docs-fastapi/docs/zh-hant/docs/tutorial/request-form-models.md

表單模型

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

/// note | 注意

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

將它加入你的專案：

$ uv add python-multipart

///

/// note | 注意

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

///

針對表單的 Pydantic 模型

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

{* ../../docs_src/request_form_models/tutorial001_an_py310.py hl[9:11,15] *}

FastAPI 會從請求中的 表單資料 擷取 每個欄位 的資料，並給你所定義的 Pydantic 模型。

檢視文件

你可以在 /docs 的文件 UI 中驗證：

禁止額外的表單欄位

在某些特殊情況（可能不常見）下，你可能希望將 表單欄位 限制 為只有 Pydantic 模型中宣告的欄位。並禁止任何額外欄位。

/// note | 注意

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

///

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

{* ../../docs_src/request_form_models/tutorial002_an_py310.py hl[12] *}

如果用戶端嘗試傳送額外資料，將會收到錯誤回應。

例如，用戶端若送出以下表單欄位：

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