pydantic 是校验、转换、文档化外部输入数据的首选工具，其类型声明即验证规则，错误提示精准，自动转换有明确边界，field 配置需注意 default 与 default_factory 区别，v2 版本性能提升显著但需注意兼容性与 arbitrary_types_allowed 默认禁用。
Pydantic 不是“推荐用”，而是当你需要校验、转换、文档化外部输入数据时，它几乎就是唯一合理的选择——因为它的行为由 Python 类型系统驱动，验证逻辑和 IDE 提示、静态检查器（如 mypy）完全对齐，不存在“写两套规则”的割裂。
字段类型声明即验证规则
你写 email: EmailStr，就同时完成了三件事：告诉 IDE 这是个邮箱、告诉 mypy 这里只能传邮箱格式字符串、告诉运行时必须校验 TLD 和 @ 符号。不需要额外写 if "@" not in email，也不用维护独立的 schema 文件。
常见错误现象：ValidationError 报错信息直接定位到字段名和原因，比如：
1 validation error for UserCreate email value is not a valid email address (type=value_error.email)
而不是模糊的 "email format invalid" —— 这个粒度对调试和 API 错误响应都关键。
自动类型转换不是“魔法”，是有明确边界的行为
Pydantic 对常见类型（int、datetime、list[int]）做宽松转换，但只在语义明确时才转：
-
"42"→42（字符串数字转整数） -
"2023-01-01"→datetime(2023, 1, 1) -
[1, "2", b"3"]→[1, 2, 3]
但它不会把 "hello" 转成 int，也不会把 None 塞进非可选字段。这种“能转则转、不能转就报错”的策略，比手写 int(data.get("id") or "0") 更安全，也比全关闭转换更实用。
Field 配置容易误用，尤其 default 和 default_factory
这两个参数看着像 Python 默认参数，但行为完全不同：
-
is_active: bool = True：字段可省略，缺失时设为True -
created_at: datetime = Field(default_factory=datetime.now)：每次实例化都调用一次datetime.now() -
created_at: datetime = Field(default=datetime.now())：⚠️ 错！所有实例共享同一个时间戳（函数只执行一次）
另一个坑：Field(...) 表示“必填且无默认值”，不是省略号语法糖，漏写会变成可选字段。
V2 版本的性能和兼容性现实
如果你还在用 V1 的 @validator 或 @root_validator，现在应该迁移到 V2 的 @field_validator 和 @model_validator —— 不仅 API 更一致，底层 Rust 引擎也让验证速度提升 5–10 倍。但要注意：from pydantic import v1 as pydantic_v1 只适合渐进迁移，混用 V1 模型和 V2 模型会导致 ValidationError 信息不一致，尤其是嵌套模型场景。
真正容易被忽略的是：V2 默认禁用 arbitrary_types_allowed=True，如果你模型里用了自定义类（比如 Decimal 或 ORM 实例），必须显式开启，否则直接报 TypeError，而不是进入验证流程。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
