FastAPI 请求体字段校验与元数据：使用 Pydantic `Field` 精确定义模型属性

FastAPI 请求体字段校验与元数据使用 PydanticField精确定义模型属性【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi在 FastAPI 中为路径操作函数的单个参数声明校验与元数据时你习惯使用Query、Path、Body而当数据被组织进 Pydantic 模型、作为请求体整体接收时则可以在模型内部使用 Pydantic 的Field为每个属性声明同样的额外校验与元数据。本文以 FastAPI 官方教程 Body - Fields 为骨架结合本仓库的源码与测试系统讲解Field的导入方式、声明方法、参数能力、与 FastAPI 参数工具共享的底层机制以及这些声明如何被翻译为 OpenAPI / JSON Schema 元数据。为什么需要在模型内部声明字段约束在定义请求体模型时很多约束只针对模型内部的某个字段而不是整个请求体。例如description是可选的但若提供则不能超过 300 个字符price是必填浮点数且必须大于 0tax可缺省。这些约束若放在*路径操作函数*的参数上用Query、Path、Body表达并不合适——因为数据被包裹在模型对象里。此时正确的位置就是Pydantic 模型的属性声明处使用的工具则是 Pydantic 的Field。这一点正是 Body - Fields 的主题像Query、Path、Body为单个参数添加额外校验和元数据一样用 Pydantic 的Field在模型内部为属性添加校验与元数据。从pydantic导入Field首先需要导入Field。注意它直接来自pydantic而不是像Query、Path、Body那样来自fastapi。from typing import Annotated from fastapi import Body, FastAPI from pydantic import BaseModel, Field app FastAPI() class Item(BaseModel): name: str description: str | None Field( defaultNone, titleThe description of the item, max_length300 ) price: float Field(gt0, descriptionThe price must be greater than zero) tax: float | None None app.put(/items/{item_id}) async def update_item(item_id: int, item: Annotated[Item, Body(embedTrue)]): results {item_id: item_id, item: item} return resultswarning请留意Field从pydantic导入而其余参数工具Query、Path、Body等均从fastapi导入。混淆来源会导致导入错误或行为不符合预期。上述代码完整保存在仓库的 docs_src/body_fields/tutorial001_py310.py非Annotated写法与 docs_src/body_fields/tutorial001_an_py310.pyAnnotated写法中。两个版本功能完全等价后者利用Annotated把Body(embedTrue)元信息与类型放在同一处是当前推荐的现代写法本仓库对应测试 tests/test_tutorial/test_body_fields/test_tutorial001.py 对两种写法做了参数化回归验证。使用Field声明模型属性导入后即可在模型属性上用Field声明额外信息class Item(BaseModel): name: str description: str | None Field( defaultNone, titleThe description of the item, max_length300 ) price: float Field(gt0, descriptionThe price must be greater than zero) tax: float | None None逐行解读属性声明含义namename: str必填字符串无额外约束descriptionstr \| None Field(defaultNone, title..., max_length300)可选默认None在 JSON Schema 中title被设为 The description of the item字符串最大长度 300pricefloat Field(gt0, description...)必填浮点数gt0表示严格大于 0description作为字段说明写入 Schemataxtax: float \| None None可选浮点数使用普通默认值未加额外约束在默认值中使用Field的等价写法description一例演示了把Field(...)整体作为属性默认值的写法无default参数的语法在 Pydantic v2 中需显式default或用Field(...)。两种结构语义一致description: str | None Field(defaultNone, ...) # 等价于 description: str | None None # 若不需要任何额外约束与单个参数的声明保持同构值得注意的一个技巧是模型中每个带类型、默认值和Field的属性其结构与*路径操作函数*的参数完全同构——区别仅在于后者用Path、Query、Body取代了Field。对比# 路径操作函数参数用 Query/Path/Body async def update_item(item_id: int, item: Annotated[Item, Body(embedTrue)]): ... # 模型属性用 Field price: float Field(gt0, descriptionThe price must be greater than zero)理解了这套同构关系你就掌握了把任何参数级校验迁移到字段级校验的直觉。Field与Query/Path/Body的底层关系文档中有一则重要的Technical Details它解释了为什么Field与 FastAPI 的各个参数工具长得一模一样实际上Query、Path以及后续你将见到的其他工具创建的都是一种公共Param类的子类对象而Param类本身又是 PydanticFieldInfo类的子类Pydantic 的Field同样返回FieldInfo实例Body则直接返回FieldInfo的某个子类对象。还有更多你稍后会见到的工具是Body类的子类。另外请记住从fastapi导入的Query、Path等其实是返回特殊类的函数。源码印证了这一点。在 fastapi/params.py 中可以看到class Param(FieldInfo): # type: ignore[misc] in_: ParamTypes即 FastAPI 的Param直接继承自pydantic.fields.FieldInfo该文件顶部也通过from pydantic.fields import FieldInfo引入。而在 fastapi/param_functions.py 中Path、Query、Body以及Header、Cookie等都是返回相应*Info/Param子类对象的函数。由此可以推断出完整的继承脉络pydantic FieldInfo ├── pydantic Field(...) 返回 FieldInfo 实例 └── fastapi Param(FieldInfo) └── Query() / Path() / Header() / Cookie() 等返回 Param 子类 └── Body(...) 返回 FieldInfo 的专用子类对象因为共享同一套FieldInfo基座Field天然支持与Query、Path、Body相同的参数集合——gt/ge/lt/le、min_length/max_length、pattern、title、description、examples、alias、deprecated、json_schema_extra等二者在使用体验上保持一致。Field的常见参数速查基于源码 fastapi/params.py 展示的Param.__init__签名Field同为FieldInfo体系支持的常用参数可归纳如下数值校验gt/ge/lt/le分别约束大于、大于等于、小于、小于等于某数值price Field(gt0)multiple_of必须是某数的整数倍allow_inf_nan是否允许inf/nanmax_digits/decimal_places用于Decimal类型的小数位数约束。字符串校验min_length/max_length最小 / 最大长度description Field(max_length300)pattern正则表达式约束FastAPI 0.100.0 起取代已弃用的regex。模型元信息会写入 JSON Schema / OpenAPItitle字段标题默认取属性名可覆盖为人类可读的标题如titleThe description of the itemdescription字段说明文字examples/openapi_examples示例值example单数形式已在 OpenAPI 3.1 中弃用alias、validation_alias、serialization_alias字段别名deprecated标记字段废弃json_schema_extra向生成的 Schema 追加额外键discriminator联合类型的判别字段strict启用严格校验模式。校验生效422 错误的结构化返回当请求违反字段约束时FastAPI 会返回标准的 422 校验错误。仓库测试 tests/test_tutorial/test_body_fields/test_tutorial001.py 用负价格验证了这一点def test_invalid_price(client: TestClient): response client.put(/items/5, json{item: {name: Foo, price: -3.0}}) assert response.status_code 422 assert response.json()[detail][0] { type: greater_than, loc: [body, item, price], msg: Input should be greater than 0, input: -3.0, ctx: {gt: 0.0}, }注意错误定位loc: [body, item, price]——它精确指出了失败位置处于请求体的item对象内price属性验证了字段级约束与参数级约束共享同一套校验与错误上报管线。其背后正是 Pydantic v2 的校验器而 FastAPI 负责把FieldInfo上声明的约束装配进模型字段。额外信息如何进入生成的 JSON Schema 与 OpenAPI你在Field、Query、Body等中声明的额外信息都会被纳入最终生成的 JSON Schema进而出现在/openapi.json里。同一测试文件中 test_openapi_schema 展示了这一点Item模型的 Schema 中{ title: Item, required: [name, price], type: object, properties: { name: {title: Name, type: string}, description: { title: The description of the item, anyOf: [{maxLength: 300, type: string}, {type: null}] }, price: { title: Price, exclusiveMinimum: 0.0, type: number, description: The price must be greater than zero } } }可以清楚看到三处映射Field(max_length300)→maxLength: 300Field(gt0)→exclusiveMinimum: 0.0titleThe description of the item、descriptionThe price must be greater than zero→ Schema 中对应的title/description。同时由于请求体使用了Body(embedTrue)OpenAPI 中还会额外生成一层Body_update_item_items__item_id__put包装 Schema把Item嵌套在item键下。FastAPI 的交互式文档/docs会据此渲染出带字段说明与长度、取值约束的表单客户端也可依据该 Schema 提前做静态校验。warning传入Field的额外关键字extra keys同样会出现在应用最终的 OpenAPI Schema 中。由于这些键不一定属于 OpenAPI 规范本身部分 OpenAPI 工具例如 Swagger 官方校验器可能无法正确解析你生成的 Schema。因此自定义额外元数据前请权衡其对第三方工具链的兼容性影响。官方文档后续会在讲解 examples示例时介绍如何规范地添加这类额外信息。小结用 Pydantic 的Field可以在模型内部为每个属性声明额外的校验与元数据与Query、Path、Body为参数做声明的方式完全同构Field必须从pydantic导入而非从fastapi导入技术上FastAPI 的Query/Path等函数返回ParamFieldInfo子类对象Pydantic 的Field返回FieldInfo实例二者共享参数体系见 fastapi/params.py因此声明体验一致Field中的校验与元数据title、description、max_length、gt等会如实写入生成的 JSON Schema 与 OpenAPI请求违反字段约束时返回 422错误loc精确指向模型内字段路径相关行为由仓库测试 test_tutorial001.py 验证。在继续学习 body-nested-models.md 处理嵌套模型、或参考 body.md 回顾请求体基础之前掌握Field是让模型从容器升级为自带契约的关键一步。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考