Python pydantic 的 v1 到 v2 迁移路径

小伙伴们有没有觉得学习文章很有意思？有意思就对了！今天就给大家带来《Python pydantic 的 v1 到 v2 迁移路径》，以下内容将会涉及到，若是在学习中对其中部分知识点有疑问，或许看了本文就能帮到你！

Pydantic v2 与 v1 不兼容，必须重写模型类：元类冲突、验证器改用 @field_validator/@modelvalidator、禁用可变默认值、移除 parse* 方法、错误结构扁平化、配置改用 model_config。

pydantic.BaseModel 不能直接继承 v1 的类

Pydantic v2 彻底移除了 BaseModel 的 v1 兼容层，所有继承自 v1 BaseModel 的类在 v2 下会报 TypeError: metaclass conflict 或静默行为异常。这不是语法问题，而是元类和验证逻辑重构导致的底层不兼容。

• 必须重写所有模型类，不能靠 from pydantic import BaseModel 替换就完事
• v1 中用 @validator、@root_validator 的地方，v2 改用 @field_validator 和 @model_validator，且签名和触发时机不同
• 如果项目里混用了 v1 模型（比如第三方库返回的），别试图用 v2 模型去继承它——要么升级依赖，要么用 model_construct() 手动转成 v2 实例

Field(default=...) 和 Field(default_factory=...) 的行为差异变大了

v2 对字段默认值的解析更严格，尤其在嵌套结构或可变对象场景下，容易出现意外的共享引用或校验跳过。

• Field(default=[]) 在 v1 中虽不推荐但能跑，在 v2 中会直接报 PydanticUserError：「mutable default」被明确禁止
• 必须改用 Field(default_factory=list)，同理 dict、set 等都得走 default_factory
• v2 中 default 只接受不可变字面量（None、42、"abc"），而 default_factory 必须是无参 callable，不能带参数或闭包捕获外部变量

parse_obj()、parse_raw()、from_orm() 全部被移除

这些 v1 的工厂方法在 v2 中统一收口到模型类本身的 __init__ 和 model_validate() / model_validate_json()，旧代码会直接报 AttributeError。

• MyModel.parse_obj(data) → 改用 MyModel.model_validate(data)
• MyModel.parse_raw(json_str) → 改用 MyModel.model_validate_json(json_str)
• MyModel.from_orm(db_obj) → 改用 MyModel.model_validate(db_obj, from_attributes=True)，注意必须显式传 from_attributes=True
• 如果用了 Config.orm_mode = True，v2 中要换成 model_config = ConfigDict(from_attributes=True)

错误信息格式和字段名映射变了，调试时容易懵

v2 的 ValidationError 错误结构扁平化，errors() 返回的字典 key 从 v1 的 loc 元组变成字符串路径（如 "user.name"），而且缺失字段不再默认补 None，而是直接报错。

• v1 报错可能是 [{'loc': ('age',), 'msg': 'field required', ...}]，v2 是 [{'type': 'missing', 'loc': ['age'], ...}] —— 注意 loc 是 list 不是 tuple，且不含字段类型前缀
• 自定义错误提示要用 model_config = ConfigDict(strict=False) 配合 strict 参数控制，不能靠 v1 的 allow_population_by_field_name
• 如果用了 FastAPI，它的自动错误渲染依赖 v2 的 error schema，升级后接口 422 响应体字段路径会变，前端校验逻辑可能需要微调

事情说清了就结束。最麻烦的不是语法改写，而是那些藏在测试用例、mock 数据构造、ORM 交互桥接里的隐式 v1 行为——它们不会报错，但会在某个边缘 case 里悄悄产出错数据。

到这里，我们也就讲完了《Python pydantic 的 v1 到 v2 迁移路径》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！