Pydantic v2 是 Python 的数据校验与序列化库，于 2023 年 6 月发布，基于 Rust 实现的 pydantic-core 近乎完全重写。其 API 与 v1 相似但不完全相同，若干 v1 写法会静默失效或行为改变。本技能文档记录 v2 的惯用写法、v1 迁移陷阱以及 FastAPI 集成面。
版本信息 资料称当前稳定版为 2.13（截至 2026-04-19），配套 Python 3.10-3.14，包含 3.14 自由线程构建。近期版本要点：
- 2.11（2025）：schema 构建时间提升 2 倍，嵌套模型内存降低 2-5 倍，支持 PEP 695/696 泛型语法，实验性支持自由线程 Python 3.13，新增 validate_by_alias / validate_by_name / serialize_by_alias 配置（populate_by_name 待 v3 弃用），Path 与 deque 不再接受约束。
- 2.12：支持 Python 3.14（PEP 649/749 注解），实验性 MISSING 哨兵，字段级 exclude_if，JSON 输出的 ensure_ascii，serialize_as_any 统一行为，@model_validator(mode="after") 的 classmethod 写法被弃用，应写为实例方法。
- 2.13（2026 年 4 月）：多态序列化（model_dump(polymorphic_serialization=True)），exclude_if 扩展到计算字段，StringConstraints 的 ascii_only，model_fields_set 跟踪实例化后新增的额外字段。
按场景查阅
- 从零编写新模型：核心模型模式 + 校验器
- 从 v1 迁移：v1 -> v2 迁移清单
- 金额 / 小数处理：货币精度（CWE-681 防御）
- FastAPI 请求 / 响应模型：FastAPI 集成
- 性能敏感热路径：性能说明
- 密钥处理 / 脱敏：安全与密钥
- 校验可观测性或 LLM 智能体：PydanticAI 与 Logfire
核心模型模式 使用 model_config = ConfigDict(...) 取代 v1 的内部类 Config；用 Annotated[T, Field(...)] 或 Annotated[T, StringConstraints(...)] 附加约束，优于 constr()、conint()、condecimal() 包装器；@computed_field 取代 v1 的 @property + validator(always=True) 组合，并自动出现在 model_dump() 中；@field_validator("字段名") 取代 v1 的 @validator，装饰器为 classmethod，需在其后加 @classmethod；@model_validator(mode="before"|"after") 取代 v1 的 @root_validator，mode="after" 时返回 self 而非 dict，且 2.12+ 起 mode="after" 上的 @classmethod 已弃用，应写为普通实例方法。优先使用 validate_by_alias / validate_by_name / serialize_by_alias（2.11+）而非旧的 populate_by_name=True。Path 与 deque 在 2.11+ 不再接受 Field 约束，需自定义校验器。MISSING 哨兵（2.12，实验性）可在校验时区分“未提供”与“显式默认值”。
校验器 模式选择：after（默认）适用于约 90% 场景，对已强制转换的值做逻辑，速度快，返回与字段同类型；before 用于重塑原始输入（字符串拆分、旧键映射），有 Python 回调开销，返回任意值随后再强制转换；wrap 用于捕获 ValidationError、加日志、强制 PydanticUseDefault，最慢；plain 完全自定义，不做强制转换与下游校验，按原样信任，对类型安全有风险。性能规则：尽量用 Field(...) 或 Annotated 元数据表达约束，由 Rust 引擎处理；Python 级校验器有逐值调用开销。 字段校验器可接收 ValidationInfo，其中 info.data 为已校验字段（按声明顺序，无法访问后面的字段），info.context 为用户通过 model_validate(data, context={...}) 传入的字典，info.mode 为 "python"|"json"|"strings"，info.field_name 为当前字段名。 Annotated 校验器（AfterValidator、BeforeValidator、WrapValidator）适合跨模型复用。顺序规则：Before 与 Wrap 校验器从右到左运行，After 校验器从左到右运行，装饰器式 @field_validator 最后追加。 错误定制可用 PydanticCustomError 提供机器可读错误类型、模板与上下文字典；直接抛 ValueError 会自动包装为 Pydantic 错误；避免使用 assert（在 python -O 下会被跳过）；loc 由校验器位置决定，不可在抛出点编辑。 继承方面，基类的模型校验器会在子类实例上运行，子类覆盖会替换（而非扩展）父类逻辑，建议优先用 Annotated 校验器组合而非深层继承。
序列化 v2 重命名了 v1 方法：model.dict() -> model.model_dump()，model.json() -> model.model_dump_json()，Model.parse_obj -> Model.model_validate，Model.parse_raw -> Model.model_validate_json，Model.construct -> Model.model_construct，Model.schema() -> Model.model_json_schema()，Model.fields -> Model.model_fields。旧名仍可用但会告警，生产环境应使用 v2 名称。 序列化模式：mode="python" 保留原生类型（Decimal 仍为 Decimal），mode="json" 转为 JSON 兼容类型（Decimal -> str、UUID -> str、datetime -> ISO），mode="strings" 全部转为字符串。支持 exclude、include、exclude_none、by_alias、round_trip 等参数；2.13+ 支持 polymorphic_serialization=True 按实际子类类型序列化并暴露子类独有字段。 自定义序列化器有三种：@field_serializer 按字段、@model_serializer(mode="wrap") 整模型包装（调用 handler(self) 获取默认输出再后处理）、以及可复用的 Annotated PlainSerializer / WrapSerializer。when_used 取值："always"（默认）、"json"、"json-unless-none"、"unless-none"。 JSON Schema 有 validation 与 serialization 两种模式，分别对应请求形状与响应形状；FastAPI 两者都用，Pydantic v2 原生面向 OpenAPI 3.1。 别名有三种：alias 同时影响输入与输出，validation_alias 仅输入，serialization_alias 仅输出；2.11 起可用 validate_by_alias / validate_by_name / serialize_by_alias 按配置控制。 快速 JSON 输出：model_dump_json() 已快于 json.dumps(model_dump())；热路径可用 MyModel.pydantic_serializer.to_json(model) 直接从 Rust 得到 bytes，并在模块级缓存 pydantic_serializer。round_trip=True 可保证 dump 后再 validate 得到等价实例（RootModel、判别联合、别名字段），但带副作用的计算字段缓存状态不保证往返。
判别联合 用 Annotated[Union[A, B], Field(discriminator="type")] 让某字段决定解析哪个模型。相比 v1 联合更快（pydantic-core 直接选分支而非逐个尝试），错误信息也更清晰。
货币精度（CWE-681 防御） 金额绝不用 float。两种惯用方式：Annotated[Decimal, Field(max_digits=14, decimal_places=2, ge=0)]（推荐），或 condecimal(max_digits=14, decimal_places=2, ge=0)（仍支持）。货币运算可配合 decimal.getcontext() 设置舍入模式，如 ROUND_HALF_EVEN（银行家舍入）。
配置管理（pydantic-settings） v2 将配置抽取为独立包 pydantic-settings（pip install pydantic-settings）。用 BaseSettings 与 SettingsConfigDict 配置 env_file、env_file_encoding、env_prefix、case_sensitive 等。SecretStr / SecretBytes 会在 repr 与 model_dump_json 中隐藏值，适用于所有 API 密钥、密码、令牌；读取值用 get_secret_value()。来源优先级（高到低）：初始化参数 > 环境变量 > .env 文件 > 默认值。
FastAPI 集成 响应模型：用 response_model 指定输出模型，FastAPI 会按该模型序列化，从而剥离如 password_hash 等仅服务端字段，优于手工构造 dict。请求校验可自定义错误信封，通过 @app.exception_handler(RequestValidationError) 返回 JSONResponse。
限制与注意事项 资料未提供该技能的安装命令、收费方式、平台支持范围或具体使用步骤；上述内容均为 Pydantic v2 库本身的特性说明。部分特性标注为实验性（如 MISSING 哨兵、自由线程支持），部分写法标注为待弃用（如 populate_by_name、mode="after" 的 classmethod），迁移时需留意。