表单数据¶
当您需要接收表单字段而不是 JSON 时，可以使用 Form。
导入 Form¶
从 fastapi 导入 Form
from typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
return {"username": username}
🤓 其他版本和变体
from fastapi import FastAPI, Form
from typing_extensions import Annotated
app = FastAPI()
@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
return {"username": username}
提示
如果可能，请优先使用 Annotated 版本。
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 typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
return {"username": username}
🤓 其他版本和变体
from fastapi import FastAPI, Form
from typing_extensions import Annotated
app = FastAPI()
@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
return {"username": username}
提示
如果可能，请优先使用 Annotated 版本。
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）相同的配置，包括验证、示例、别名（例如 user-name 而不是 username）等。
信息
Form 是一个直接继承自 Body 的类。
提示
要声明表单主体，您需要显式使用 Form，因为如果没有它，参数将被解释为查询参数或主体 (JSON) 参数。
关于“表单字段”¶
HTML 表单 (<form></form>) 向服务器发送数据的方式通常对该数据使用“特殊”编码，它与 JSON 不同。
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 声明表单数据输入参数。