Back
Featured image of post 【JSON API 1.0规范】Flask-REST-JSONAPI 一个让你和主管停止争吵的轮子!

【JSON API 1.0规范】Flask-REST-JSONAPI 一个让你和主管停止争吵的轮子!

JSON API规范就是你的核武器。

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-RestfulFlask-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_postbefore_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/

沪ICP备20004885号-2
jonathan.nuance@outlook.com
Built with Hugo
Theme Stack designed by Jimmy