[JSON API 1.0 规范] Flask-REST-JSONAPI 一个让你和主管停止争吵的轮子！

[ JSON API 1.0 规范] Flask-REST-JSONAPI 一个让你和主管停止争吵的轮子！

和主管为一个接口输出真吵了一天，搞得都想离职，求怎么破 https://www.v2ex.com/t/546096?p=1

JSON API 1.0 规范官网第一句话：“ If you ’ ve ever argued with your team about the way your JSON responses should be formatted, JSON:API can be your anti-bikeshedding tool.” “如果你和你的团队曾经争论过使用什么方式构建合理 JSON 响应格式，那么 JSON API 规范就是你的核武器。”

最近开发一个 CRM 项目，后端 API 服务器一开始在Flask-Restful和Flask-Restless之间纠结，由于 Flask-Restful 封装程度低，需要自己实现的功能太多；纠结地选择了数据库映射型框架Flask-Restless，这个框架至少实现了 JSON API 1.0 规范。可结果发现是个天坑！！外键查询，只能逐条查询，不支持联表或自定义查询方式！ Github issue 里 2016 年就有人反应过这个问题，作者也表示是设计架构问题，无能为力。

绝望，感觉要自己徒手造个摩天轮了。

曙光，就在这个 issue 下面，有人表示已经将项目完整迁移到 Flask-REST-JSONAPI，一个完全陌生的框架，至少国内完全搜不到这个框架。

我查了下，**文档齐全！规范标准！层次清晰！拓展容易！**感觉就是 Flask 中的 Flask。

框架遵循 Restful JSON API 1.0 规范，意味着在客户端也有实现该规范的轮子可以用！而且 Flask-REST-JSONAPI 这个框架真的好用到爆炸！作者一句话总结他的框架：

"It combines the power of Flask-Restless and the flexibility of Flask-RESTful around a strong specification JSONAPI 1.0."

结合了 Flask-Restless 的能力和 Flask-RESTful 的灵活性，并且严格遵守 JSONAPI 1.0 规范。

写完了一个项目，总结下这个框架优点：

层次清晰：框架内部分为资源层、逻辑数据抽象层（数据结构层）和数据库层。

例：一个 PATCH 请求，先从 Flask 路由层 users/me 映射到自定义的资源层 user_detail_resource；再经过资源层对应的数据结构层 user_schema，Schema 定义了 api 的数据结构，验证数据是否规范、完整，并反序列化把数据变成 Python 对象；再将 Python 对象传入数据层，更新数据；最后更新完成后，再返回给数据结构层 user_schema 序列化，把 Python 对象变成 JSON 数据，并将更新后的完整数据返回客户端。
可定制程度高：在数据结构层，框架使用的是 Marshmallow-jsonapi 进行序列化和反序列化；如果你们有自己独特的 JSON 数据规范，也可以自己定制自己的序列化包；在数据库层，框架实现了 Sqlalchemy 的增删改查，其实只要实现了基类的接口，你可以使用自己的数据库层，为专门的资源做专门 sql 优化，甚至替换任何数据库或 ORM。
拓展性强：框架在资源层和数据库都预留了 before、after 的钩子函数，比如before_post，before_create_object；而且预留了统一的权限钩子。
文档齐全：仅依靠官方文档，完全可以开始自己的项目。

规范标准：框架完全实现了 JSONAPI 1.0 规范，实现了条件查询、外键查询、按需查询、排序和分页。

# 条件查询：查询名字叫 John 的人
GET /persons?filter=[{"name":"name","op":"eq","val":"John"}] 

# 外键查询：查询结果包含外键 Computers
GET /persons/1?include=computers

# 按需查询: 仅返回人的名字
GET /persons?fields[person]=display_name

# 排序：结果按年龄排序
GET /persons?sort=age

作为回馈，近期我将启动文档翻译工作，希望如此优质的框架和规范能被更多人用上。

Github：https://github.com/miLibris/flask-rest-jsonapi

文档：https://flask-rest-jsonapi.readthedocs.io/en/latest/