Flask-Marshmallow：Flask 接口序列化的一层薄胶水

Flask-Marshmallow 在 GitHub 上积累了 891 个 Star。它是 marshmallow 序列化库与 Flask 框架之间的薄集成层，专门解决 API 返回数据的格式化问题。

1、 它解决了什么问题

写 Flask 接口时，返回数据库对象给前端是个重复劳动。手动拼装 JSON 字段，处理日期格式，加上分页和链接信息，代码越写越长。

Flask-Marshmallow 把这个过程收进 Schema 定义里。模型字段和输出格式分开维护，修改接口返回内容时不用动业务逻辑。

2、 核心功能

它的能力分两块。一是基础的序列化/反序列化，把 SQLAlchemy 模型对象转成 JSON 响应。二是超链接字段，让 API 返回自带导航信息。

Hyperlinks 字段可以生成 RESTful 风格的自引用链接。比如用户详情接口返回的数据里，自动带上 self 指向当前资源，collection 指向列表接口。这对构建 HATEOAS 架构的 API 很直接。

它也支持可选的 Flask-SQLAlchemy 集成，ORM 模型可以直接套 Schema，省去中间转换。

3、 安装与使用

安装一行命令：

pip install flask-marshmallow

初始化：

from flask import Flask
from flask_marshmallow import Marshmallow

app = Flask(__name__)
ma = Marshmallow(app)

定义模型和 Schema：

class UserSchema(ma.Schema):
    email = ma.Email()
    date_created = ma.DateTime()

    _links = ma.Hyperlinks({
        "self": ma.URLFor("user_detail", values=dict(id="<id>")),
        "collection": ma.URLFor("users"),
    })

接口里直接 dump：

@app.route("/api/users/<id>")
def user_detail(id):
    user = User.get(id)
    return user_schema.dump(user)

返回的数据长这样：

{
    "email": "fred@queen.com",
    "date_created": "Fri, 25 Apr 2014 06:02:56 -0000",
    "_links": {
        "self": "/api/users/42",
        "collection": "/api/users/"
    }
}

4、 适合谁用

• 用 Flask 写 REST API，需要统一数据输出格式的开发者
• 想给 API 响应加上 HATEOAS 链接，又不想手写 URL 拼接逻辑的人
• 已经在用 Flask-SQLAlchemy，希望模型到 JSON 的转换更轻量的项目

这个项目文档托管在 Read the Docs 上，PyPI 可直接安装，协议是 MIT。代码量不大，但正好填补了 Flask 生态里序列化这层空缺。

的项目

这个项目文档托管在 Read the Docs 上，PyPI 可直接安装，协议是 MIT。代码量不大，但正好填补了 Flask 生态里序列化这层空缺。