APIFlask：一个基于 Flask 的 Web API 框架

vlambda
2021-04-11

APIFlask：一个基于 Flask 的 Web API 框架

经常看到有人把 FastAPI 和 Flask 放到一起比较，但是却没有意识到这完全是两种东西——前者是基于 Web 框架 Starlette 添加了 Web API 功能支持的（框架之上的）框架，而后者是和 Starlette 同类的通用 Web 框架。你怎么能让小明和骑电动车的小军赛跑然后还夸小军好快好强？为了让框架 PK 爱好者们有一个更公平的比较对象，从一份 APIFairy 0.6.2 版本的 fork 开始，我实现了一个基于 Flask 的 Web API 框架——APIFlask：

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

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

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

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

 from apiflask import APIFlask, Schema, input, output, abort_json
 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>')
 @output(PetOutSchema) # 使用 @output 装饰器标记响应数据模式
 def get_pet(pet_id):
 if pet_id > len(pets) - 1:
 abort_json(404)
 return pets[pet_id]
 
 
 @app.post('/pets/<int:pet_id>')
 @input(PetInSchema) # 使用 @input 装饰器标记请求数据模式
 @output(PetOutSchema)
 def update_pet(pet_id, data): # 通过验证后的请求数据字典会注入到视图函数
 if pet_id > len(pets) - 1:
 abort_json(404)
 data['id'] = pet_id
 pets[pet_id] = data
 return data

如果你想在你的电脑上运行这个示例，可以先用下面的命令安装 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）。

以下面的 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)}'

目前这个项目还属于早期阶段，在下一个版本（0.4.0）还会有一些破坏性的变动，更多的特性还在策划中（比如类视图支持），中文文档也会在英文文档完成后开始写作。

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

vlambda博客
学习文章列表