Pydantic v2 中通过继承 BaseModel 并使用 Field 显式标注类型和校验规则定义请求模型,FastAPI 0.100+ 原生支持,自动调用 model_validate;查询参数和表单需分别用 Query() 和 Form() 绑定,错误定位应使用 exc.errors()。

Pydantic v2 中如何定义请求数据模型?
Pydantic v2 把模型定义从 BaseModel 迁移到了 BaseModel(名字没变,但内部机制完全不同),关键区别是默认启用 strict mode、移除了 Config 类的大部分字段,改用 model_config 字典或 @model_config 装饰器。
定义请求体模型时,必须显式标注类型,且推荐使用 Field 控制校验行为:
from pydantic import BaseModel, Field from typing import Optional <p>class UserCreate(BaseModel): username: str = Field(..., min_length=3, max_length=20) email: str age: int = Field(ge=0, le=150) # >=0 and <=150 is_active: Optional[bool] = None
-
...表示该字段必填;None或省略默认值表示可选 -
Field的min_length/max_length对str有效,对int无效——别错配 - v2 不再支持
allow_mutation=False这类旧 Config 写法,要用model_config = {"frozen": True}
FastAPI 中怎么把 Pydantic v2 模型用于请求校验?
FastAPI 0.100+ 原生兼容 Pydantic v2,直接把模型作为路径函数参数即可,框架会自动调用 .model_validate()(不是旧版的 .parse_obj())解析并校验 JSON 请求体。
常见错误现象:ValidationError: 1 validation error for UserCreate\nemail\n Input should be a valid string——说明传入的是 null 或数字,而字段声明为 str。
立即学习“Python免费学习笔记(深入)”;
- 确保前端发送的是标准 JSON,比如
{"email": "a@b.c"},而非{"email": null}(除非字段是Optional[str]) - 如果想允许空字符串作为合法值,得加
default=""并配合allow_empty=True(但 v2 中空字符串默认被接受,无需额外配置) - 嵌套模型要逐层定义,FastAPI 不会自动展开 dict —— 错误写法:
user: dict;正确写法:user: UserCreate
如何处理查询参数和表单数据的校验?
Pydantic v2 本身不区分请求来源,校验逻辑统一;但 FastAPI 需要靠依赖注入来绑定不同来源的数据。查询参数用 Query,表单用 Form,它们底层仍走 Pydantic 校验流程。
from fastapi import Query, Form
from pydantic import BaseModel
<p>class SearchParams(BaseModel):
q: str = Field(..., min_length=1)
page: int = Field(1, ge=1)</p><h1>查询参数校验</h1><p>@app.get("/search")
def search(params: SearchParams = Query()): ...</p><h1>表单校验(需安装 python-multipart)</h1><p>@app.post("/upload")
def upload(file: bytes = Form(...), meta: SearchParams = Form()): ...
-
Query()和Form()的括号不能省——否则 FastAPI 当作普通参数,不触发校验 - 表单中混合文件和 JSON 字段时,非文件字段仍由 Pydantic 解析,但必须用
Form显式标注,否则报ValueError: field required - URL 编码的查询参数(如
?q=hello%20world)会被自动解码后再进校验,无需手动urllib.parse.unquote
遇到 ValidationError 怎么定位具体字段和原因?
Pydantic v2 的错误信息更结构化,但默认只返回第一层错误。调试时建议捕获异常并打印 exc.errors(),它返回一个 list,每项含 loc(字段路径)、msg(提示)、type(错误类型)。
from pydantic import ValidationError
<p>try:
user = UserCreate.model_validate({"username": "ab", "email": 123})
except ValidationError as exc:
print(exc.errors())</p><h1>输出类似:[{'loc': ('username',), 'msg': 'String should have at least 3 characters', ...},</h1><pre class="brush:php;toolbar:false;"># {'loc': ('email',), 'msg': 'Input should be a valid string', ...}]
-
loc是 tuple,比如('items', 0, 'name')表示嵌套列表第一个元素的name字段 - 不要依赖
str(exc)做日志——它可能被截断或格式混乱;始终用exc.errors() - 生产环境别直接返回原始错误给前端,FastAPI 默认已做封装,但自定义异常处理器里记得过滤敏感字段(如数据库字段名)
实际用起来最易忽略的是:Pydantic v2 对 None 的处理比 v1 更严格,哪怕字段声明为 Optional[str],如果传了 null(JSON 中),它仍会通过;但若传了 undefined(前端漏传)且字段没设默认值,就会报错——这个边界在前后端联调时最容易卡住。


















