V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
nuance2ex
V2EX  ›  程序员

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

  •  1
     
  •   nuance2ex · 2019-03-31 00:50:15 +08:00 · 3599 次点击
    这是一个创建于 2044 天前的主题,其中的信息可能已经有所发展或是发生改变。

    [ 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-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/

    14 条回复    2019-10-06 08:57:59 +08:00
    di94sh
        1
    di94sh  
       2019-03-31 01:08:37 +08:00 via Android
    flask restful 注册错误处理是是失效的。
    lynskylate
        2
    lynskylate  
       2019-03-31 02:06:13 +08:00 via Android
    相比 django rest framework 如何?
    ryd994
        3
    ryd994  
       2019-03-31 02:40:29 +08:00 via Android
    主管拒绝接受此规范
    congeec
        4
    congeec  
       2019-03-31 03:46:55 +08:00
    程序员拒绝接受此规范
    plqws
        5
    plqws  
       2019-03-31 06:31:02 +08:00
    Patreon 的 API 就是这个规范的,其实用起来挺让人奔溃的,看起来不错而已,实际用起来的话会发现极其不灵活
    Abbeyok
        6
    Abbeyok  
       2019-03-31 07:27:11 +08:00 via Android
    API 用 jsonify 咋样?
    jisibencom
        7
    jisibencom  
       2019-03-31 08:29:15 +08:00 via Android
    不是太懂,现在接口太多,如何灵活调用有没有通用的软件或工具,php,python
    forestLittleBear
        8
    forestLittleBear  
       2019-03-31 09:19:17 +08:00 via Android
    @jisibencom 官方文档。
    TommyLemon
        9
    TommyLemon  
       2019-03-31 18:55:47 +08:00
    先收藏一下
    nuance2ex
        10
    nuance2ex  
    OP
       2019-03-31 23:42:26 +08:00 via iPhone
    @lynskylate django rest 对标的是 flask-restful。从灵活度的角度来说,可以自由拓展;但灵活性的另一面就是封装程度低,什么都要自己实现。
    nuance2ex
        11
    nuance2ex  
    OP
       2019-03-31 23:48:45 +08:00 via iPhone
    @plqws 这个规范返回的 JSON 数据层次比较冗余,客户端直接提数据比较麻烦,最好用实现该规范的反序列解析器。我自己写完客户端解析器后,发现其实已经有现成的 JS 轮子了。
    nuance2ex
        12
    nuance2ex  
    OP
       2019-03-31 23:52:09 +08:00 via iPhone
    @Abbeyok 简单接口可以用 jsonify,一旦项目复杂起来,可复用性和可维护性就会骤降。
    Outliver0
        13
    Outliver0  
       2019-05-27 13:39:46 +08:00
    @nuance2ex 老哥,有翻译好吗,我来学习
    nuance2ex
        14
    nuance2ex  
    OP
       2019-10-06 08:57:59 +08:00 via iPhone
    @Outliver0 来自越时空的回复。已经翻译好了。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1197 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 24ms · UTC 18:24 · PVG 02:24 · LAX 11:24 · JFK 14:24
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.