1. 先搞清楚为什么你的代码里需要Pydantic这篇聊的是 Pydantic 基础用法但它不会是从安装到 API 的流水账。起因是我又双叒在凌晨被值班电话叫醒线上订单接口报错排查半天发现从第三方回调里拿到的age字段不是数字而是字符串30代码里直接用age 60判断字符串和整数比较在 Python 3 里直接抛 TypeError。这种问题我遇到过不下五次后来把所有数据入口都换成 Pydantic 做校验转换类似的线上事故基本绝迹。这里说的 Pydantic 基础用法核心就三件事数据校验、类型转换、序列化导出。校验是说字段该是 int 必须是 int该必填的不能缺转换是说外部传过来的数据哪怕全是字符串Pydantic 也会按类型注解帮你转成合适的 Python 类型序列化是说模型对象能一键变回字典或 JSON 字符串方便返回给前端或落库。这三件事要是拆成三套工具做每套都维护一套类型定义迟早对不上。Pydantic 用一个模型类就把它们全部定义清楚这就是它最大的价值。它的适用范围比多数人想象中广。写 API 时校验请求体是最常见的用法FastAPI 底层就是靠它微服务之间传消息、读配置文件、解析外部开放平台的回调都可以拿它当统一的数据入口守卫。不适合的场景也有如果你已经有一份完全可信的内部数据只是要在内存里高频读写的纯计算逻辑硬套 Pydantic 反而多了一层没必要的数据结构开销。搞清楚什么场景该用、什么场景不该用比学会写模型类更重要。1.1 没有校验层时代码会变成什么样没有 Pydantic 的处理逻辑通常是这样的def handle_user(data: dict): # data来自HTTP请求没人保证字段齐全 if name not in data or not isinstance(data[name], str): raise ValueError(name参数非法) if age not in data: raise ValueError(age缺失) age int(data[age]) # 万一data[age]是abc这里直接抛异常 if age 0 or age 150: raise ValueError(age范围非法) return {name: data[name], age: age}字段少还好业务字段一多每个接口都写这么一段代码里就全是防御式 if。更麻烦的是字典这种结构本身没有任何类型约束你传data[name]给下游函数时IDE 不会提示你它是字符串重构时换个 key 名也不会立刻报错。而 Pydantic 把校验逻辑声明式地写在模型类里业务代码拿到的就是一个类型明确的模型对象IDE 补全、重构、类型检查全都能用上。1.2 为什么校验转换序列化必须合成一个工具单独做校验的办法很多jsonschema、cerberus、手写 if都能做。但 Pydantic 把这三个环节捆在一起因为外部数据往往以字符串形态存在——HTTP 的 query 参数全是字符串数据库读出来的字段可能是 Decimal、datetime 这类对象。校验完还要转成代码里方便用的类型用的时候又要转回去给别人。如果拆成三套工具每个环节都要维护一份类型定义迟早出现校验通过的字段序列化时却报错的尴尬。用一个模型类统一描述输入输出的规格这是从工程角度最省心的做法。2. 环境准备与你的第一个Pydantic模型2.1 安装与版本选择先装包。2024 年之后的项目直接装 v2 系列就好pip install pydantic检查版本python -c import pydantic; print(pydantic.__version__)如果是 2.x 开头就说明你用的是 v2 语法如果装到了 1.x很多 API 都不一样强烈建议升级pip install pydantic2。这里必须多说一句版本问题。网上搜 Pydantic 教程一半是 v1 时代的写法parse_obj、dict()、json()、validator、class Config这些在 v2 里全变了。v2 最大的变化是底层校验核心用 Rust 重写了性能比 v1 快好几倍API 也重新设计过。如果你刚接触请直接学 v2遇到老帖子时要会区分版本。后面所有示例都以 v2 为准老 API 我会附带提一句对应关系。2.2 定义模型继承 BaseModelPydantic 的核心是BaseModel。用普通 class 继承它照常写字段注解from pydantic import BaseModel class User(BaseModel): name: str age: int email: str | None None user User(name张三, age18) print(user.name) # 张三 print(user.age) # 18注意是int print(type(user.age)) # class int print(user.email) # Noneage18传进去的是字符串但模型实例的age已经是 int。这就是 Pydantic 和普通 dataclass 最大的区别普通 dataclass 你传什么就是什么Pydantic 会按注解做一次合法范围内的自动转换字符串18能被明确解析成数字 18所以不报错传abc则转换失败立刻抛ValidationError。需要特别强调的是Pydantic 在实例化时才做校验不是在定义模型时。模型类本身只是声明调用构造方法的那一刻才校验数据。这个时间点关系很重要后面讲到性能优化和批量导入时会用到。2.3 转换失败时报错信息怎么读实际开发中永远要用try/except捕获校验失败from pydantic import ValidationError try: User(name张三, ageabc) except ValidationError as e: print(e.errors())输出是一个列表每一项包含loc哪个字段、msg为什么失败、type错误类型。这个结构化错误可以直接转成给前端看的参数错误提示。自己手写校验逻辑的话这一步往往要手动拼错误信息而 Pydantic 已经帮你把错误结构准备好了省掉一大块样板代码。2.4 为什么宽松转类型反而是优点有人会觉得传字符串居然能正确转成 int这也太宽松了。但注意Pydantic 的宽松是有底线的只在输入能明确、无歧义地转换成目标类型时才转。18 - 18是明确转换abc - int不是所以后者报错。这个设计服务于一个现实网络传输层拿到的数据大多是字符串形态如果不自动转换就要在每个函数里自己int()、str()转换异常散落在业务代码里根本查不过来。把转换集中在数据入口业务逻辑里直接信任类型这个信任边界才是 Pydantic 给你带来的最大收益。3. 字段类型体系从int到复杂泛型的正确用法3.1 内置类型与常见陷阱Pydantic 直接复用 Python 的类型注解str、int、float、bool、bytes、list、set、dict这些都能直接用。大多数类型凭直觉就不会错真正需要留心的是 bool。bool字段在 v2 里会尝试把常见字符串形态比如true、false大小写不敏感和 0、1 转成布尔。但生产环境里不同客户端序列化的风格不一样有人传True有人传1有人传YPydantic 的默认转换未必覆盖所有野生格式。我的建议是对外接口的文档里明确要求布尔字段传true/false如果上游真的不规范就单独写一个field_validator做白名单映射不要指望默认行为兜底。另外注意 Decimal 和 datetime。金融类金额用Decimal而不是float日期用datetime、date、time。Pydantic 对 ISO 8601 格式的字符串会自动解析成 datetime 对象这个在解析接口返回值时非常常用。3.2 Optional、Union 与 None 的三种写法可选字段最常见的写法是str | None NonePython 3.10低版本用Optional[str] None。这里有两个容易忽略的点第一str | None None表示这个字段有两个约束接收字符串、允许为空。如果你只写str NonePydantic 会报错因为默认值类型和注解不匹配。第二Union[str, int]这样的多类型字段能用但不建议滥用。虽然 v2 有智能选择机制尽量帮你选一个合法类型但它终究是为数据来源极度不可控的场景准备的。绝大多数情况下你应该把类型弄得更精确而不是更模糊。用 Union 之前先问问自己这个字段到底是什么业务含义3.3 Literal、Annotated 与更精确的约束Literal可以约束字段只能取固定几个值from typing import Literal class Order(BaseModel): status: Literal[pending, paid, cancelled] Order(statuspending) # 正常 Order(statusshipped) # 报错仅允许三种值这比单纯用str强很多相当于把枚举约束提前到字段类型阶段非法状态在入口就被拦截。Annotated则可以把 Field 约束直接合并进类型里适合定义可复用的字段类型from typing import Annotated from pydantic import Field PositiveInt Annotated[int, Field(gt0)] class Order(BaseModel): total: PositiveInt这个技巧在大型项目里很有用把业务上的类型和Python 基础类型区分开字段约束可以到处复用不用每个模型都复制一遍同样的 Field 配置。4. Field约束与内置校验新手最容易忽略的防线4.1 Field 的必填、默认值与常见参数字段声明用Field函数可以附加校验约束这是新手最常忽略的一层免费校验from pydantic import BaseModel, Field class Product(BaseModel): name: str Field(..., min_length1, max_length100) price: float Field(..., gt0, le99999) sku: str Field(..., patternr^[A-Z]{3}\d{4}$) tags: list[str] Field(default_factorylist, max_length10)...表示必填。为什么不用None因为None是默认值而默认值会被当成合法输入必填字段如果没有显式传值用...会让 Pydantic 报field required语义比 None 清晰得多。这是写模型类时第一个要养成的习惯。4.2 数值边界、字符串长度与正则数值类约束参数有gt大于、ge大于等于、lt小于、le小于等于、multiple_of倍数约束字符串类有min_length、max_length、pattern集合类同样支持min_length、max_length适用于 list、set、dict。产品单价price必须是正数、SKU 必须符合公司编号规则这些业务规则完全可以用 Field 写在类型声明里根本不用写 if。校验失败的报错信息也足够友好直接把错误抛给调用方业务代码保持干净。项目里的做法是把这类模型放在 API 入口层的 schema 目录里任何外部数据进来先过一遍模型后续服务内部全都不用再担心字段格式问题。4.3 可变默认值list 和 dict 必须用 default_factory这是 Python 老坑换了个马甲出现在 Pydantic 里class Team(BaseModel): members: list[str] Field(default_factorylist) # 正确 # members: list[str] [] # 错误可变对象共享直接写 []在 Python 里是经典的共享可变对象问题多个实例会共用同一个 listA 实例往里面加成员B 实例也看得到。Pydantic 文档明确要求可变默认值一律通过default_factory生成很多 lint 规则也会拦这种写法。建议从第一天写模型就养成习惯后面不会踩这个隐蔽的坑。4.4 Field 校验失败的时机在实例化时不在使用时我见过很多同事以为 Pydantic 会实时检查字段。不是的。校验只发生在模型实例化的时候。如果你用 Pydantic 建模后来又直接通过model.attr value改了属性值默认情况下不会重新校验。要开启赋值时校验需要配置validate_assignmentTrue这个后面第 8 节详细讲。理解这个时机边界很重要否则你会写出改完属性以为校验过了的 bug。5. Validator机制自定义校验的正确姿势Field 只能覆盖单字段、单值的简单约束跨字段、需要查表、需要转换后才能判断的逻辑就要用 Validator。5.1 field_validator单字段的自定义校验v2 里写自定义单字段校验from pydantic import field_validator class Order(BaseModel): quantity: int Field(..., gt0) price: float Field(..., gt0) field_validator(quantity) classmethod def check_quantity(cls, v): if v 10000: raise ValueError(单笔订单数量过大) return vv2 的field_validator通常配合classmethod使用第一个参数是cls第二个参数是字段值v返回值会作为最终值替换原值。如果你想在类型转换前看原始输入用modebefore默认modeafter是在 Pydantic 完成内置类型转换之后执行你的逻辑此时v已经是干净的int类型。field_validator还支持一次校验多个字段field_validator(name, sku)多个字段共用同一套校验逻辑时很省事。要注意的是如果字段本身类型转换失败比如quantityabc那么后续field_validator根本不会执行因为数据没到达那一步。排查validator 没触发问题时先确认是不是类型转换阶段就挂了。5.2 model_validator跨字段联动校验单字段校验管不了开始时间必须早于结束时间这种跨字段约束要用model_validatorfrom datetime import datetime from pydantic import model_validator class Booking(BaseModel): start_at: datetime end_at: datetime model_validator(modeafter) def check_time_range(self): if self.end_at self.start_at: raise ValueError(end_at必须晚于start_at) return selfmodeafter表示模型已经构造完成可以在self上读任意字段并做联动校验另一种modebefore拿到的还是原始 dict适合对整个输入做预处理。我个人的习惯是能用 after 就用 after因为你能拿到的是已经验证过的字段值逻辑写起来直观可靠。5.3 校验顺序与报错合并Pydantic 的校验顺序是先做内置类型转换再执行field_validator最后执行model_validator。如果多个字段都校验失败错误会被合并收集在同一个ValidationError.errors()里返回而不是抛第一个就停止。这对 API 场景极其友好——一次能把所有字段的错误都返回给前端让用户一起改而不是改一个重新提交一次。5.4 从 v1 迁移过来的人最容易踩的语法差异老代码里validator是同步方法第一个参数是字段值模型配置写在class Config里。v2 里validator改名field_validator并且要求类方法风格Config类改成model_config ConfigDict(...)。升级老项目时建议全局搜索parse_obj、.dict()、.json()、validator、Config这几个关键词逐个替换否则编译不报错、运行时全是兼容性错误比语法报错难查得多。6. 序列化与数据导出不只是model_dump模型实例最终要返回给外部或者落库、进队列这时候需要把对象导出成字典或 JSON。6.1 三个导出方法的定位方法输出典型场景model_dump()Python 原生 dict传给其他函数、转 dict 后处理model_dump_json()JSON 字符串返回给 HTTP 客户端、写文件model_dump(modejson)JSON 兼容类型的 dict需要 dict 但值必须能json.dumps很多 v1 老教程的写法是model.dict()和model.json()这两个在 v2 已废弃。新项目直接记model_dump和model_dump_json即可。modejson这个参数特别实用它会确保 datetime 变成字符串、Decimal 变成字符串或数字总之是一个JSON 安全的 dict比先 dump 再 json.dumps 再 json.loads那套绕路写法高效得多。6.2 exclude / include / exclude_none控制导出范围实际生产中不是所有字段都要导出。用户模型里可能有密码哈希、内部工号返回给前端时要排除class User(BaseModel): id: int name: str password: str user.model_dump(exclude{password}) # {id: 1, name: 张三}exclude_noneTrue可以去掉所有为 None 的字段避免 JSON 里一堆email: null。还有include是白名单方式和 exclude 互斥按需使用。对嵌套模型exclude 可以跟进到子字段比如exclude{address: {city}}细节很多实际用到时查文档即可。6.3 alias输入输出字段名不一致怎么办前后端字段命名风格经常不一致后端用 snake_case前端接口文档却用 camelCase。alias 机制就是干这个的from pydantic import ConfigDict class UserOut(BaseModel): user_name: str Field(validation_aliasuserName, serialization_aliasuserName) model_config ConfigDict(populate_by_nameTrue)validation_alias决定接收输入时认哪个 keyserialization_alias决定导出时输出哪个 keyalias参数同时设置两者populate_by_nameTrue允许你用 Python 字段名传值。配合model_dump(by_aliasTrue)输出 camelCase前端直接消费后端内部继续用 snake_case两边都舒服。但要注意alias 的实际效果比示例复杂嵌套 alias、validate_by_alias、serialize_by_alias三个开关各有职责项目里统一配置好再全局使用别一个模型一个样。6.4 自定义序列化field_serializer有时候默认导出格式不满足要求比如日期要YYYY/MM/DD而不是 ISO 格式用field_serializerfrom pydantic import field_serializer class Event(BaseModel): created_at: datetime field_serializer(created_at) def serialize_time(self, v: datetime) - str: return v.strftime(%Y/%m/%d %H:%M:%S)这个功能和field_validator方向相反validator 管进serializer 管出两边的逻辑都写在模型里进出的规则始终是同一份定义。7. 嵌套模型与复杂结构设计真实项目里几乎没有模型是纯扁平的。订单里有用户用户里有地址地址里还有经纬度。Pydantic 对嵌套结构处理得相当顺手。7.1 内嵌模型字典自动变成对象class Address(BaseModel): city: str street: str class OrderUser(BaseModel): name: str address: Address u OrderUser(name张三, address{city: 北京, street: 中关村大街1号}) print(u.address.city) # 北京外部传进来的address是普通 dictPydantic 会自动把它转换成Address实例。你再也不用手写Address(**data[address])这种样板代码。这也意味着嵌套属性访问是链式的u.address.cityIDE 能自动补全重构时字段改名也会报错提醒。7.2 List、Dict、Set 等容器类型容器类型同样支持自动转换class Order(BaseModel): items: list[AddressItem] Order(items[{name: 苹果, price: 3.5}, {name: 梨, price: 4.5}])list[AddressItem]里的每个 dict 都会被转成 AddressItem 实例。注意 Python 3.9 以下不支持list[X]这种写法要用List[X]Python 3.9 两者都行。如果容器里混入非法元素错误信息会定位到具体索引比如items.1.price排查起来非常方便。7.3 递归模型和自引用树形结构、评论楼中楼这类场景需要模型引用自身class TreeNode(BaseModel): name: str children: list[TreeNode] [] root TreeNode(nameroot, children[{name: child}])用字符串做前向引用即可。如果运行时出现类型未解析的错误调用TreeNode.model_rebuild()可以强制重新解析内部引用。递归模型是 Pydantic 相对高级但很实用的能力注意别在无环数据上写无限递归逻辑那会导致构造过程死循环。7.4 从 ORM 对象构建模型Pydantic 不只能吃字典还能吃任意对象ORM 实例。只要配置from_attributesTrueclass UserOut(BaseModel): id: int name: str model_config ConfigDict(from_attributesTrue) user_out UserOut.model_validate(db_user) # db_user是SQLAlchemy对象这个能力让ORM 模型到 API 响应模型的转换完全自动化。有人觉得可以直接把 ORM 对象塞给 FastAPI 返回但那样会把数据库表结构直接暴露给前端风险很大。标准做法永远是定义一个独立的响应模型把 ORM 实例转进去只保留你想暴露的字段。这是 Pydantic 在 Web 项目里最核心的用法之一。8. 模型配置与行为控制模型类里还有一个设置区——model_config它控制模型整体行为而不是单个字段。8.1 ConfigDict 核心参数速查from pydantic import ConfigDict class User(BaseModel): model_config ConfigDict( extraforbid, # 多余字段怎么处理 frozenTrue, # 是否冻结不可变 validate_assignmentTrue, # 是否在属性赋值时校验 str_strip_whitespaceTrue, # 自动去除字符串首尾空白 ) name: str age: int参数取值含义extraignore/forbid/allow多余字段忽略、拒绝、或保留到__pydantic_extra__frozenTrue/FalseTrue 后实例属性不可改validate_assignmentTrue/False赋值时重跑校验str_strip_whitespaceTrue/False字符串自动去首尾空格strictTrue/False全局严格模式extra默认是ignore多余字段静默丢弃。做接口契约解析时我会用forbid只要调用方传了没定义的字段就直接报错这能在早期暴露客户端与文档不一致的问题。但是注意extraforbid也会把一些合理的扩展字段拒之门外建议小范围使用别全局无脑开。8.2 严格模式什么时候真正需要strict 模式下18不会转成 18true不会转成 True一切按照 Python 的严格类型来。适合你有十足把握数据来源类型完全规范或者对宽松转换的隐蔽风险特别敏感的场合。不过我的经验是大多数 Web 项目不值得全局开 strict。因为 HTTP 层天然是字符串开 strict 等于自己把 Pydantic 最大的转换优势废掉。更合理的做法是选择性使用——某几个对类型极其敏感的字段单独Annotated[int, Strict()]其他地方继续保持宽松转换。局部严格比全局严格实用得多。8.3 validate_assignment 与不可变模型默认情况下user.age 20这种赋值不会触发校验类型注解形同虚设。开了validate_assignmentTrue后赋值时也会重新校验适合对数据一致性要求高的领域模型。同理frozenTrue会让修改属性直接报ValidationError相当于一个轻量级不可变对象。这两个配置都有轻微性能开销通常可以忽略真正要注意的是别在热路径里频繁赋值导致额外校验开销被放大。9. 踩坑记录Pydantic实操中我反复摔跟头的地方最后一章不写理论知识全是我实际项目里踩过的坑。每一条都是用线上故障换来的经验。9.1 v1 和 v2 的 API 混用这是最高频的坑。网上老教程多很多人把parse_obj和model_dump混着写。v2 里parse_obj变成了model_validateparse_raw变成了model_validate_json。我的建议是新项目一律 v2升级老项目时至少跑一遍官方迁移工具并且全局搜索上面几个关键词逐一确认。9.2 bool 转换的混乱现实前面提过 bool 转换。实际踩坑场景是前端传了个0字符串给接口Pydantic v2 里到底能不能转成 False我的经验是不要赌这个默认行为。数据入口处统一做一层规范化或者自定义一个field_validator(modebefore)用一张明确的映射表把0/1/0/1/true/false/True/False全部映射到布尔值。业务代码永远不该去猜测上游传的是什么格式。9.3 默认值共享事故可变默认值问题在真实项目里出现过不止一次class Team(BaseModel): members: list[str] Field(default_factorylist) # 正确 # members: list[str] [] # 错误可变对象共享用错误写法时多个实例共享同一个 listA 实例加成员B 实例也看得到。这种 bug 特别隐蔽不是每次运行都会炸而是等到某个实例莫名多了数据才发现。Pydantic 文档对此有明确要求建议把这条写进团队代码规范。9.4 在 FastAPI 之外单用时的性能认知很多人觉得 Pydantic 慢其实那是 v1 的老印象。v2 的校验核心在 Rust 里跑性能已经非常好了。但有一种情况仍然会拖慢程序在超高频率的循环里反复构造同一个模型实例。比如每秒处理几十万条日志每条日志都包一层 BaseModel这个开销就值得在意。解决办法是高频纯数据处理路径上用原生 tuple/dict数据出口和入口处再用 Pydantic 把关。Pydantic 用在边界不用在每一个细粒度计算里。9.5 错误信息太笼统时的排查技巧e.errors()会给你结构化错误但真实业务里多层嵌套模型报错时光看 msg 不够。我常用两招第一打印e.errors(include_urlFalse)去掉文档链接日志干净很多第二地方便起见直接print(e)它会给出带路径的错误描述比如1 validation error for User / age / Input should be a valid integer [typeint_type]一眼就能看出是哪个字段、什么原因。遇到为什么明明传了字段还说 required的时候先查字段名拼写和 alias 配置十有八九是 alias 的问题。9.6 一个最后的实用建议如果你在建一个服务端项目最快上手 Pydantic 的路径不是孤立地学它而是先写一个 FastAPI 的最小接口感受一下请求体自动被校验是什么体验再回头单独研究 Pydantic。理解了入口校验、类型转换、出口序列化这条完整链路你对 Pydantic 基础用法的掌握就已经超过大多数只背过示例代码的开发者了。我当年就是在一次线上事故后痛定思痛把接口层全部换成 Pydantic 模型从此这类问题就很少再回来找我了。 Pydantic基础用法全解析：数据校验、类型转换与序列化最佳实践
1. 先搞清楚为什么你的代码里需要Pydantic这篇聊的是 Pydantic 基础用法但它不会是从安装到 API 的流水账。起因是我又双叒在凌晨被值班电话叫醒线上订单接口报错排查半天发现从第三方回调里拿到的age字段不是数字而是字符串30代码里直接用age 60判断字符串和整数比较在 Python 3 里直接抛 TypeError。这种问题我遇到过不下五次后来把所有数据入口都换成 Pydantic 做校验转换类似的线上事故基本绝迹。这里说的 Pydantic 基础用法核心就三件事数据校验、类型转换、序列化导出。校验是说字段该是 int 必须是 int该必填的不能缺转换是说外部传过来的数据哪怕全是字符串Pydantic 也会按类型注解帮你转成合适的 Python 类型序列化是说模型对象能一键变回字典或 JSON 字符串方便返回给前端或落库。这三件事要是拆成三套工具做每套都维护一套类型定义迟早对不上。Pydantic 用一个模型类就把它们全部定义清楚这就是它最大的价值。它的适用范围比多数人想象中广。写 API 时校验请求体是最常见的用法FastAPI 底层就是靠它微服务之间传消息、读配置文件、解析外部开放平台的回调都可以拿它当统一的数据入口守卫。不适合的场景也有如果你已经有一份完全可信的内部数据只是要在内存里高频读写的纯计算逻辑硬套 Pydantic 反而多了一层没必要的数据结构开销。搞清楚什么场景该用、什么场景不该用比学会写模型类更重要。1.1 没有校验层时代码会变成什么样没有 Pydantic 的处理逻辑通常是这样的def handle_user(data: dict): # data来自HTTP请求没人保证字段齐全 if name not in data or not isinstance(data[name], str): raise ValueError(name参数非法) if age not in data: raise ValueError(age缺失) age int(data[age]) # 万一data[age]是abc这里直接抛异常 if age 0 or age 150: raise ValueError(age范围非法) return {name: data[name], age: age}字段少还好业务字段一多每个接口都写这么一段代码里就全是防御式 if。更麻烦的是字典这种结构本身没有任何类型约束你传data[name]给下游函数时IDE 不会提示你它是字符串重构时换个 key 名也不会立刻报错。而 Pydantic 把校验逻辑声明式地写在模型类里业务代码拿到的就是一个类型明确的模型对象IDE 补全、重构、类型检查全都能用上。1.2 为什么校验转换序列化必须合成一个工具单独做校验的办法很多jsonschema、cerberus、手写 if都能做。但 Pydantic 把这三个环节捆在一起因为外部数据往往以字符串形态存在——HTTP 的 query 参数全是字符串数据库读出来的字段可能是 Decimal、datetime 这类对象。校验完还要转成代码里方便用的类型用的时候又要转回去给别人。如果拆成三套工具每个环节都要维护一份类型定义迟早出现校验通过的字段序列化时却报错的尴尬。用一个模型类统一描述输入输出的规格这是从工程角度最省心的做法。2. 环境准备与你的第一个Pydantic模型2.1 安装与版本选择先装包。2024 年之后的项目直接装 v2 系列就好pip install pydantic检查版本python -c import pydantic; print(pydantic.__version__)如果是 2.x 开头就说明你用的是 v2 语法如果装到了 1.x很多 API 都不一样强烈建议升级pip install pydantic2。这里必须多说一句版本问题。网上搜 Pydantic 教程一半是 v1 时代的写法parse_obj、dict()、json()、validator、class Config这些在 v2 里全变了。v2 最大的变化是底层校验核心用 Rust 重写了性能比 v1 快好几倍API 也重新设计过。如果你刚接触请直接学 v2遇到老帖子时要会区分版本。后面所有示例都以 v2 为准老 API 我会附带提一句对应关系。2.2 定义模型继承 BaseModelPydantic 的核心是BaseModel。用普通 class 继承它照常写字段注解from pydantic import BaseModel class User(BaseModel): name: str age: int email: str | None None user User(name张三, age18) print(user.name) # 张三 print(user.age) # 18注意是int print(type(user.age)) # class int print(user.email) # Noneage18传进去的是字符串但模型实例的age已经是 int。这就是 Pydantic 和普通 dataclass 最大的区别普通 dataclass 你传什么就是什么Pydantic 会按注解做一次合法范围内的自动转换字符串18能被明确解析成数字 18所以不报错传abc则转换失败立刻抛ValidationError。需要特别强调的是Pydantic 在实例化时才做校验不是在定义模型时。模型类本身只是声明调用构造方法的那一刻才校验数据。这个时间点关系很重要后面讲到性能优化和批量导入时会用到。2.3 转换失败时报错信息怎么读实际开发中永远要用try/except捕获校验失败from pydantic import ValidationError try: User(name张三, ageabc) except ValidationError as e: print(e.errors())输出是一个列表每一项包含loc哪个字段、msg为什么失败、type错误类型。这个结构化错误可以直接转成给前端看的参数错误提示。自己手写校验逻辑的话这一步往往要手动拼错误信息而 Pydantic 已经帮你把错误结构准备好了省掉一大块样板代码。2.4 为什么宽松转类型反而是优点有人会觉得传字符串居然能正确转成 int这也太宽松了。但注意Pydantic 的宽松是有底线的只在输入能明确、无歧义地转换成目标类型时才转。18 - 18是明确转换abc - int不是所以后者报错。这个设计服务于一个现实网络传输层拿到的数据大多是字符串形态如果不自动转换就要在每个函数里自己int()、str()转换异常散落在业务代码里根本查不过来。把转换集中在数据入口业务逻辑里直接信任类型这个信任边界才是 Pydantic 给你带来的最大收益。3. 字段类型体系从int到复杂泛型的正确用法3.1 内置类型与常见陷阱Pydantic 直接复用 Python 的类型注解str、int、float、bool、bytes、list、set、dict这些都能直接用。大多数类型凭直觉就不会错真正需要留心的是 bool。bool字段在 v2 里会尝试把常见字符串形态比如true、false大小写不敏感和 0、1 转成布尔。但生产环境里不同客户端序列化的风格不一样有人传True有人传1有人传YPydantic 的默认转换未必覆盖所有野生格式。我的建议是对外接口的文档里明确要求布尔字段传true/false如果上游真的不规范就单独写一个field_validator做白名单映射不要指望默认行为兜底。另外注意 Decimal 和 datetime。金融类金额用Decimal而不是float日期用datetime、date、time。Pydantic 对 ISO 8601 格式的字符串会自动解析成 datetime 对象这个在解析接口返回值时非常常用。3.2 Optional、Union 与 None 的三种写法可选字段最常见的写法是str | None NonePython 3.10低版本用Optional[str] None。这里有两个容易忽略的点第一str | None None表示这个字段有两个约束接收字符串、允许为空。如果你只写str NonePydantic 会报错因为默认值类型和注解不匹配。第二Union[str, int]这样的多类型字段能用但不建议滥用。虽然 v2 有智能选择机制尽量帮你选一个合法类型但它终究是为数据来源极度不可控的场景准备的。绝大多数情况下你应该把类型弄得更精确而不是更模糊。用 Union 之前先问问自己这个字段到底是什么业务含义3.3 Literal、Annotated 与更精确的约束Literal可以约束字段只能取固定几个值from typing import Literal class Order(BaseModel): status: Literal[pending, paid, cancelled] Order(statuspending) # 正常 Order(statusshipped) # 报错仅允许三种值这比单纯用str强很多相当于把枚举约束提前到字段类型阶段非法状态在入口就被拦截。Annotated则可以把 Field 约束直接合并进类型里适合定义可复用的字段类型from typing import Annotated from pydantic import Field PositiveInt Annotated[int, Field(gt0)] class Order(BaseModel): total: PositiveInt这个技巧在大型项目里很有用把业务上的类型和Python 基础类型区分开字段约束可以到处复用不用每个模型都复制一遍同样的 Field 配置。4. Field约束与内置校验新手最容易忽略的防线4.1 Field 的必填、默认值与常见参数字段声明用Field函数可以附加校验约束这是新手最常忽略的一层免费校验from pydantic import BaseModel, Field class Product(BaseModel): name: str Field(..., min_length1, max_length100) price: float Field(..., gt0, le99999) sku: str Field(..., patternr^[A-Z]{3}\d{4}$) tags: list[str] Field(default_factorylist, max_length10)...表示必填。为什么不用None因为None是默认值而默认值会被当成合法输入必填字段如果没有显式传值用...会让 Pydantic 报field required语义比 None 清晰得多。这是写模型类时第一个要养成的习惯。4.2 数值边界、字符串长度与正则数值类约束参数有gt大于、ge大于等于、lt小于、le小于等于、multiple_of倍数约束字符串类有min_length、max_length、pattern集合类同样支持min_length、max_length适用于 list、set、dict。产品单价price必须是正数、SKU 必须符合公司编号规则这些业务规则完全可以用 Field 写在类型声明里根本不用写 if。校验失败的报错信息也足够友好直接把错误抛给调用方业务代码保持干净。项目里的做法是把这类模型放在 API 入口层的 schema 目录里任何外部数据进来先过一遍模型后续服务内部全都不用再担心字段格式问题。4.3 可变默认值list 和 dict 必须用 default_factory这是 Python 老坑换了个马甲出现在 Pydantic 里class Team(BaseModel): members: list[str] Field(default_factorylist) # 正确 # members: list[str] [] # 错误可变对象共享直接写 []在 Python 里是经典的共享可变对象问题多个实例会共用同一个 listA 实例往里面加成员B 实例也看得到。Pydantic 文档明确要求可变默认值一律通过default_factory生成很多 lint 规则也会拦这种写法。建议从第一天写模型就养成习惯后面不会踩这个隐蔽的坑。4.4 Field 校验失败的时机在实例化时不在使用时我见过很多同事以为 Pydantic 会实时检查字段。不是的。校验只发生在模型实例化的时候。如果你用 Pydantic 建模后来又直接通过model.attr value改了属性值默认情况下不会重新校验。要开启赋值时校验需要配置validate_assignmentTrue这个后面第 8 节详细讲。理解这个时机边界很重要否则你会写出改完属性以为校验过了的 bug。5. Validator机制自定义校验的正确姿势Field 只能覆盖单字段、单值的简单约束跨字段、需要查表、需要转换后才能判断的逻辑就要用 Validator。5.1 field_validator单字段的自定义校验v2 里写自定义单字段校验from pydantic import field_validator class Order(BaseModel): quantity: int Field(..., gt0) price: float Field(..., gt0) field_validator(quantity) classmethod def check_quantity(cls, v): if v 10000: raise ValueError(单笔订单数量过大) return vv2 的field_validator通常配合classmethod使用第一个参数是cls第二个参数是字段值v返回值会作为最终值替换原值。如果你想在类型转换前看原始输入用modebefore默认modeafter是在 Pydantic 完成内置类型转换之后执行你的逻辑此时v已经是干净的int类型。field_validator还支持一次校验多个字段field_validator(name, sku)多个字段共用同一套校验逻辑时很省事。要注意的是如果字段本身类型转换失败比如quantityabc那么后续field_validator根本不会执行因为数据没到达那一步。排查validator 没触发问题时先确认是不是类型转换阶段就挂了。5.2 model_validator跨字段联动校验单字段校验管不了开始时间必须早于结束时间这种跨字段约束要用model_validatorfrom datetime import datetime from pydantic import model_validator class Booking(BaseModel): start_at: datetime end_at: datetime model_validator(modeafter) def check_time_range(self): if self.end_at self.start_at: raise ValueError(end_at必须晚于start_at) return selfmodeafter表示模型已经构造完成可以在self上读任意字段并做联动校验另一种modebefore拿到的还是原始 dict适合对整个输入做预处理。我个人的习惯是能用 after 就用 after因为你能拿到的是已经验证过的字段值逻辑写起来直观可靠。5.3 校验顺序与报错合并Pydantic 的校验顺序是先做内置类型转换再执行field_validator最后执行model_validator。如果多个字段都校验失败错误会被合并收集在同一个ValidationError.errors()里返回而不是抛第一个就停止。这对 API 场景极其友好——一次能把所有字段的错误都返回给前端让用户一起改而不是改一个重新提交一次。5.4 从 v1 迁移过来的人最容易踩的语法差异老代码里validator是同步方法第一个参数是字段值模型配置写在class Config里。v2 里validator改名field_validator并且要求类方法风格Config类改成model_config ConfigDict(...)。升级老项目时建议全局搜索parse_obj、.dict()、.json()、validator、Config这几个关键词逐个替换否则编译不报错、运行时全是兼容性错误比语法报错难查得多。6. 序列化与数据导出不只是model_dump模型实例最终要返回给外部或者落库、进队列这时候需要把对象导出成字典或 JSON。6.1 三个导出方法的定位方法输出典型场景model_dump()Python 原生 dict传给其他函数、转 dict 后处理model_dump_json()JSON 字符串返回给 HTTP 客户端、写文件model_dump(modejson)JSON 兼容类型的 dict需要 dict 但值必须能json.dumps很多 v1 老教程的写法是model.dict()和model.json()这两个在 v2 已废弃。新项目直接记model_dump和model_dump_json即可。modejson这个参数特别实用它会确保 datetime 变成字符串、Decimal 变成字符串或数字总之是一个JSON 安全的 dict比先 dump 再 json.dumps 再 json.loads那套绕路写法高效得多。6.2 exclude / include / exclude_none控制导出范围实际生产中不是所有字段都要导出。用户模型里可能有密码哈希、内部工号返回给前端时要排除class User(BaseModel): id: int name: str password: str user.model_dump(exclude{password}) # {id: 1, name: 张三}exclude_noneTrue可以去掉所有为 None 的字段避免 JSON 里一堆email: null。还有include是白名单方式和 exclude 互斥按需使用。对嵌套模型exclude 可以跟进到子字段比如exclude{address: {city}}细节很多实际用到时查文档即可。6.3 alias输入输出字段名不一致怎么办前后端字段命名风格经常不一致后端用 snake_case前端接口文档却用 camelCase。alias 机制就是干这个的from pydantic import ConfigDict class UserOut(BaseModel): user_name: str Field(validation_aliasuserName, serialization_aliasuserName) model_config ConfigDict(populate_by_nameTrue)validation_alias决定接收输入时认哪个 keyserialization_alias决定导出时输出哪个 keyalias参数同时设置两者populate_by_nameTrue允许你用 Python 字段名传值。配合model_dump(by_aliasTrue)输出 camelCase前端直接消费后端内部继续用 snake_case两边都舒服。但要注意alias 的实际效果比示例复杂嵌套 alias、validate_by_alias、serialize_by_alias三个开关各有职责项目里统一配置好再全局使用别一个模型一个样。6.4 自定义序列化field_serializer有时候默认导出格式不满足要求比如日期要YYYY/MM/DD而不是 ISO 格式用field_serializerfrom pydantic import field_serializer class Event(BaseModel): created_at: datetime field_serializer(created_at) def serialize_time(self, v: datetime) - str: return v.strftime(%Y/%m/%d %H:%M:%S)这个功能和field_validator方向相反validator 管进serializer 管出两边的逻辑都写在模型里进出的规则始终是同一份定义。7. 嵌套模型与复杂结构设计真实项目里几乎没有模型是纯扁平的。订单里有用户用户里有地址地址里还有经纬度。Pydantic 对嵌套结构处理得相当顺手。7.1 内嵌模型字典自动变成对象class Address(BaseModel): city: str street: str class OrderUser(BaseModel): name: str address: Address u OrderUser(name张三, address{city: 北京, street: 中关村大街1号}) print(u.address.city) # 北京外部传进来的address是普通 dictPydantic 会自动把它转换成Address实例。你再也不用手写Address(**data[address])这种样板代码。这也意味着嵌套属性访问是链式的u.address.cityIDE 能自动补全重构时字段改名也会报错提醒。7.2 List、Dict、Set 等容器类型容器类型同样支持自动转换class Order(BaseModel): items: list[AddressItem] Order(items[{name: 苹果, price: 3.5}, {name: 梨, price: 4.5}])list[AddressItem]里的每个 dict 都会被转成 AddressItem 实例。注意 Python 3.9 以下不支持list[X]这种写法要用List[X]Python 3.9 两者都行。如果容器里混入非法元素错误信息会定位到具体索引比如items.1.price排查起来非常方便。7.3 递归模型和自引用树形结构、评论楼中楼这类场景需要模型引用自身class TreeNode(BaseModel): name: str children: list[TreeNode] [] root TreeNode(nameroot, children[{name: child}])用字符串做前向引用即可。如果运行时出现类型未解析的错误调用TreeNode.model_rebuild()可以强制重新解析内部引用。递归模型是 Pydantic 相对高级但很实用的能力注意别在无环数据上写无限递归逻辑那会导致构造过程死循环。7.4 从 ORM 对象构建模型Pydantic 不只能吃字典还能吃任意对象ORM 实例。只要配置from_attributesTrueclass UserOut(BaseModel): id: int name: str model_config ConfigDict(from_attributesTrue) user_out UserOut.model_validate(db_user) # db_user是SQLAlchemy对象这个能力让ORM 模型到 API 响应模型的转换完全自动化。有人觉得可以直接把 ORM 对象塞给 FastAPI 返回但那样会把数据库表结构直接暴露给前端风险很大。标准做法永远是定义一个独立的响应模型把 ORM 实例转进去只保留你想暴露的字段。这是 Pydantic 在 Web 项目里最核心的用法之一。8. 模型配置与行为控制模型类里还有一个设置区——model_config它控制模型整体行为而不是单个字段。8.1 ConfigDict 核心参数速查from pydantic import ConfigDict class User(BaseModel): model_config ConfigDict( extraforbid, # 多余字段怎么处理 frozenTrue, # 是否冻结不可变 validate_assignmentTrue, # 是否在属性赋值时校验 str_strip_whitespaceTrue, # 自动去除字符串首尾空白 ) name: str age: int参数取值含义extraignore/forbid/allow多余字段忽略、拒绝、或保留到__pydantic_extra__frozenTrue/FalseTrue 后实例属性不可改validate_assignmentTrue/False赋值时重跑校验str_strip_whitespaceTrue/False字符串自动去首尾空格strictTrue/False全局严格模式extra默认是ignore多余字段静默丢弃。做接口契约解析时我会用forbid只要调用方传了没定义的字段就直接报错这能在早期暴露客户端与文档不一致的问题。但是注意extraforbid也会把一些合理的扩展字段拒之门外建议小范围使用别全局无脑开。8.2 严格模式什么时候真正需要strict 模式下18不会转成 18true不会转成 True一切按照 Python 的严格类型来。适合你有十足把握数据来源类型完全规范或者对宽松转换的隐蔽风险特别敏感的场合。不过我的经验是大多数 Web 项目不值得全局开 strict。因为 HTTP 层天然是字符串开 strict 等于自己把 Pydantic 最大的转换优势废掉。更合理的做法是选择性使用——某几个对类型极其敏感的字段单独Annotated[int, Strict()]其他地方继续保持宽松转换。局部严格比全局严格实用得多。8.3 validate_assignment 与不可变模型默认情况下user.age 20这种赋值不会触发校验类型注解形同虚设。开了validate_assignmentTrue后赋值时也会重新校验适合对数据一致性要求高的领域模型。同理frozenTrue会让修改属性直接报ValidationError相当于一个轻量级不可变对象。这两个配置都有轻微性能开销通常可以忽略真正要注意的是别在热路径里频繁赋值导致额外校验开销被放大。9. 踩坑记录Pydantic实操中我反复摔跟头的地方最后一章不写理论知识全是我实际项目里踩过的坑。每一条都是用线上故障换来的经验。9.1 v1 和 v2 的 API 混用这是最高频的坑。网上老教程多很多人把parse_obj和model_dump混着写。v2 里parse_obj变成了model_validateparse_raw变成了model_validate_json。我的建议是新项目一律 v2升级老项目时至少跑一遍官方迁移工具并且全局搜索上面几个关键词逐一确认。9.2 bool 转换的混乱现实前面提过 bool 转换。实际踩坑场景是前端传了个0字符串给接口Pydantic v2 里到底能不能转成 False我的经验是不要赌这个默认行为。数据入口处统一做一层规范化或者自定义一个field_validator(modebefore)用一张明确的映射表把0/1/0/1/true/false/True/False全部映射到布尔值。业务代码永远不该去猜测上游传的是什么格式。9.3 默认值共享事故可变默认值问题在真实项目里出现过不止一次class Team(BaseModel): members: list[str] Field(default_factorylist) # 正确 # members: list[str] [] # 错误可变对象共享用错误写法时多个实例共享同一个 listA 实例加成员B 实例也看得到。这种 bug 特别隐蔽不是每次运行都会炸而是等到某个实例莫名多了数据才发现。Pydantic 文档对此有明确要求建议把这条写进团队代码规范。9.4 在 FastAPI 之外单用时的性能认知很多人觉得 Pydantic 慢其实那是 v1 的老印象。v2 的校验核心在 Rust 里跑性能已经非常好了。但有一种情况仍然会拖慢程序在超高频率的循环里反复构造同一个模型实例。比如每秒处理几十万条日志每条日志都包一层 BaseModel这个开销就值得在意。解决办法是高频纯数据处理路径上用原生 tuple/dict数据出口和入口处再用 Pydantic 把关。Pydantic 用在边界不用在每一个细粒度计算里。9.5 错误信息太笼统时的排查技巧e.errors()会给你结构化错误但真实业务里多层嵌套模型报错时光看 msg 不够。我常用两招第一打印e.errors(include_urlFalse)去掉文档链接日志干净很多第二地方便起见直接print(e)它会给出带路径的错误描述比如1 validation error for User / age / Input should be a valid integer [typeint_type]一眼就能看出是哪个字段、什么原因。遇到为什么明明传了字段还说 required的时候先查字段名拼写和 alias 配置十有八九是 alias 的问题。9.6 一个最后的实用建议如果你在建一个服务端项目最快上手 Pydantic 的路径不是孤立地学它而是先写一个 FastAPI 的最小接口感受一下请求体自动被校验是什么体验再回头单独研究 Pydantic。理解了入口校验、类型转换、出口序列化这条完整链路你对 Pydantic 基础用法的掌握就已经超过大多数只背过示例代码的开发者了。我当年就是在一次线上事故后痛定思痛把接口层全部换成 Pydantic 模型从此这类问题就很少再回来找我了。