使用Flask-RESTful构建RESTful API

Flask-RESTful 是一个 Flask 扩展,用于快速构建 REST API。本文基于 Flask-RESTful 0.3.6 版本。

安装

安装:

pipenv install flask-restful

Minimal App:

from flask import Flask
from flask_restful import Resource, Api

app = Flask(__name__)
api = Api(app)

class HelloWorld(Resource):
    def get(self):
        return {'hello': 'world'}

api.add_resource(HelloWorld, '/')

if __name__ == '__main__':
    app.run(debug=True)

运行:

python3 app.py

集成

与 Flask App 集成

from flask import Flask
from flask_restful import Api

app = Flask(__name__)
api = Api(app)

使用 factory function 时,可调用 flask_restful.Apiinit_app 方法:

from flask import Flask
from flask_restful import Api

api = Api()

def create_app():
    app = Flask(__name__)
    api.init_app(app)

app = create_app()

与 Blueprint 集成

from flask import Blueprint, Flask
from flask_restful import Api

app = Flask(__name__)
bp_api = Blueprint('bp_api', __name__, url_prefix='/api')
api = Api(bp_api)

app.register_blueprint(api_bp)

路由

Flask-RESTful 使用了 Flask 中的 即插视图(Pluggable Views),可参考董伟明老师《Python Web 开发实践》P40。

Flask-RESTful 中的路由以资源为中心,视图类继承自 flask_restful.Resource

from flask import Flask, request
from flask_restful import Resource, Api

app = Flask(__name__)
api = Api(app)

todos = {}

class TodoSimple(Resource):
    def get(self, todo_id):
        return {todo_id: todos[todo_id]}

    def put(self, todo_id):
        todos[todo_id] = request.form['data']
        return {todo_id: todos[todo_id]}

api.add_resource(TodoSimple, '/<string:todo_id>')

if __name__ == '__main__':
    app.run(debug=True)

解析请求参数

基本用法

Flask-RESTful 的请求解析器会在 2.0 版本被删除。

一个 demo 如下:

from flask_restful import reqparse

parser = reqparse.RequestParser()
parser.add_argument('rate', type=int, help='Rate cannot be converted')
parser.add_argument('name')
args = parser.parse_args()

首先新建解析器 reqparse.RequestParser 对象,然后使用 add_argument 方法添加参数,最后在路由方法中使用 parse_args 方法解析参数。

默认情况下,参数都是可选参数,在解析器中声明但未传入的参数值为 None

Argument 常见参数

add_argument 接受 reqparse.Argument 实例,或传递给 reqparse.Argument 构造函数的参数。

构造函数常用参数有:

  • name 参数名称
  • type 参数类型
  • required 必传参数,默认非必传
  • default 默认值
  • dest 添加到返回对象中的参数名
  • action 默认 “store”,设置为 “append” 即可将同名参数接收为一个列表
  • choices 参数可选值列表
  • trim 去掉参数头尾空格,默认不处理
  • nullable 允许参数为 None,默认不允许
  • help 参数的简短描述,在参数无效时替换默认的错误消息在响应中返回,替换默认的错误消息。可以使用 “{error_msg}” 来包含默认的错误消息。
  • location 从何种 flask.Request 对象属性中获取参数,默认为 “json” 和 “value”。多个 location 的参数会被组成为 MultiDict 对象。

自定义参数检查

可以传递一个函数给 type,在函数中对参数进行检查和处理。若参数不符合要求可抛出 ValueErrorValueError 的错误消息将在响应中返回。

parser = reqparse.RequestParser()

def odd_number(value):
    if value % 2 == 0:
        raise ValueError("Value is not odd")
    return value

parser.add_argument('OddNumber', type=odd_number)
parser.parse_args()

函数也可接收两个参数——参数值和参数名。方便于在错误消息中引用参数名。

def odd_number(value, name):
    if value % 2 == 0:
        raise ValueError(f"The parameter '{name}' is not odd. You gave us the value: {value}")
    return value

定义输出字段

基本用法

首先定义输出格式 dict,dict 中字段类型从设置为 fields中类型(会自动转换输出值)。其键是要呈现的对象上的属性或键的名称,其值是将格式化并返回该字段的值的类。

然后使用 marshal_with 装饰器绑定到请求方法上。最后在请求方法中返回数据库对象或字典即可。

from flask_restful import Resource, fields, marshal_with

resource_fields = {
    'name': fields.String,
    'address': fields.String,
    'date_updated': fields.DateTime(dt_format='rfc822'),
}

class Todo(Resource):
    @marshal_with(resource_fields, envelope='resource')
    def get(self, **kwargs):
        return db_get_todo()    # 这里的对象可以是数据库对象,或者 dict

上面这个例子中,我们假定返回的自定义的数据库对象,有 nameaddressdate_updated 属性。对象中的其他属性将不会被返回。envelope 参数指定可选的关键字参数以包装结果输出。

装饰器 marshal_with 相当于:

class Todo(Resource):
    def get(self, **kwargs):
        return marshal(db_get_todo(), resource_fields), 200

fields 常用类型

  • String(default=None, attribute=None) 字符串

  • Float(default=None, attribute=None) 浮点数

  • Boolean(default=None, attribute=None) 布尔型

  • Integer(default=0, **kwargs) 整数

  • FormattedString(src_str) 格式化字符串,自动替换 format 语法中的参数。例如:

python fields = { 'name': fields.String, 'greeting': fields.FormattedString("Hello {name}") } data = { 'name': 'Doug', } marshal(data, fields)

  • DateTime(dt_format=’rfc822’, **kwargs) UTC时间,可以输出为 ‘rfc822’ 或者 ‘iso8601’ 格式。
  • Url(endpoint=None, absolute=False, scheme=None, **kwargs) url类型,类似 Flask 的 url_for 函数
  • Fixed(decimals=5, **kwargs) 固定小数位数的浮点数,用于价格等场景
  • PriceFixed
  • Arbitrary(default=None, attribute=None) 具有任意精度的浮点数
  • Nested(nested, allow_null=False, **kwargs) 嵌套类型
  • List(cls_or_instance, **kwargs) 列表类型
  • Raw(default=None, attribute=None) 提供了一个基本字段类,自定义字段类从该字段类继承。

重命名属性

如果内部字段名称和输出字段名称不同,可以使用 attribute 参数指定内部参数名称。

指定时,可以使用字符串:

fields = {
    'name': fields.String(attribute='private_name'),
    'address': fields.String,
}

使用函数:

fields = {
    'name': fields.String(attribute=lambda x: x._private_name),
    'address': fields.String,
}

嵌套属性:

fields = {
    'name': fields.String(attribute='people_list.0.person_dictionary.name'),
    'address': fields.String,
}

增加默认值

使用 default 参数为输出增加默认值。仅有部分类型支持。

fields = {
    'name': fields.String(default='Anonymous User'),
    'address': fields.String,
}

自定义字段值

自定义字段需要继承 fields.Raw类并实现format方法。这对于使用整数存储的标识位字段非常有用。

class UrgentItem(fields.Raw):
    def format(self, value):
        return "Urgent" if value & 0x01 else "Normal"

class UnreadItem(fields.Raw):
    def format(self, value):
        return "Unread" if value & 0x02 else "Read"

fields = {
    'name': fields.String,
    'priority': UrgentItem(attribute='flags'),
    'status': UnreadItem(attribute='flags'),
}

复杂结构

除了输出简单的一层 k-v 结构之外,也可以输出嵌套结构。

resource_fields = {'name': fields.String}
resource_fields['address'] = {}
resource_fields['address']['line 1'] = fields.String(attribute='addr1')
resource_fields['address']['line 2'] = fields.String(attribute='addr2')
resource_fields['address']['city'] = fields.String
resource_fields['address']['state'] = fields.String
resource_fields['address']['zip'] = fields.String

data = {
    'name': 'bob',
    'addr1': '123 fake street',
    'addr2': '',
    'city': 'New York',
    'state': 'NY',
    'zip': '10468'
}

result = marshal(data, resource_fields)

# result
{
    "name": "bob",
    "address":{
        "line 1": "123 fake street",
        "line 2": "",
        "state": "NY",
        "zip": "10468",
        "city": "New York"
    }
}

地址字段实际上并不存在于数据对象上,但是任何子字段都可以直接从对象访问属性,就好像它们没有嵌套一样。

列表字段

使用 fields.List 输出列表字段。

>>> from flask_restful import fields, marshal
>>> import json
>>>
>>> resource_fields = {'name': fields.String, 'first_names': fields.List(fields.String)}
>>> data = {'name': 'Bougnazal', 'first_names' : ['Emile', 'Raoul']}
>>> json.dumps(marshal(data, resource_fields))
>>> '{"first_names": ["Emile", "Raoul"], "name": "Bougnazal"}'

输出列表

有时,我们可能不想要输出 dict,而是要直接输出列表,可以利用 fields.Listfields.Nested 配合输出列表。

此时要使用 marshal_with_field 装饰器。

resource_fields = {'name': fields.String, 'age': fields.Integer}
resource_list_fields = fields.List(fields.Nested(product_fields))

class ResourceList(Resource):
    @marshal_with_field(resource_list_fields)
    def get(self):
        data = [
            dict(name='aaa', age=14),
            dict(name='bbb', age=15),
        ]
        return data

参考文档

目录