• 主页: https://apiflask.com
• GitHub: https://github.com/greyli/apiflask
• Twitter: https://twitter.com/apiflask

APIFlask 在 Flask 的基础上添加了更多 Web API 相关的功能支持，核心特性包括：

• 更多方便的装饰器，比如 @app.input()、@app.output()、@app.get()、@app.post() 等等
• 自动反序列化和验证请求格式，当请求数据不符合模式类要求时，会自动生成包含错误详细信息的错误响应（基于 Webargs）
• 自动格式化和序列化响应数据，在定义好响应模式后，你可以直接在视图函数返回一个模型类对象，或是返回字典（基于 Marshmallow）
• 自动生成 OpenAPI Specification 文件，你可以把这个文件导入到 API 调试工具或是用来生成客户端代码（基于 APISpec）
• 自动生成交互式 API 文档，并自动为蓝本和视图设置对应的标签分类（基于 Swagger UI and Redoc）
• 自动为 HTTP 错误生成 JSON 格式的错误响应

下面是一个最基础的示例程序：

 from apiflask import APIFlask, Schema, abort
 from apiflask.fields import Integer, String
 from apiflask.validators import Length, OneOf
 ​
 app = APIFlask(__name__)  # 可以使用 title 和 version 参数来自定义 API 的名称和版本
 ​
 pets = [
     {
         'id': 0,
         'name': 'Kitty',
         'category': 'cat'
     },
     {
         'id': 1,
         'name': 'Coco',
         'category': 'dog'
     }
 ]
 ​
 # 定义一个请求数据模式类
 class PetInSchema(Schema):
     name = String(required=True, validate=Length(0, 10))  # 可以使用 description 参数添加字段描述
     category = String(required=True, validate=OneOf(['dog', 'cat']))
 ​
 # 定义一个响应数据模式类
 class PetOutSchema(Schema):
     id = Integer()
     name = String()
     category = String()
 ​
 ​
 @app.get('/pets/<int:pet_id>')
 @app.output(PetOutSchema)  # 使用 @output 装饰器标记响应数据模式
 def get_pet(pet_id):
     if pet_id > len(pets) - 1:
         abort(404)
     # 在真实程序里，你可以直接返回 ORM 模型类的实例，比如
     # return Pet.query.get(1)
     return pets[pet_id]
 ​
 ​
@app.patch('/pets/<int:pet_id>')
@app.input(PetInSchema(partial=True))  # 使用 @input 装饰器标记请求数据模式
@app.output(PetOutSchema)
def update_pet(pet_id, json_data):  # 通过验证后的请求数据字典会注入到视图函数，默认参数名为 json_data
    if pet_id > len(pets) - 1:
        abort(404)
    for attr, value in json_data.items():
        pets[pet_id][attr] = value
    return pets[pet_id]

P.S. 你也可以使用类视图（class-based views），具体示例见这里。

如果你想在你的电脑上运行这个示例，可以先用下面的命令安装 APIFlask（需要 Python 3.7 及以上版本，Flask 1.1 及以上版本）：

Linux 和 macOS:

 $ pip3 install apiflask

Windows:

 > pip install apiflask

安装完成后把上面的代码保存到文件 app.py，然后执行下面的命令运行程序：

 $ flask run

现在你可以在浏览器访问 http://localhost:5000/docs 查看基于 Swagger UI 自动生成的交互式 API 文档：

或者访问 http://localhost:5000/redoc 查看基于 Redoc 生成的 API 文档：

访问 http://localhost:5000/openapi.json 可以获取自动生成的 OpenAPI spec 文件。

这个示例程序的完整版本可以在 https://github.com/greyli/apiflask/tree/master/examples 看到。如果你想了解更多用法，可以阅读文档中的基本用法一章（目前只有英文）。

APIFlask 只在 Flask 之上做了轻量级包装，所以你实际上仍然是在写一个 Flask 程序，所有 Flask 的特性都完全兼容。你只需要记住下面两处不同点：

• 创建程序实例的时候使用 APIFlask 类（from apiflask import APIFlask）。
• 创建蓝本实例的时候使用 APIBlueprint 类（from apiflask import APIBlueprint）。
• 使用 apiflask.abort() 函数返回 JSON 格式的错误响应。

以下面的 Flask 程序为例：

 from flask import Flask, request, escape
 ​
 app = Flask(__name__)
 ​
 @app.route('/')
 def hello():
     name = request.args.get('name', 'Human')
     return f'Hello, {escape(name)}'

迁移到 APIFlask 只需要改动两行代码：

 from apiflask import APIFlask  # 第一行
 from flask import request, escape
 ​
 app = APIFlask(__name__)  # 第二行
 ​
 @app.route('/')
 def hello():
     name = request.args.get('name', 'Human')
     return f'Hello, {escape(name)}'

欢迎提出改进建议，报告 bug 或是分享其他任何相关的想法。你也可以在 GitHub 上创建 Issue，或是提交 PR 来改进它。谢谢！

为什么要再写一本 Flask 书？

尽管我很想早一点深入学习更多的东西，而不是局限在 Flask（或 Python） 领域，但事实是，在这一个领域就已经有太多的东西需要研究和学习……目前来说，我最想解决的就是 Web API 的编写问题。《Flask Web 开发实战》虽然在第十章介绍了 Web API 的大部分基础概念，但是只实现了一种 OAuth 认证流程，也没能深入更多内容，包括数据校验、请求封装等。因此，我决定再写一本书来覆盖这个主题。

另一个原因是，我在上一本书的电商页面、豆瓣条目还有其他地方收集到了一些批评，其中有一些很中肯，所以我想写一本更好的 Flask 书。除了克服这些批评里提到的缺点，我也会尝试更科学的写作方式，不会像上一本书那样在早期印刷版本包含那么多的笔误和疏漏。

作为试水，我在 PyCon China 2019 上海场会有一个相关主题的演讲：《基于 Flask 的 Web API 开发指南》，如果你感兴趣的话，可以考虑报名参加。

新书会包含哪些内容？

不同于《Flask Web 开发实战》所追求的大而全，这本书的定位是一个小而精的 Flask 书。它会包含下面这几部分：

• 一个更轻松简单的入门部分。
• 进阶部分：开发一个传统 Web 程序。
• 作为重点的 Web API 开发部分。
• Flask 相关的进阶部分，包括缓存、异步任务、容器部署等。
• 可能会加入的其他内容：FastAPI、Django REST Framework、GraphQL。

这本书一来可以衔接《Flask 入门教程》，二来可以补充《Flask Web 开发实战》没有覆盖的内容。当然，对于学习 Flask，囊括几乎所有相关主题的《Flask Web 开发实战》仍然是一个不错的选择。

对于相同的主题，我会考虑使用不同的工具，比如《Flask Web 开发实战》里单元测试使用 unitttest，那么这本书就会介绍用 pytest；上一本书里编辑器介绍使用 PyCharm，这一本书或许就会介绍使用 VSCode。

下面是这本书的其他具体设计：

• 只使用一个示例程序，贯穿全书。
• 使用中文作为示例程序的界面语言。
• 使用 Python3，但在书中对 Python2 兼容部分添加必要的提示。
• 对书中的代码块添加尽可能多的注释。
• 添加一个「术语表」，收集所有 Flask 和 Web 开发相关的术语，尝试给它们下一个简单易懂的定义。
• 添加一个「常见错误速查表」，列出常见错误、错误解释和对应的解决方法（在维护上一本书的时间里，我处理了大量提问，见识过各种错误和误区）。

作为后续，在这本书完成后，我计划写一本电子书来介绍如何使用 Vue.js 基于这本 Flask 书编写的 Web API 来开发客户端。尽管我现在还没入门 Vue.js……但是我已经把放相关内容的网站域名准备好了：HelloVuejs.com（它和 HelloFlask.com 是兄弟域名 :p）

什么时间能完成？

预计的发售时间是明年愚人节，即 2020 年 4 月 1 日。因为 Flask 的诞生时间是 2010 年的愚人节，所以明年愚人节会是 Flask 诞生十周年纪念日，一个很完美的发售时间。

如果你对这本书感兴趣，可以关注我的微信公众号、Twitter 和豆瓣账号获取最新动态，或是访问这本书的主页。

2020/4/1 更新：Flask 新书完成时间推迟

你想看到什么内容？

在公开上一本写作消息的文章里，我征集到了大约 40 条建议，虽然没能完全采纳，但我都一一考虑过这些很有价值的建议。对于这本新书，在内容、形式或是其他任何方面，你有什么意见和建议？欢迎发评论分享你的想法，谢谢。