表单模型

你可以使用 Pydantic 模型 在 FastAPI 中声明 表单字段。

Info

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

确保你创建了一个 虚拟环境，激活它，然后安装，例如：

$ pip install python-multipart

Note

此功能自 FastAPI 版本 0.113.0 开始支持。🤓

用于表单的 Pydantic 模型

你只需要声明一个包含你想要作为 表单字段 接收的字段的 Pydantic 模型，然后将参数声明为 Form：

Python 3.9+

from typing import Annotated

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str


@app.post("/login/")
async def login(data: Annotated[FormData, Form()]):
    return data

🤓 Other versions and variants

Python 3.8+Python 3.8+ - non-Annotated

from fastapi import FastAPI, Form
from pydantic import BaseModel
from typing_extensions import Annotated

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str


@app.post("/login/")
async def login(data: Annotated[FormData, Form()]):
    return data

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str


@app.post("/login/")
async def login(data: FormData = Form()):
    return data

FastAPI 会从请求的 表单数据 中为 每个字段 提取 数据，并给你定义好的 Pydantic 模型。

查看文档

你可以在 /docs 的文档 UI 中验证：

禁止额外的表单字段

在一些特殊的使用场景中（可能不太常见），你可能希望 限制 表单字段仅为 Pydantic 模型中声明的字段。并 禁止 任何 额外 字段。

Note

此功能自 FastAPI 版本 0.114.0 开始支持。🤓

你可以使用 Pydantic 的模型配置来 forbid 任何 extra 字段：

Python 3.9+

from typing import Annotated

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str
    model_config = {"extra": "forbid"}


@app.post("/login/")
async def login(data: Annotated[FormData, Form()]):
    return data

🤓 Other versions and variants

Python 3.8+Python 3.8+ - non-Annotated

from fastapi import FastAPI, Form
from pydantic import BaseModel
from typing_extensions import Annotated

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str
    model_config = {"extra": "forbid"}


@app.post("/login/")
async def login(data: Annotated[FormData, Form()]):
    return data

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str
    model_config = {"extra": "forbid"}


@app.post("/login/")
async def login(data: FormData = Form()):
    return data

如果客户端尝试发送一些额外的数据，他们将收到一个 错误 响应。

例如，如果客户端尝试发送表单字段：

• username: Rick
• password: Portal Gun
• extra: Mr. Poopybutthole

他们将收到一个错误响应，告知字段 extra 不被允许：

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["body", "extra"],
            "msg": "Extra inputs are not permitted",
            "input": "Mr. Poopybutthole"
        }
    ]
}

总结

你可以使用 Pydantic 模型在 FastAPI 中声明表单字段。😎