拓冰网站定制 
1. Pydantic 到底帮你解决了什么问题先说结论Pydantic 是 Python 生态里做数据校验和序列化最顺手的库之一核心就一句话——用 Python 的类型注解定义数据模型在数据进入程序的那一刻完成校验、清洗和转换。在 Python 里你大概率写过这样的代码def register_user(name, age, email): if not isinstance(name, str): raise TypeError(name 必须是字符串) if not isinstance(age, int): raise TypeError(age 必须是整数) if age 0 or age 150: raise ValueError(age 范围不合法) if not in email: raise ValueError(email 格式不对) return {name: name, age: age, email: email}这种手写校验的问题在于校验逻辑散落在业务代码里每加一个字段就要多写一堆 if项目大了之后根本维护不动。Pydantic 的解法是让数据模型本身自带规则from pydantic import BaseModel class User(BaseModel): name: str age: int email: str user User(name张三, age25, emailzhangsanexample.com)就这么简单。类型注解即校验规则数据不对直接报错正确数据还能自动做类型转换——比如你传了字符串25进来只要声明是int它会帮你转成整数。这个自动转换特性在实际开发里太实用了尤其是对接外部 API、读取配置文件、解析 JSON 响应的场景。它适合谁来学只要你在用 Python 做 Web 开发FastAPI 底层就是 Pydantic、写爬虫解析数据、做数据处理管道、管理配置项或者干脆就是被字典套字典这种无结构代码折磨过的人Pydantic 都值得纳入工具箱。新手友好的地方在于语法非常直觉——声明一个类写清楚字段类型剩下的交给它不用理解任何魔法。2. 模型定义与字段类型从最基础开始写2.1 最小可用的模型长什么样Pydantic 的核心概念叫BaseModel你定义的每个数据模型都继承它。最基本的用法就是声明字段和类型from pydantic import BaseModel class Item(BaseModel): name: str price: float is_offer: bool False这里name和price是必填字段没有默认值就必须传入is_offer带了默认值False不传也没关系。实例化模型时Pydantic 会逐个检查字段item Item(name咖啡, price9.9) print(item) # name咖啡 price9.9 is_offerFalse如果你漏掉必填字段会收到一条非常明确的报错如果类型对不上但能转换它会尝试转换完全不能转换直接抛出ValidationError。这一点后面细说。我在实际项目里最常用的字段类型有这么几类字段类型声明方式典型场景基础类型strintfloatbool几乎所有模型枚举Enum的子类状态、类型、角色等受限取值日期时间datetime.datedatetime.datetime时间戳、生日、创建时间列表list[str]List[int]标签数组、ID 集合字典dict[str, str]键值对、扩展属性嵌套模型另一个BaseModel子类用户包含地址、订单包含商品可选字段Optional[str]或str | None允许为空的字段2.2 默认值与可选字段的坑在 Pydantic v2 里可选字段推荐写法是field: str | None None别用Optional[str]也行两者等价但|写法更符合 Python 3.10 的习惯。这里有个新手常踩的坑声明了str | None不代表可以缺省只是说值可以是 None该字段仍然是必填的除非给了默认值。要让它变成可不传就必须带上默认值from pydantic import BaseModel class Profile(BaseModel): nickname: str | None None # 可不传缺省为 None bio: str | None # 报错没有默认值必须显式传值或传 None这两行的区别非常关键。前者是选填字段后者是必填但允许值为 None。很多人在对接外部接口时看到对方文档写bio nullable就直接按选填处理结果漏传字段导致报错排查半天才发现是默认值没给。我自己的习惯是只要外部字段可能缺失就一律写成str | None None宁可在业务层再判断空值也别被 Pydantic 拦住。2.3 验证信息类字段创建时间from datetime import datetime class Post(BaseModel): title: str content: str created_at: datetime None # 类型错误这个不行上面这种写法会报错因为created_at的类型是datetime但默认值是NonePydantic 的类型检查不允许除非声明Optional。如果想让created_at自动填当前时间可以用默认值工厂from datetime import datetime from pydantic import BaseModel, Field class Post(BaseModel): title: str content: str created_at: datetime Field(default_factorydatetime.now)default_factory接受一个无参函数每次实例化模型时都会调用它生成默认值。这样每条记录创建时都自动带上当时的时间而不是模型类被导入那一刻的时间。这是个高频考点用datetime.now()做默认值会在导入模块时固定时间所有实例共享同一个时间戳用default_factory才是真正动态的。创建时间、UUID、随机数这类需求老老实实用default_factory。3. 字段校验的进阶玩法不只是类型检查3.1 Pydantic 的校验流程是怎样的当你写出User(name张三, age25)这行代码时Pydantic 内部做了三件事收集字段值把传入的参数和模型定义的字段一一对应类型判断与转换看声明的类型是否能匹配如果能强制转换比如字符串25转整数25直接转执行字段级和模型级校验器跑你自定义的校验逻辑。第三步就是我们自己扩展的地方。Pydantic 的校验器有四种级别字段校验器field_validator、模型校验器model_validator、类型校验器自定义__get_validators__和配置校验model_config中的约束。日常开发用得最多的是前两种。3.2 用 field_validator 给字段加业务规则假设用户注册时手机号必须是 11 位数字from pydantic import BaseModel, field_validator class User(BaseModel): name: str phone: str field_validator(phone) classmethod def validate_phone(cls, value: str) - str: if len(value) ! 11 or not value.isdigit(): raise ValueError(手机号必须是11位数字) return value注意两个细节field_validator装饰器要放在类方法上面方法必须是 classmethodv2 中不写classmethod会告警或报错校验器函数返回的值会替代原始输入所以你可以在这里做数据清洗比如去掉空白字符、统一小写from pydantic import BaseModel, field_validator class User(BaseModel): email: str field_validator(email) classmethod def normalize_email(cls, value: str) - str: return value.strip().lower()这样即使客户端传了 ZhangSanExample.COM 模型里存的也是干净的zhangsanexample.com。数据清洗放在模型层的好处是——所有走到业务逻辑的数据都是干净的不用在每处使用地方重复处理。3.3 多字段联动的模型校验器有些规则不是针对单个字段而是要跨字段比较。比如注册时确认密码和密码要一致from pydantic import BaseModel, model_validator class RegisterForm(BaseModel): username: str password: str confirm_password: str model_validator(modeafter) def check_passwords_match(self): if self.password ! self.confirm_password: raise ValueError(两次输入的密码不一致) return selfmodeafter表示在单个字段校验全部完成之后再跑这个模型级校验器此时self已经是一个完整的模型实例可以任意访问字段。还有个modebefore会在字段校验之前运行它接收的数据是还没处理过的原始字典适合做整体性的数据预处理。这块的区分逻辑很简单before 改输入after 改输出验证整体状态。3.4 联合类型和类型转换的边界Pydantic 的自动转换很方便但能转和该转是两回事。看个例子from pydantic import BaseModel class Score(BaseModel): value: int s1 Score(value85) # 字符串转 int成功 s2 Score(value85) # 直接是 int成功 s3 Score(value85.5) # 浮点转 int成功但值变成了 85第三个例子要特别注意85.5转成int后变成了85小数部分被静默丢弃。这在统计分数、计算金额的场景里就是灾难。如果你希望浮点数不被悄悄截断用strictTrue开启严格模式from pydantic import BaseModel, ConfigDict class Score(BaseModel): model_config ConfigDict(strictTrue) value: int s Score(value85.5) # 报错Input should be a valid integer严格模式下Pydantic 不做任何隐式转换类型不符就直接报错。对外部数据源比如用户提交的表单、第三方 API 响应我建议在边界处使用严格模式宁可报错也不要静默地拿到被改过的数据。内部自己拼接的数据则无所谓默认的宽松模式反而省事。如果你需要接收整数或整数字符串这种灵活的输入可以用Union[int, str]配合校验器处理v2 里更推荐用Annotated加上约束from typing import Annotated from pydantic import BaseModel, Field class Item(BaseModel): quantity: Annotated[int, Field(ge1, le100)] 1Field(ge1, le100)表示 quantity 的取值范围在 1 到 100 之间超出直接报错。同样支持的还有gt大于、lt小于、min_length、max_length字符串长度、pattern正则匹配等。能用 Field 约束表达的就别手写校验器代码少、报错信息还规范。4. 嵌套模型与复杂结构模型套模型才是日常4.1 把一个模型塞进另一个模型实际业务里的数据很少是扁平的。一个订单包含用户信息和商品列表这是最典型的场景。Pydantic 的嵌套模型写法很直观from pydantic import BaseModel from typing import List class Address(BaseModel): city: str street: str class User(BaseModel): name: str address: Address class Order(BaseModel): order_id: str user: User items: List[str] data { order_id: 20240101, user: {name: 张三, address: {city: 北京, street: 中关村}}, items: [咖啡, 蛋糕] } order Order(**data)也就是说嵌套模型会自动递归校验。你传一个字典进去Pydantic 会自动把字典转成对应的Address实例你传错的字段名或类型它在最深层也会准确报出是哪一层的哪个字段出了问题。这种字典套字典的结构在真实 API 响应里太常见了用嵌套模型管理后代码可读性提升一大截IDE 的自动补全和跳转也好用了。4.2 List、Dict 和 Optional 的组合拳复杂结构基本都逃不开这三种容器类型from typing import Dict, List, Optional from pydantic import BaseModel class Product(BaseModel): sku: str tags: List[str] [] attrs: Dict[str, str] {} remark: Optional[str] None product Product( skuA1001, tags[新品, 热销], attrs{color: 白色, size: L} )这里tags: List[str] []是可变默认值Pydantic 内部会做防御性拷贝所以不会出现多个实例共享同一个列表这种经典 Python 陷阱。Dict[str, str]会校验所有键和值都是字符串。嵌套容器类型比如List[List[int]]、Dict[str, List[float]]也完全支持Pydantic 会逐层递归校验。4.3 model_config 全局设置从能用到好用from pydantic import BaseModel, ConfigDict class BaseConfig(BaseModel): model_config ConfigDict( extraforbid, # 禁止传入未定义字段 frozenTrue, # 模型实例不可修改 populate_by_nameTrue, # 允许用字段别名填充 )这三个配置项是最常用的extraforbid传入未声明的字段直接报错能帮你及时发现接口字段定义遗漏或拼写错误。默认是ignore静默忽略未定义字段容易被坑。如果你对接的 API 字段经常变动考虑allow——把多余字段存进__pydantic_extra__后面还能取出来用。frozenTrue实例创建后不可修改任何字段类似只读对象适合配置类、常量类模型。populate_by_nameTrue当字段有别名alias时允许同时用别名和 Python 字段名传参。典型场景是 JSON 里的字段是下划线风格、Python 代码里要写驼峰风格或反过来给字段加Field(aliasuser_id)数据填充时原始字段名和别名都能识别。5. 序列化与解析把模型变回 JSON一个数据模型在程序里好用还不够你总得把它发给前端、存进数据库或者传给下游服务这时候就需要序列化。Pydantic 提供了几个非常顺手的 API。5.1 model_dump 和 model_dump_jsonfrom pydantic import BaseModel class User(BaseModel): name: str age: int u User(name李四, age30) # 转成字典 data u.model_dump() # {name: 李四, age: 30} # 转成 JSON 字符串 json_str u.model_dump_json() # {name:李四,age:30}注意两点v2 用model_dump()替代了 v1 的dict()很多教程还是老的dict()写法在 v2 里也能跑但会告警尽快换成新 API 更省心。model_dump_json()返回的是字符串model_dump()返回的是可继续处理的原生字典。如果你的模型里有datetime字段model_dump_json()默认会输出 ISO 格式字符串from datetime import datetime from pydantic import BaseModel class Event(BaseModel): name: str time: datetime e Event(name发布会, timedatetime(2025, 1, 1, 10, 30)) print(e.model_dump_json()) # {name:发布会,time:2025-01-01T10:30:00}这个默认行为在大多数前端场景都够用了。如果要自定义时间格式可以用json_encoders配置from pydantic import BaseModel, ConfigDict from datetime import datetime class Event(BaseModel): model_config ConfigDict(json_encoders{datetime: lambda v: v.strftime(%Y/%m/%d %H:%M)}) name: str time: datetime不过说句实话自定义 JSON 编码器在 v2 里支持得不算优雅更推荐的做法是定义专门的响应模型response model在视图层做格式转换模型层保持干净。5.2 解析外部数据model_validate 与 model_validate_jsonfrom pydantic import BaseModel class User(BaseModel): name: str age: int data {name: 王五, age: 28} # 注意 age 是字符串 user User.model_validate(data) print(user.age) # 28已被自动转为 intmodel_validate()接收字典或对象model_validate_json()接收 JSON 字符串。它们是 v2 中替代 v1 的parse_obj()和parse_raw()的新 API数据从外部进来时首选这两个入口。还有一个很香的场景直接解析 JSON 文件。import json from pydantic import BaseModel class Config(BaseModel): host: str port: int 8080 with open(config.json, r, encodingutf-8) as f: config Config.model_validate(json.load(f))配置文件、外部 API 响应、数据库查询结果……用模型统一收口后后续代码里全是类型明确的字段访问而不是data[host]这种会随手打错键名的字典操作。5.3 等价的 pydantic 类型转换函数除了模型自身的方法Pydantic 还提供了一层类型转换函数适用于不定义完整模型的快速场景from pydantic import TypeAdapter # 把一个普通 dict 转成目标类型 adapter TypeAdapter(list[int]) result adapter.validate_python([1, 2, 3]) print(result) # [1, 2, 3]TypeAdapter是 v2 中非常灵活的工具能对任意类型做校验转换不局限于BaseModel子类。我常拿它校验配置项或命令行参数省去定义模型的仪式感。6. 使用 FastAPI 时的 Pydantic 联动体验如果你做 Web 开发一定会遇到 Pydantic 和 FastAPI 的黄金组合。FastAPI 的Body、Query、Path参数校验全部委托给 Pydantic而且 OpenAPI 文档自动生成。from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float app.post(/items/) async def create_item(item: Item): return {message: fitem {item.name} created, price: item.price}这里item: Item路径参数意味着 FastAPI 会自动把请求体 JSON 解析成Item实例校验失败时自动返回 422 错误和错误明细。在 FastAPI 路由函数里拿到的是一个类型明确的模型而不是裸字典配合 IDE 的补全和类型检查开发体验完全是另一个档次。常见联动配置from pydantic import BaseModel, Field class Item(BaseModel): name: str Field(..., min_length1, max_length20, description商品名称) price: float Field(..., gt0, description价格必须大于0)Field(..., ...)中第一个...表示没有默认值、必填配合description内容能直接生成到 API 文档中。这几个实用的点结合起来接口层就不用写一堆 if 校验了。7. 常见问题与排查技巧实录7.1 v1 和 v2 的语法迁移踩坑Pydantic 两年多前从 v1 升到 v2大量旧教程和代码仍然停留在 v1 写法新手一跑就报错。最常见的几个变化v1 写法v2 写法说明parse_obj()model_validate()解析字典parse_raw()model_validate_json()解析 JSON 字符串dict()model_dump()转字典json()model_dump_json()转 JSON 字符串validatorfield_validator字段校验器root_validatormodel_validator模型校验器Config类model_config ConfigDict(...)配置方式SecretStr等用法基本不变特殊类型仍然保留如果你拿到的项目还是 v1 写的建议先确认 pip 安装的版本pip show pydantic如果输出版本号是 2.x而代码里还在用parse_obj它其实会抛AttributeError。反过来某些 v1 专属 API 在 v2 中已经不兼容最好的方式是把代码迁到新语法而不是装回旧版本。7.2 别名与自定义字段名导致的数据丢失对接外部 API 时接口返回的字段可能是user_id而你定义的 Python 字段名是userId如果不设置别名Pydantic 会报缺失字段错误。解决办法from pydantic import BaseModel, Field class User(BaseModel): user_id: str Field(aliasuserId) data {userId: U123} user User.model_validate(data) print(user.user_id) # U123注意默认情况下只认别名不认 Python 字段名。如果你希望两种名字都能传比如你既要兼容外部 API 又要方便自己构造数据就在model_config里开populate_by_nameTrue。7.3 循环引用的序列化问题如果一个模型引用了自己比如树形结构、评论的回复序列化时容易陷入递归死循环。Pydantic 提供了model_dump(exclude_noneTrue)和model_dump(exclude{children})这类字段排除机制必要时用它们截断递归链。更通用的做法是维护一个手动深度from pydantic import BaseModel from typing import Optional, List class Comment(BaseModel): content: str replies: List[Comment] [] # v2 支持自引用字符串注解序列化时如果层级太深用递归函数手动截断别依赖默认的全量导出。7.4 校验失败的报错看不懂怎么办ValidationError的默认str(error)输出 v1 是一大段文本v2 是多行结构化的 JSON。建议在开发环境里加上错误格式化from pydantic import ValidationError try: User(name, age200) except ValidationError as e: print(e.errors()) # 结构化错误列表 print(e.json()) # 格式化后的 JSON 错误信息errors()返回的是一个列表每项包含type、loc、msg、input、ctx等键一眼就能定位有问题的是哪个字段、什么类型错误。排查外部数据异常时这个输出比单纯看异常文本高效得多。8. 我的实际使用经验与扩展建议Pydantic 用久了我养成了几个固定习惯分享给大家参考。习惯一所有外部数据入口统一做模型校验。不管是读配置文件、接 API 响应还是解析数据库查询结果我都在边界处定义一个 Pydantic 模型然后model_validate一把梭。好处是业务层代码干净坏处是模型定义会多一点但这点成本换来的可维护性非常值。习惯二模型尽量细分不要一个巨型模型装所有字段。一个用户模型包含几十个字段看着全能但不同接口需要的字段完全不一样。我倾向把一个领域对象拆成多个小模型UserCreate、UserUpdate、UserResponse输入输出各用各的。Pydantic 支持模型继承公共字段放基类差异字段放子类不重复也不丢信息。习惯三配置类模型打开frozen和extraforbid。配置出错的代价比代码出错的代价大得多因为它是静默的。frozen避免代码运行到一半配置被无意修改extraforbid保证配置文件里多拼一个字母也能立刻暴露而不是被忽略后系统带着错误配置跑完整个流程。习惯四复杂校验逻辑下沉到模型层服务层只处理业务。校验器里只做数据本身的规则检查格式、范围、依赖关系跨表查库、调用外部服务这类操作别写在校验器里会拖慢所有模型实例化的速度。如果你还想往深学可以关注这几个方向Pydantic 的自定义类型实现__get_pydantic_core_schema__做自定义序列化协议、泛型模型GenericModel、TypeAdapter的复杂用法、以及 Pydantic 与 ORM 的集成from_attributesTrue能让模型直接从数据库对象构造。最后分享一个我自己工作中经常用的小技巧用 Pydantic 模型做 SQL 查询结果的行数据包装。比如用psycopg2查出数据cursor.fetchall()返回的是元组列表配合字典游标返回的是字典列表不管哪种直接User.model_validate(row_dict)就能把行数据变成类型安全的模型。配合 Python 3.10 以上的match语法整套数据处理代码写起来干净又不容易出错。Pydantic 不是那种学了会用就行的库它在项目里的渗透率会随着你用得越多而越深。数据校验是每个程序都要面对的问题与其到处写 if 判断不如花一个下午把 Pydantic 的基础用法过一遍后续的每个项目都能省下大量重复劳动。 Python数据校验与序列化：Pydantic类型注解实战指南
1. Pydantic 到底帮你解决了什么问题先说结论Pydantic 是 Python 生态里做数据校验和序列化最顺手的库之一核心就一句话——用 Python 的类型注解定义数据模型在数据进入程序的那一刻完成校验、清洗和转换。在 Python 里你大概率写过这样的代码def register_user(name, age, email): if not isinstance(name, str): raise TypeError(name 必须是字符串) if not isinstance(age, int): raise TypeError(age 必须是整数) if age 0 or age 150: raise ValueError(age 范围不合法) if not in email: raise ValueError(email 格式不对) return {name: name, age: age, email: email}这种手写校验的问题在于校验逻辑散落在业务代码里每加一个字段就要多写一堆 if项目大了之后根本维护不动。Pydantic 的解法是让数据模型本身自带规则from pydantic import BaseModel class User(BaseModel): name: str age: int email: str user User(name张三, age25, emailzhangsanexample.com)就这么简单。类型注解即校验规则数据不对直接报错正确数据还能自动做类型转换——比如你传了字符串25进来只要声明是int它会帮你转成整数。这个自动转换特性在实际开发里太实用了尤其是对接外部 API、读取配置文件、解析 JSON 响应的场景。它适合谁来学只要你在用 Python 做 Web 开发FastAPI 底层就是 Pydantic、写爬虫解析数据、做数据处理管道、管理配置项或者干脆就是被字典套字典这种无结构代码折磨过的人Pydantic 都值得纳入工具箱。新手友好的地方在于语法非常直觉——声明一个类写清楚字段类型剩下的交给它不用理解任何魔法。2. 模型定义与字段类型从最基础开始写2.1 最小可用的模型长什么样Pydantic 的核心概念叫BaseModel你定义的每个数据模型都继承它。最基本的用法就是声明字段和类型from pydantic import BaseModel class Item(BaseModel): name: str price: float is_offer: bool False这里name和price是必填字段没有默认值就必须传入is_offer带了默认值False不传也没关系。实例化模型时Pydantic 会逐个检查字段item Item(name咖啡, price9.9) print(item) # name咖啡 price9.9 is_offerFalse如果你漏掉必填字段会收到一条非常明确的报错如果类型对不上但能转换它会尝试转换完全不能转换直接抛出ValidationError。这一点后面细说。我在实际项目里最常用的字段类型有这么几类字段类型声明方式典型场景基础类型strintfloatbool几乎所有模型枚举Enum的子类状态、类型、角色等受限取值日期时间datetime.datedatetime.datetime时间戳、生日、创建时间列表list[str]List[int]标签数组、ID 集合字典dict[str, str]键值对、扩展属性嵌套模型另一个BaseModel子类用户包含地址、订单包含商品可选字段Optional[str]或str | None允许为空的字段2.2 默认值与可选字段的坑在 Pydantic v2 里可选字段推荐写法是field: str | None None别用Optional[str]也行两者等价但|写法更符合 Python 3.10 的习惯。这里有个新手常踩的坑声明了str | None不代表可以缺省只是说值可以是 None该字段仍然是必填的除非给了默认值。要让它变成可不传就必须带上默认值from pydantic import BaseModel class Profile(BaseModel): nickname: str | None None # 可不传缺省为 None bio: str | None # 报错没有默认值必须显式传值或传 None这两行的区别非常关键。前者是选填字段后者是必填但允许值为 None。很多人在对接外部接口时看到对方文档写bio nullable就直接按选填处理结果漏传字段导致报错排查半天才发现是默认值没给。我自己的习惯是只要外部字段可能缺失就一律写成str | None None宁可在业务层再判断空值也别被 Pydantic 拦住。2.3 验证信息类字段创建时间from datetime import datetime class Post(BaseModel): title: str content: str created_at: datetime None # 类型错误这个不行上面这种写法会报错因为created_at的类型是datetime但默认值是NonePydantic 的类型检查不允许除非声明Optional。如果想让created_at自动填当前时间可以用默认值工厂from datetime import datetime from pydantic import BaseModel, Field class Post(BaseModel): title: str content: str created_at: datetime Field(default_factorydatetime.now)default_factory接受一个无参函数每次实例化模型时都会调用它生成默认值。这样每条记录创建时都自动带上当时的时间而不是模型类被导入那一刻的时间。这是个高频考点用datetime.now()做默认值会在导入模块时固定时间所有实例共享同一个时间戳用default_factory才是真正动态的。创建时间、UUID、随机数这类需求老老实实用default_factory。3. 字段校验的进阶玩法不只是类型检查3.1 Pydantic 的校验流程是怎样的当你写出User(name张三, age25)这行代码时Pydantic 内部做了三件事收集字段值把传入的参数和模型定义的字段一一对应类型判断与转换看声明的类型是否能匹配如果能强制转换比如字符串25转整数25直接转执行字段级和模型级校验器跑你自定义的校验逻辑。第三步就是我们自己扩展的地方。Pydantic 的校验器有四种级别字段校验器field_validator、模型校验器model_validator、类型校验器自定义__get_validators__和配置校验model_config中的约束。日常开发用得最多的是前两种。3.2 用 field_validator 给字段加业务规则假设用户注册时手机号必须是 11 位数字from pydantic import BaseModel, field_validator class User(BaseModel): name: str phone: str field_validator(phone) classmethod def validate_phone(cls, value: str) - str: if len(value) ! 11 or not value.isdigit(): raise ValueError(手机号必须是11位数字) return value注意两个细节field_validator装饰器要放在类方法上面方法必须是 classmethodv2 中不写classmethod会告警或报错校验器函数返回的值会替代原始输入所以你可以在这里做数据清洗比如去掉空白字符、统一小写from pydantic import BaseModel, field_validator class User(BaseModel): email: str field_validator(email) classmethod def normalize_email(cls, value: str) - str: return value.strip().lower()这样即使客户端传了 ZhangSanExample.COM 模型里存的也是干净的zhangsanexample.com。数据清洗放在模型层的好处是——所有走到业务逻辑的数据都是干净的不用在每处使用地方重复处理。3.3 多字段联动的模型校验器有些规则不是针对单个字段而是要跨字段比较。比如注册时确认密码和密码要一致from pydantic import BaseModel, model_validator class RegisterForm(BaseModel): username: str password: str confirm_password: str model_validator(modeafter) def check_passwords_match(self): if self.password ! self.confirm_password: raise ValueError(两次输入的密码不一致) return selfmodeafter表示在单个字段校验全部完成之后再跑这个模型级校验器此时self已经是一个完整的模型实例可以任意访问字段。还有个modebefore会在字段校验之前运行它接收的数据是还没处理过的原始字典适合做整体性的数据预处理。这块的区分逻辑很简单before 改输入after 改输出验证整体状态。3.4 联合类型和类型转换的边界Pydantic 的自动转换很方便但能转和该转是两回事。看个例子from pydantic import BaseModel class Score(BaseModel): value: int s1 Score(value85) # 字符串转 int成功 s2 Score(value85) # 直接是 int成功 s3 Score(value85.5) # 浮点转 int成功但值变成了 85第三个例子要特别注意85.5转成int后变成了85小数部分被静默丢弃。这在统计分数、计算金额的场景里就是灾难。如果你希望浮点数不被悄悄截断用strictTrue开启严格模式from pydantic import BaseModel, ConfigDict class Score(BaseModel): model_config ConfigDict(strictTrue) value: int s Score(value85.5) # 报错Input should be a valid integer严格模式下Pydantic 不做任何隐式转换类型不符就直接报错。对外部数据源比如用户提交的表单、第三方 API 响应我建议在边界处使用严格模式宁可报错也不要静默地拿到被改过的数据。内部自己拼接的数据则无所谓默认的宽松模式反而省事。如果你需要接收整数或整数字符串这种灵活的输入可以用Union[int, str]配合校验器处理v2 里更推荐用Annotated加上约束from typing import Annotated from pydantic import BaseModel, Field class Item(BaseModel): quantity: Annotated[int, Field(ge1, le100)] 1Field(ge1, le100)表示 quantity 的取值范围在 1 到 100 之间超出直接报错。同样支持的还有gt大于、lt小于、min_length、max_length字符串长度、pattern正则匹配等。能用 Field 约束表达的就别手写校验器代码少、报错信息还规范。4. 嵌套模型与复杂结构模型套模型才是日常4.1 把一个模型塞进另一个模型实际业务里的数据很少是扁平的。一个订单包含用户信息和商品列表这是最典型的场景。Pydantic 的嵌套模型写法很直观from pydantic import BaseModel from typing import List class Address(BaseModel): city: str street: str class User(BaseModel): name: str address: Address class Order(BaseModel): order_id: str user: User items: List[str] data { order_id: 20240101, user: {name: 张三, address: {city: 北京, street: 中关村}}, items: [咖啡, 蛋糕] } order Order(**data)也就是说嵌套模型会自动递归校验。你传一个字典进去Pydantic 会自动把字典转成对应的Address实例你传错的字段名或类型它在最深层也会准确报出是哪一层的哪个字段出了问题。这种字典套字典的结构在真实 API 响应里太常见了用嵌套模型管理后代码可读性提升一大截IDE 的自动补全和跳转也好用了。4.2 List、Dict 和 Optional 的组合拳复杂结构基本都逃不开这三种容器类型from typing import Dict, List, Optional from pydantic import BaseModel class Product(BaseModel): sku: str tags: List[str] [] attrs: Dict[str, str] {} remark: Optional[str] None product Product( skuA1001, tags[新品, 热销], attrs{color: 白色, size: L} )这里tags: List[str] []是可变默认值Pydantic 内部会做防御性拷贝所以不会出现多个实例共享同一个列表这种经典 Python 陷阱。Dict[str, str]会校验所有键和值都是字符串。嵌套容器类型比如List[List[int]]、Dict[str, List[float]]也完全支持Pydantic 会逐层递归校验。4.3 model_config 全局设置从能用到好用from pydantic import BaseModel, ConfigDict class BaseConfig(BaseModel): model_config ConfigDict( extraforbid, # 禁止传入未定义字段 frozenTrue, # 模型实例不可修改 populate_by_nameTrue, # 允许用字段别名填充 )这三个配置项是最常用的extraforbid传入未声明的字段直接报错能帮你及时发现接口字段定义遗漏或拼写错误。默认是ignore静默忽略未定义字段容易被坑。如果你对接的 API 字段经常变动考虑allow——把多余字段存进__pydantic_extra__后面还能取出来用。frozenTrue实例创建后不可修改任何字段类似只读对象适合配置类、常量类模型。populate_by_nameTrue当字段有别名alias时允许同时用别名和 Python 字段名传参。典型场景是 JSON 里的字段是下划线风格、Python 代码里要写驼峰风格或反过来给字段加Field(aliasuser_id)数据填充时原始字段名和别名都能识别。5. 序列化与解析把模型变回 JSON一个数据模型在程序里好用还不够你总得把它发给前端、存进数据库或者传给下游服务这时候就需要序列化。Pydantic 提供了几个非常顺手的 API。5.1 model_dump 和 model_dump_jsonfrom pydantic import BaseModel class User(BaseModel): name: str age: int u User(name李四, age30) # 转成字典 data u.model_dump() # {name: 李四, age: 30} # 转成 JSON 字符串 json_str u.model_dump_json() # {name:李四,age:30}注意两点v2 用model_dump()替代了 v1 的dict()很多教程还是老的dict()写法在 v2 里也能跑但会告警尽快换成新 API 更省心。model_dump_json()返回的是字符串model_dump()返回的是可继续处理的原生字典。如果你的模型里有datetime字段model_dump_json()默认会输出 ISO 格式字符串from datetime import datetime from pydantic import BaseModel class Event(BaseModel): name: str time: datetime e Event(name发布会, timedatetime(2025, 1, 1, 10, 30)) print(e.model_dump_json()) # {name:发布会,time:2025-01-01T10:30:00}这个默认行为在大多数前端场景都够用了。如果要自定义时间格式可以用json_encoders配置from pydantic import BaseModel, ConfigDict from datetime import datetime class Event(BaseModel): model_config ConfigDict(json_encoders{datetime: lambda v: v.strftime(%Y/%m/%d %H:%M)}) name: str time: datetime不过说句实话自定义 JSON 编码器在 v2 里支持得不算优雅更推荐的做法是定义专门的响应模型response model在视图层做格式转换模型层保持干净。5.2 解析外部数据model_validate 与 model_validate_jsonfrom pydantic import BaseModel class User(BaseModel): name: str age: int data {name: 王五, age: 28} # 注意 age 是字符串 user User.model_validate(data) print(user.age) # 28已被自动转为 intmodel_validate()接收字典或对象model_validate_json()接收 JSON 字符串。它们是 v2 中替代 v1 的parse_obj()和parse_raw()的新 API数据从外部进来时首选这两个入口。还有一个很香的场景直接解析 JSON 文件。import json from pydantic import BaseModel class Config(BaseModel): host: str port: int 8080 with open(config.json, r, encodingutf-8) as f: config Config.model_validate(json.load(f))配置文件、外部 API 响应、数据库查询结果……用模型统一收口后后续代码里全是类型明确的字段访问而不是data[host]这种会随手打错键名的字典操作。5.3 等价的 pydantic 类型转换函数除了模型自身的方法Pydantic 还提供了一层类型转换函数适用于不定义完整模型的快速场景from pydantic import TypeAdapter # 把一个普通 dict 转成目标类型 adapter TypeAdapter(list[int]) result adapter.validate_python([1, 2, 3]) print(result) # [1, 2, 3]TypeAdapter是 v2 中非常灵活的工具能对任意类型做校验转换不局限于BaseModel子类。我常拿它校验配置项或命令行参数省去定义模型的仪式感。6. 使用 FastAPI 时的 Pydantic 联动体验如果你做 Web 开发一定会遇到 Pydantic 和 FastAPI 的黄金组合。FastAPI 的Body、Query、Path参数校验全部委托给 Pydantic而且 OpenAPI 文档自动生成。from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float app.post(/items/) async def create_item(item: Item): return {message: fitem {item.name} created, price: item.price}这里item: Item路径参数意味着 FastAPI 会自动把请求体 JSON 解析成Item实例校验失败时自动返回 422 错误和错误明细。在 FastAPI 路由函数里拿到的是一个类型明确的模型而不是裸字典配合 IDE 的补全和类型检查开发体验完全是另一个档次。常见联动配置from pydantic import BaseModel, Field class Item(BaseModel): name: str Field(..., min_length1, max_length20, description商品名称) price: float Field(..., gt0, description价格必须大于0)Field(..., ...)中第一个...表示没有默认值、必填配合description内容能直接生成到 API 文档中。这几个实用的点结合起来接口层就不用写一堆 if 校验了。7. 常见问题与排查技巧实录7.1 v1 和 v2 的语法迁移踩坑Pydantic 两年多前从 v1 升到 v2大量旧教程和代码仍然停留在 v1 写法新手一跑就报错。最常见的几个变化v1 写法v2 写法说明parse_obj()model_validate()解析字典parse_raw()model_validate_json()解析 JSON 字符串dict()model_dump()转字典json()model_dump_json()转 JSON 字符串validatorfield_validator字段校验器root_validatormodel_validator模型校验器Config类model_config ConfigDict(...)配置方式SecretStr等用法基本不变特殊类型仍然保留如果你拿到的项目还是 v1 写的建议先确认 pip 安装的版本pip show pydantic如果输出版本号是 2.x而代码里还在用parse_obj它其实会抛AttributeError。反过来某些 v1 专属 API 在 v2 中已经不兼容最好的方式是把代码迁到新语法而不是装回旧版本。7.2 别名与自定义字段名导致的数据丢失对接外部 API 时接口返回的字段可能是user_id而你定义的 Python 字段名是userId如果不设置别名Pydantic 会报缺失字段错误。解决办法from pydantic import BaseModel, Field class User(BaseModel): user_id: str Field(aliasuserId) data {userId: U123} user User.model_validate(data) print(user.user_id) # U123注意默认情况下只认别名不认 Python 字段名。如果你希望两种名字都能传比如你既要兼容外部 API 又要方便自己构造数据就在model_config里开populate_by_nameTrue。7.3 循环引用的序列化问题如果一个模型引用了自己比如树形结构、评论的回复序列化时容易陷入递归死循环。Pydantic 提供了model_dump(exclude_noneTrue)和model_dump(exclude{children})这类字段排除机制必要时用它们截断递归链。更通用的做法是维护一个手动深度from pydantic import BaseModel from typing import Optional, List class Comment(BaseModel): content: str replies: List[Comment] [] # v2 支持自引用字符串注解序列化时如果层级太深用递归函数手动截断别依赖默认的全量导出。7.4 校验失败的报错看不懂怎么办ValidationError的默认str(error)输出 v1 是一大段文本v2 是多行结构化的 JSON。建议在开发环境里加上错误格式化from pydantic import ValidationError try: User(name, age200) except ValidationError as e: print(e.errors()) # 结构化错误列表 print(e.json()) # 格式化后的 JSON 错误信息errors()返回的是一个列表每项包含type、loc、msg、input、ctx等键一眼就能定位有问题的是哪个字段、什么类型错误。排查外部数据异常时这个输出比单纯看异常文本高效得多。8. 我的实际使用经验与扩展建议Pydantic 用久了我养成了几个固定习惯分享给大家参考。习惯一所有外部数据入口统一做模型校验。不管是读配置文件、接 API 响应还是解析数据库查询结果我都在边界处定义一个 Pydantic 模型然后model_validate一把梭。好处是业务层代码干净坏处是模型定义会多一点但这点成本换来的可维护性非常值。习惯二模型尽量细分不要一个巨型模型装所有字段。一个用户模型包含几十个字段看着全能但不同接口需要的字段完全不一样。我倾向把一个领域对象拆成多个小模型UserCreate、UserUpdate、UserResponse输入输出各用各的。Pydantic 支持模型继承公共字段放基类差异字段放子类不重复也不丢信息。习惯三配置类模型打开frozen和extraforbid。配置出错的代价比代码出错的代价大得多因为它是静默的。frozen避免代码运行到一半配置被无意修改extraforbid保证配置文件里多拼一个字母也能立刻暴露而不是被忽略后系统带着错误配置跑完整个流程。习惯四复杂校验逻辑下沉到模型层服务层只处理业务。校验器里只做数据本身的规则检查格式、范围、依赖关系跨表查库、调用外部服务这类操作别写在校验器里会拖慢所有模型实例化的速度。如果你还想往深学可以关注这几个方向Pydantic 的自定义类型实现__get_pydantic_core_schema__做自定义序列化协议、泛型模型GenericModel、TypeAdapter的复杂用法、以及 Pydantic 与 ORM 的集成from_attributesTrue能让模型直接从数据库对象构造。最后分享一个我自己工作中经常用的小技巧用 Pydantic 模型做 SQL 查询结果的行数据包装。比如用psycopg2查出数据cursor.fetchall()返回的是元组列表配合字典游标返回的是字典列表不管哪种直接User.model_validate(row_dict)就能把行数据变成类型安全的模型。配合 Python 3.10 以上的match语法整套数据处理代码写起来干净又不容易出错。Pydantic 不是那种学了会用就行的库它在项目里的渗透率会随着你用得越多而越深。数据校验是每个程序都要面对的问题与其到处写 if 判断不如花一个下午把 Pydantic 的基础用法过一遍后续的每个项目都能省下大量重复劳动。