Flask-REXTx 学习笔记——1.响应编组（Response marshalling）

记录对Flask-REXTx的学习笔记

简介

Flask-RESTx是一个基于Flask的扩展，它提供了一些额外的功能来帮助开发人员更轻松地构建强大的RESTful API。这些功能包括API文档的自动生成、请求参数解析和API资源管理等。Flask-RESTx的目标是在维护API时能够提供更好的文档和工具支持。
它是Flask-RESTful的增强版（实际上是因为lask-RESTful的开发者在GitHub上迟迟不处理BUG和优化，所以有人做了一个分支开发了Flask-RESTx），完全兼容Flask-RESTPlus，提供了更规范化的接口编写方式，并支持Swagger文档，这使得API的设计和文档化更加清晰和简便。

用 Flask-RESTx 还是蓝图 blueprint？

我的项目之前是用蓝图来构建和组织后端结构的，但是它缺少RESTful API的某些特定支持，例如基于Swagger的接口文档自动生成。
随着项目体量增大，不便于开发人员查阅和参考，也没有可供调试的接口。最重要的是，新人没有一个快速入手的文档以供查询，基本都靠口口相传。
加上虽然我们的后端设计思想是符合 RESTful AIP的，但是API 文档也是它的一个重要部分。
所以基于以上原因，决定引入 Flask-RESTx。之后新内容用 Flask-RESTx，旧内容依旧用蓝图，目前不改动。

响应编组（Response marshalling）

基本用法：
i.api.model + api.marshal_with(model, envelope)
ii.envelope 会将输出按对应参数进行一层字典包装

from flask_restx import Resource, fieldsmodel = api.model('Model', {'name': fields.String,'address': fields.String,'date_updated': fields.DateTime(dt_format='rfc822'),
})@api.route('/todo')
class Todo(Resource):@api.marshal_with(model, envelope='resource') // 这里的最终输出变成 {'resource': db_get_todo()}def get(self, **kwargs):return db_get_todo()  # Some function that queries the db

重命名属性
i.通常，面向公众的字段名称与内部字段名称不同。要配置此映射
ii.也可以使用匿名函数或者嵌套属性

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

默认值

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

自定义字段和多个值：适合特定的格式需求

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"model = {'name': fields.String,'priority': UrgentItem(attribute='flags'),'status': UnreadItem(attribute='flags'),
}

Url 和其他具体字段

model = {'name': fields.String,'uri': fields.Url('', absolute=True), // 能返回当前访问的url，absolute参数可以返回完整的url
}

复杂结构
i.marshal() 将一个平面结构的 data 转换成复杂结构

from flask_restx import fields, marshal
import json
resource_fields = {'name': fields.String,'address': {'line 1': fields.String(attribute='addr1'),'line 2': fields.String(attribute='addr2'),'city': fields.String,'state': fields.String,'zip': fields.String}
}@api.route('/test')
class testMarshal(Resource):def post(self):data = {'name': 'bob', 'addr1': '123 fake street', 'addr2': '', 'city': 'New York', 'state': 'NY', 'zip': '10468'}return marshal(data, resource_fields)

通配符字段
i.只关心值的类型，不关心key的名称时，使用 Wildcard 构建。
ii.注意这里不是正则表达式，只能简单使用 * 和 ?。

>>> from flask_restx import fields, marshal
>>> import json
>>>
>>> wild = fields.Wildcard(fields.String)
>>> wildcard_fields = {'*': wild}
>>> data = {'John': 12, 'bob': 42, 'Jane': '68'}
>>> json.dumps(marshal(data, wildcard_fields))
>>> '{"Jane": "68", "bob": "42", "John": "12"}'>>> wildcard_fields = {'j*': wild}
>>> data = {'John': 12, 'bob': 42, 'Jane': '68'}
>>> json.dumps(marshal(data, wildcard_fields))
>>> '{"Jane": "68", "John": "12"}'