Flask之restful

• Rest

  • rest 是一组架构约束条件和原则 ，是Roy Thomas Fielding在他2000年的博士论文中提出的。直译的话，rest是表现层状态转移，其实说白了就是通过URL定位资源，利用HTTP动词（GET， POST等）描述操作。
  • 而其核心就是资源（Resource），而URL的指向就是它，因此要获取资源，访问URL就可以了。

• Restful API架构

  • 满足restful风格设计的API（应用程序接口，由服务器提供）
  • restful表示的是一种以网络为基础的应用软件的架构设计
  • restful的特点
    • 每一个URI代表一种资源；
    • 客户端和服务器之间，传递这种资源的某种表现层（就是将资源具体呈现出来的形式）；
    • 客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。
    • 对应的restfulAPI标准接口
      • GET 检索资源列表 http://[hostname]/todo/api/v1.0/items
      • GET 检索某个特定资源 http://[hostname]/todo/api/v1.0/items/[item_id]
      • POST 创建新资源 http://[hostname]/todo/api/v1.0/items
      • PUT 更新资源 http://[hostname]/todo/api/v1.0/items/[item_id]
      • DELETE 删除资源 http://[hostname]/todo/api/v1.0/items/[item_id]
    • 针对上边的几种API接口的返回结果，返回状态码等，有一些规则说明：
      • GET检索资源列表，返回一个资源数组或字典，并返回状态码200，表示请求成功。
      • GET检索某个特定资源，返回单个资源，并返回状态码200，表示请求成功。
      • POST创建新资源，返回创建后的资源，并返回状态码201，表示资源创建成功。
      • PUT更新资源，返回更新后的资源，并返回状态码201，表示资源更新成功。
      • DELETE删除资源，返回空，并返回状态码204，表示资源删除成功，服务器已无该资源。

  • Flask-Restful

    • flask-restful是flask的扩展，增加了对快速构建restAPI的支持，可以与ORM库进行结合使用。
    • 因此在开发使用时，直接使用pip install flask-restful 进行安装

    • flask-restful整体介绍

      • import os
        
        from flask import jsonify
        from flask_restful import Resource, marshal_with, fields, reqparse, inputs
        from werkzeug.datastructures import FileStorage
        
        
        from apps.user.model import User
        from config import Config
        from exts import db
        # 蓝图可以极大地简化大型应用程序的工作方式并为Flask扩展提供了一种集中的方式来注册应用程序上的操作。
        api_bp = Blueprint('api', __name__)
        api = Api(api_bp)
        
        # 订制需要在界面上显示的内容或者说是输出字段
        # fields 是一种控制响应数据的一种类似于字典的格式，也可以进行过滤和格式化数据
        # attribute='private_name' 表示为了不显示数据库中具体的字段名，可以使用此参数来对显示字段进行重命名， 也可以用lambda指定
        # fields.Url它为请求的资源综合了一个uri，表示连接的下属具体内容，其参数是必须要包含跳转的路由， absolute=True表示加主机名和端口以及路由的绝对路径
        user_fields = {
            'id': fields.Integer,			# 整型
            'uasername': fields.String（attribute='private_name'）,		# 字符串
            'create_time': fields.DateTime, # 时间
            'email': fields.String,
            'phone': fields.String，
            'url': fields.Url('news.newsdetail', absolute=True)   # 该新闻的详情
        }
        user_list_fields = {
        fields.List(fields.Nested(user_fields)),  表示该Nested构造函数将字段的字典内呈现为子字段：表如说在查看一篇文章时，除了查看文章本身的内容之外，还要看它的评论以及回复，这时就可以使用List对象和Nested对象嵌套评论和回复的输出字段
        }
        # 自定义fields类型（继承 fields.Raw该类并实现该format功能）当属性存储多条信息时使用
        class AuthorName(fields.Raw):
            def format(self, value):
                return value.username
                
        # 参数解析
        # bundle_errors=True，表示通过解析数据，数据出错时将错误信息一起发送给客户端，若为False则是只发送一条错误信息
        # reqparse 提供对flask.requestFlask中对象的所有变量的统一访问
        # 也是对前端传进的数据进行验证，类似于form
        # help 表示在解析前端传进的数据时，出现错误时为其提示错误的消息
        # type 表示前端传入数据的类型， required=True表示必需传入
        # action='append' 表示可以传入多个值作为列表
        # location=['files'] 表示对字段的请求作出限制，以什么方式请求或者表示获取自变量的对象属性（文件，或者headers等）
        # reset_parser = parser.copy() 表示继承（即在解析数据时若遇相同的参数，可以通过浅复制来共享参数）
        parser = reqparse.RequestParser(bundle_errors=True)     # bundle_errors=True 表示出错的所有提示信息
        parser.add_argument('username', type=str, required=True, help='请填用户名，必填')
        parser.add_argument('phone', type=inputs.regex(r'^1[356789]\d{9}$'), required=True, help='请填写手机号码，必填')
        parser.add_argument('email', required=True, help='请填邮箱，必填')     # type=inputs.regex() 表示进一步验证字段是否否合正则表达式
        parser.add_argument('password', required=True, help='请填写密码，必填')
        parser.add_argument('hobby', action='append')  # action='append' 表示可添加多个值
        parser.add_argument('icon', type=FileStorage, location=['files'])   
        reset_parser = parser.copy()
        
        # 统一路由部分：http://127.0.0.1:5000/， 处理用户集合
        class UsersResource(Resource):
        
            @marshal_with(user_fields)   # 用来控制返回的数据格式是json格式和在界面显示的内容
            def get(self):
                users = User.query.all()
                return users             # 使用marshal_with后会直接返回json格式
        
            @marshal_with(user_fields)
            def post(self):
                args = parser.parse_args()  # 获取经过argument验证过得字段
                username = args.get('username')
                password = args.get('password')
                phone = args.get('phone')
                email = args.get('email')
                icon = args.get('icon')
        
                user = User()
                user.username = username
                user.password = password
                user.phone = phone
                user.email = email
                if icon:
                    upload_path = os.path.join(Config.UPLOAD_ICON_DIR, icon.filename)  # 获取图片的保存路径
                    icon.save(upload_path)
                    user.icon = os.path.join('upload/icon', icon.filename)      # 数据库存图片的保存路径
                db.session.add(user)
                db.session.commit()
                return user
        
            def put(self):
                pass
        
            def delete(self):
                pass
        
        
        # 处理单个用户
        class UserResource(Resource):
        
            @marshal_with(user_fields)   # 用来控制返回的数据格式和内容
            def get(self, id):
                return
        
            def post(self, id):
                pass
        
            def put(self, id):
                pass
        
            def delete(self, id):
                pass
        
        api.add_resource(UsersResource, '/user')   # 添加路由
        api.add_resource(NewsDetailApi, '/newsdetail/<int:id>', endpoint='newsdetail') # endpoint 可以将路径的某些部分作为资源方法的变量进行匹配