10.第十四章Flask-Restful

14.1 第一节 Restful API规范

restful api是用于在前端与后台进行通信的一套规范。使用这个规范可以让前后端开发变得更加轻松。以下将讨论这套规范的一些设计细节。

协议：

采用http或者https协议。

数据传输格式：

数据之间传输的格式应该都使用json，而不使用xml。

url链接：

url链接中，不能有动词，只能有名词。并且对于一些名词，如果出现复数，那么应该在后面加s。

比如：获取文章列表，应该使用/articles/，而不应该使用/get_article/

HTTP请求的方法：

  1. GET：从服务器上获取资源。
  2. POST：在服务器上新创建一个资源。
  3. PUT：在服务器上更新资源。（客户端提供所有改变后的数据）
  4. PATCH：在服务器上更新资源。（客户端只提供需要改变的属性）
  5. DELETE：从服务器上删除资源。

示例如下：

  • GET /users/：获取所有用户。
  • POST /user/：新建一个用户。
  • GET /user/id/：根据id获取一个用户。
  • PUT /user/id/：更新某个id的用户的信息（需要提供用户的所有信息）。
  • PATCH /user/id/：更新某个id的用户信息（只需要提供需要改变的信息）。
  • DELETE /user/id/：删除一个用户。

状态码：

状态码 原生描述 描述
200 OK 服务器成功响应客户端的请求。
400 INVALID REQUEST 用户发出的请求有错误，服务器没有进行新建或修改数据的操作
401 Unauthorized 用户没有权限访问这个请求
403 Forbidden 因为某些原因禁止访问这个请求
404 NOT FOUND 用户发送的请求的url不存在
406 NOT Acceptable 用户请求不被服务器接收（比如服务器期望客户端发送某个字段，但是没有发送）。
500 Internal server error 服务器内部错误，比如出现了bug

14.2 第二节 Flask-Restful插件

介绍：

Flask-Restful是一个专门用来写restful api的一个插件。使用他可以快速的集成restful api功能。在app的后台以及纯api的后台中，这个插件可以帮助我们节省很多时间。当然，如果在普通的网站中，这个插件就显得有些鸡肋了，因为在普通的网页开发中，是需要去渲染HTML代码的，而Flask-Restful在每个请求中都是返回json格式的数据。

安装：

Flask-Restful需要在Flask 0.8以上的版本，在Python2.6或者Python3.3上运行。通过pip install flask-restful即可安装。

定义Restful的视图：

如果使用Flask-Restful，那么定义视图函数的时候，就要继承自flask_restful.Resource类，然后再根据当前请求的method来定义相应的方法。比如期望客户端是使用get方法发送过来的请求，那么就定义一个get方法。类似于MethodView。示例代码如下：

from flask import Flask,render_template,url_for
from flask_restful import Api,Resource

app = Flask(__name__)
# 用Api来绑定app
api = Api(app)

class IndexView(Resource):
    def get(self):
        return {"username":"zhiliao"}

api.add_resource(IndexView,'/',endpoint='index')

注意事项：

  1. endpoint是用来给url_for反转url的时候指定的。如果不写endpoint，那么将会使用视图的名字的小写来作为endpoint。
  2. add_resource的第二个参数是访问这个视图函数的url，这个url可以跟之前的route一样，可以传递参数。并且还有一点不同的是，这个方法可以传递多个url来指定这个视图函数。

参数解析：

Flask-Restful插件提供了类似WTForms来验证提交的数据是否合法的包，叫做reqparse。以下是基本用法：

parser = reqparse.RequestParser()
parser.add_argument('username',type=str,help='请输入用户名')
args = parser.parse_args()

add_argument可以指定这个字段的名字，这个字段的数据类型等。以下将对这个方法的一些参数做详细讲解：

  1. default：默认值，如果这个参数没有值，那么将使用这个参数指定的值。
  2. required：是否必须。默认为False，如果设置为True，那么这个参数就必须提交上来。
  3. type：这个参数的数据类型，如果指定，那么将使用指定的数据类型来强制转换提交上来的值。
  4. choices：选项。提交上来的值只有满足这个选项中的值才符合验证通过，否则验证不通过。
  5. help：错误信息。如果验证失败后，将会使用这个参数指定的值作为错误信息。
  6. trim：是否要去掉前后的空格。

其中的type，可以使用python自带的一些数据类型，也可以使用flask_restful.inputs下的一些特定的数据类型来强制转换。比如一些常用的：

  1. url：会判断这个参数的值是否是一个url，如果不是，那么就会抛出异常。
  2. regex：正则表达式。
  3. date：将这个字符串转换为datetime.date数据类型。如果转换不成功，则会抛出一个异常。

输出字段：

对于一个视图函数，你可以指定好一些字段用于返回。以后可以使用ORM模型或者自定义的模型的时候，他会自动的获取模型中的相应的字段，生成json数据，然后再返回给客户端。这其中需要导入flask_restful.marshal_with装饰器。并且需要写一个字典，来指示需要返回的字段，以及该字段的数据类型。示例代码如下：

class ProfileView(Resource):
    resource_fields = {
        'username': fields.String,
        'age': fields.Integer,
        'school': fields.String
    }

    @marshal_with(resource_fields)
    def get(self,user_id):
        user = User.query.get(user_id)
        return user

在get方法中，返回user的时候，flask_restful会自动的读取user模型上的username以及age还有school属性。组装成一个json格式的字符串返回给客户端。

重命名属性：

很多时候你面向公众的字段名称是不同于内部的属性名。使用 attribute可以配置这种映射。比如现在想要返回user.school中的值，但是在返回给外面的时候，想以education返回回去，那么可以这样写：

resource_fields = {
    'education': fields.String(attribute='school')
}

默认值：

在返回一些字段的时候，有时候可能没有值，那么这时候可以在指定fields的时候给定一个默认值，示例代码如下：

resource_fields = {
    'age': fields.Integer(default=18)
}

复杂结构：

有时候想要在返回的数据格式中，形成比较复杂的结构。那么可以使用一些特殊的字段来实现。比如要在一个字段中放置一个列表，那么可以使用fields.List，比如在一个字段下面又是一个字典，那么可以使用fields.Nested。以下将讲解下复杂结构的用法：

class ProfileView(Resource):
    resource_fields = {
        'username': fields.String,
        'age': fields.Integer,
        'school': fields.String,
        'tags': fields.List(fields.String),
        'more': fields.Nested({
            'signature': fields.String
        })
    }