跳转至

表单数据

🌐 Translation by AI and humans

This translation was made by AI guided by humans. 🤝

It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖

You can improve this translation by helping us guide the AI LLM better.

English version

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

Info

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

请先创建并激活一个虚拟环境，然后再进行安装，例如：

$ pip install python-multipart

导入 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}
🤓 Other versions and variants 
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}

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Form

app = FastAPI()


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

Tip

Prefer to use the Annotated version if possible.

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}
🤓 Other versions and variants 
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}

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Form

app = FastAPI()


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

Tip

Prefer to use the Annotated version if possible.

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 作为表单字段发送。

spec 要求这些字段必须精确命名为 username 和 password，并且作为表单字段发送，而不是 JSON。

使用 Form 可以像使用 Body（以及 Query、Path、Cookie）一样声明相同的配置，包括校验、示例、别名（例如将 username 写成 user-name）等。

Info

Form 是直接继承自 Body 的类。

Tip

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

关于 "表单字段"

HTML 表单（<form></form>）向服务器发送数据时通常会对数据使用一种“特殊”的编码方式，这与 JSON 不同。

FastAPI 会确保从正确的位置读取这些数据，而不是从 JSON 中读取。

技术细节

表单数据通常使用“媒体类型” application/x-www-form-urlencoded 进行编码。

但当表单包含文件时，会编码为 multipart/form-data。你将在下一章阅读如何处理文件。

如果你想了解更多关于这些编码和表单字段的信息，请参阅 MDN Web 文档的 POST。

Warning

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

这不是 FastAPI 的限制，而是 HTTP 协议的一部分。

小结

使用 Form 来声明表单数据输入参数。