表单数据

需要接收的不是 JSON，而是表单（Form）字段时，可以使用 Form。

说明

使用表单，请先安装 python-multipart。

例如，pip install python-multipart。

导入 Form

从 fastapi 导入 Form：

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
    return {"username": username}

定义 Form 参数

创建表单参数的方式与 Body 和 Query 一样：

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
    return {"username": username}

例如，OAuth2 规范的密码流规定要通过表单字段发送 username 和 password。

该规范明确要求字段必须命名为 username 和 password，并通过表单字段发送，不能用 JSON。

使用 Form 可以声明与 Body （及 Query、Path、Cookie）相同的元数据和验证。

说明

Form 是直接继承自 Body 的类。

提示

要显式使用 Form 声明表单体，否则，FastAPI 会把表单参数当作查询参数或请求体（JSON）参数。

关于表单字段

与 JSON 不同，HTML 表单（<form></form>）向服务器发送数据通常使用特定编码。

FastAPI 要确保从正确的位置读取数据，而不是读取 JSON。

技术细节

表单数据的媒体类型编码一般为 application/x-www-form-urlencoded。

但包含文件的表单编码为 multipart/form-data。文件处理详见下一章。

编码和表单字段详见 MDN Web 文档的 POST小节。

警告

可在一个路径操作中声明多个 Form 参数，但不能同时声明接收 JSON 的 Body 字段。因为此时请求体的编码是 application/x-www-form-urlencoded，不是 application/json。

这不是 FastAPI 的问题，而是 HTTP 协议的规定。

小结

本章介绍了如何使用 Form 声明表单数据输入参数。