FastAPI 表单模型Form Models实战使用 Pydantic Model 声明并校验表单字段【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi在 FastAPI 中编写登录、注册、搜索等基于 HTML 表单的接口时传统做法是逐个使用Form(...)声明字段而本教程要介绍的能力是——直接用 Pydantic Model 一次性声明整组表单字段让 FastAPI 自动把请求中的form data提取、校验并组装成模型对象。读完本文你将掌握如何安装python-multipart、如何用模型声明表单字段含两种写法、如何在/docs交互文档中验证效果以及如何通过 Pydantic 的model_config禁止多余字段。说明本文章节内容源自当前仓库的docs/hi/docs/tutorial/request-form-models.md多语言文档中与官方英文文档内容对齐的一篇正文结合docs_src/request_form_models/示例源码、fastapi/params.py实现与tests/test_tutorial/test_request_form_models/测试用例进行扩展。文中以 FastAPI0.113.0及以上版本为前提。一、前置条件安装 python-multipart 并确认版本表单数据走的是application/x-www-form-urlencoded或multipart/form-data编码FastAPI 解析这类请求体需要第三方库支持。因此在使用 Form 或 Form Models 之前必须先安装python-multipart。将依赖加入项目当前仓库使用uv作为包管理器因此命令写作uv add$ uv add python-multipart需要留意两点版本前提官方文档明确标注使用 Pydantic Model 声明表单字段Form Models自FastAPI0.113.0起支持下文中禁止额外字段extra: forbid的能力自FastAPI0.114.0起支持。若未安装python-multipart却声明了Form参数FastAPI 在启动阶段就会抛出安装提示错误这是表单相关功能最常遇到的第一个坑。二、为表单声明 Pydantic Model让每个字段自动提取与校验这一节对应官方英文文档docs/en/docs/tutorial/request-form-models.md的 Pydantic Models for Forms 一节。你需要做的只有两步定义一个Pydantic Model其中声明你希望以form fields形式接收的字段在路径操作函数的参数中把该模型标注为Form。推荐写法Annotated Form()当前仓库推荐使用Annotated元数据形式。完整示例代码见 docs_src/request_form_models/tutorial001_an_py310.pyfrom 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兼容写法data: FormData Form()仓库同样提供了非Annotated的等价示例见 docs_src/request_form_models/tutorial001_py310.pyfrom 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两种写法的运行时行为一致Annotated写法更利于类型检查与重构是官方推荐的风格本仓库中文档切片hl[9:11,15]高亮即指向模型类与路径函数签名。工作原理当收到如usernameFoopasswordsecret的表单请求时FastAPI 会为请求 form data 中该模型的每一个字段提取数据做统一的类型校验、必填校验最终组装出你定义的那个FormData实例并传入函数——每个字段的校验规则类型、必填与否、约束条件都由 Pydantic 模型字段定义决定。这一行为的底层证据可以在测试用例与 OpenAPI 输出中交叉验证发送完整字段时返回200响应体原样回显两个字段缺少username或password任意一个时返回422错误中loc为[body, username]/[body, password]类型为missingmsg: Field required说明字段校验发生在body 表单这个维度用json而非data发送请求体时同样返回422——因为该接口只接受表单编码不接受 JSON body。对应测试见 tests/test_tutorial/test_request_form_models/test_tutorial001.py其中test_post_body_form、test_post_body_form_no_password、test_post_body_json等用例逐一验证了上述行为。OpenAPI Schema 中的体现测试用例中的test_openapi_schema还验证了生成的 OpenAPI 结构值得关注的证据包括请求体媒体类型为application/x-www-form-urlencodedschema 通过$ref引用#/components/schemas/FormData而FormData被描述为一个type: object、含username/password两个string属性的对象且required: [username, password]。这意味着 Swagger UI / ReDoc 能直接把整个模型渲染为一张表单接口文档对调用方非常友好。三、在 /docs 交互文档中验证启动应用后例如uv run fastapi dev main.py或按当前仓库常规方式运行示例模块打开http://127.0.0.1:8000/docs。在POST /login/接口的 Try it out 面板中会看到请求体被渲染为一个包含username、password输入框的表单而非自由 JSON 编辑器提交后即可观察 200 成功响应或 422 校验错误含缺失字段提示。上图即为该教程配套文档截图可以在交互面板中直观核对字段渲染效果。四、禁止额外字段model_config {extra: forbid}默认情况下Pydantic 模型会忽略请求中未在模型里声明的额外表单字段FastAPI 不会报错。但在某些特殊场景虽然不算常见比如严格控制 API 入参面你希望表单字段只能是模型中声明的那几个任何extra字段都被forbid拒绝。做法非常简单在 Pydantic 模型的model_config中设置extra为forbid。完整示例见 docs_src/request_form_models/tutorial002_an_py310.pyfrom 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同样存在非Annotated版本 docs_src/request_form_models/tutorial002_py310.py行为等价。触发错误的真实响应现在若客户端试图发送如下 form fieldsusernameRickpasswordPortal GunextraMr. Poopybutthole则字段extra不在模型中客户端会收到 422 错误响应明确告知该字段不被允许{ detail: [ { type: extra_forbidden, loc: [body, extra], msg: Extra inputs are not permitted, input: Mr. Poopybutthole } ] }注意错误对象的几个要点type是 Pydantic 的标准错误类型extra_forbiddenloc指明是body下的extra字段input原样返回被拒的输入值便于调用方定位问题。这一行为在 tests/test_tutorial/test_request_form_models/test_tutorial002.py 中被test_post_body_extra_form精确锁定断言 422 与完整错误体同时该文件的test_openapi_schema显示设置extra: forbid后生成的FormDataschema 会带上additionalProperties: False——即拒绝行为会被如实写进 OpenAPI 文档调用方在文档阶段就能看到不允许额外字段的契约。同一文件中test_post_body_form_no_password、test_post_body_json等用例则说明即便启用了 forbid缺失必填字段、错误编码请求等校验逻辑依然按原样生效二者互不影响。五、从源码看 Form 模型的底层定位为了更准确地理解 Form Models可回到 FastAPI 参数体系的定义处 fastapi/params.py类Form直接继承自Body其构造函数中media_type默认值为application/x-www-form-urlencoded。也就是说Form()本质上仍是请求体这一类参数只是媒体类型被固定为表单编码当参数注解是一个Pydantic Model时FastAPI 会把整个模型视为请求体的 schema——这与把单个字段当作模型 body是同一套机制请求体的多字段被映射为模型的多个字段并统一交由 Pydantic 完成解析与校验。因此 Form Models 不是新的语法糖而是Body(Pydantic Model) 语义在表单媒体类型下的复用它同时继承了模型校验、必填规则、extra策略等全部能力这也是它能与 JSON Body 模型共用同一套字段声明心智模型的原因。六、小结在本教程中你可以学到用Pydantic Model Form()一次性声明一组表单字段免去逐字段书写Form参数的样板代码FastAPI 自动为每个字段执行提取与校验缺字段时返回标准的 422missing错误通过/docs交互面板直观验证表单渲染与 Try it out 行为通过model_config {extra: forbid}限制表单字段白名单越界字段返回extra_forbidden错误且该契约会同步进 OpenAPI 的additionalProperties: false从 fastapi/params.py 与仓库测试test_tutorial001、test_tutorial002中可以确认整套行为的底层实现与校验细节。需要再次提醒使用本功能前请先uv add python-multipart并确认 FastAPI 版本不低于0.113.0禁止额外字段功能需不低于0.114.0。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考