表單模型¶

🌐 AI 與人類共同完成的翻譯

此翻譯由人類指導的 AI 完成。🤝

可能會有對原意的誤解，或讀起來不自然等問題。🤖

你可以透過協助我們更好地引導 AI LLM來改進此翻譯。

英文版

你可以使用 Pydantic 模型 在 FastAPI 中宣告 表單欄位。

注意

要使用表單，首先安裝 python-multipart。

將它加入你的專案：

$ uv add python-multipart

注意

此功能自 FastAPI 版本 0.113.0 起支援。🤓

針對表單的 Pydantic 模型¶

你只需要宣告一個 Pydantic 模型，包含你要接收為 表單欄位 的欄位，然後將參數宣告為 Form：

Python 3.10+

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.10+ - non-Annotated

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 模型中宣告的欄位。並禁止任何額外欄位。

注意

此功能自 FastAPI 版本 0.114.0 起支援。🤓

你可以使用 Pydantic 的模型設定來 forbid 任何 extra 欄位：

Python 3.10+

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.10+ - non-Annotated

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 中宣告表單欄位。😎