Pydantic字段类型新增了哪些

本文目录导读：

1. 精确数值类型（v2 新引入的 decimal_xxx 系列）
2. 网络类型（v2 优化并新增）
3. 严格类型模式与 Strict 类型
4. 新集合类型
5. 泛型容器与 RootModel
6. 可区分联合类型（Discriminated Unions）
7. 序列化类型别名
8. InstanceOf 类型
9. 未来特性（v2.10+）
10. 总结：v2 新增字段类型速查表

截至 2025 年 5 月，Pydantic 的最新稳定版本是 v2.10.x（2024-2025 年发布），相比 v1.x 和 v2 早期版本，Pydantic v2 在字段类型方面新增了多个重要类型和特性，尤其是在精确数值、网络类型、集合类型、序列化控制以及类型适配方面。

以下是 Pydantic v2 相较于 v1 新增或显著改进的字段类型及用法：

精确数值类型（v2 新引入的 decimal_xxx 系列）

这是 v2 中最重要的新类型之一，用于替代 Python 原生的 decimal.Decimal，并提供了更细粒度的控制。

• condecimal：

  • 新增参数：decimal_places（精确小数位数）、max_digits（最大总位数）、gt、ge、lt、le。

  • 示例：

    from pydantic import BaseModel, condecimal
    class Product(BaseModel):
        price: condecimal(max_digits=10, decimal_places=2, ge=Decimal('0.01'))

• conint / confloat 的增强：

  • v2 中引入了 multiple_of 参数（v1 已有，但 v2 支持更严格的验证）。
  • 新函数：confloat 现在支持 strict=True（默认是宽松模式）。

网络类型（v2 优化并新增）

Pydantic v2 对网络类型进行了重构，现在直接基于 pydantic-core（Rust 实现），性能更好，且引入了一些新类型。

• IPv4Address / IPv6Address：直接使用 Python 标准库 ipaddress 的封装。
• IPvAnyAddress：接受 IPv4 或 IPv6 字符串。
• AnyUrl：v2 中新增的通用 URL 类型，可以接受任意协议（http, ftp, file 等）。
• HttpUrl：严格检查 http / https，并默认要求 TLD（顶级域名）存在。
• FileUrl：验证 file:/// 协议的 URL。
• PostgresDsn：专门用于验证 PostgreSQL 连接字符串。
• EmailStr：v2 中性能提升，底层使用 email-validator 库（需要额外安装）。

严格类型模式与 Strict 类型

v2 引入了显式的“严格模式”类型，用于在字段层面开启严格类型检查，而不需要全局设置 model_config。

• StrictInt、StrictFloat、StrictStr、StrictBool：

  • 效果：拒绝隐式类型转换（“123” 不会被自动转为 int）。

  • 用法：

    from pydantic import BaseModel, StrictInt
    class User(BaseModel):
        age: StrictInt  # 只接受 int，不接受 float 或字符串
    User(age=25)  # 正确
    User(age="25")  # 报错：ValidationError

新集合类型

• conset：约束集合（Set），支持 min_length、max_length、unique_items。
• conlist：约束列表，新增 unique_items 参数（v1 需要自定义验证）。
• dict / model_dict：虽然没有新类型，但 v2 的 model_dump 模式下的 mode='json' 或 by_alias=True 行为发生变化，间接影响字段序列化。

泛型容器与 RootModel

这虽然不算“字段类型”，但 v2 完全重构了 BaseModel 的底层，并引入了更清晰的泛型支持。

• RootModel：替代 v1 中的 __root__ 语法，如果你的模型只有一个字段，可以直接继承 RootModel[T]。

  from pydantic import RootModel
  # v1: class MyList(BaseModel): __root__: list[int]
  # v2:
  class MyList(RootModel[list[int]]):
      pass
  Data = MyList([1, 2, 3])

可区分联合类型（Discriminated Unions）

v2 极大改进了联合类型的处理，特别是带标识的联合（Discriminated Union）。

• 新字段类型：Annotated 配合 Discriminator。

• 效果：根据一个公共字段（type）快速推断具体模型，避免逐个尝试。

• 示例：

  from typing import Annotated, Literal, Union
  from pydantic import BaseModel, Discriminator
  class Cat(BaseModel):
      type: Literal['cat']
      name: str
  class Dog(BaseModel):
      type: Literal['dog']
      breed: str
  class Zoo(BaseModel):
      animals: list[Annotated[Union[Cat, Dog], Discriminator('type')]]

序列化类型别名

v2 引入了 Field 中新的 serialization_alias 和 validation_alias，以及 AliasGenerator，这虽然不是字段类型，但直接影响了字段的输入输出格式。

• PlainSerializer / WrapSerializer：允许为字段定义自定义序列化器。

• 示例：

  from typing import Annotated
  from pydantic import BaseModel, PlainSerializer
  class User(BaseModel):
      name: Annotated[str, PlainSerializer(lambda x: x.upper())]  # 输出时自动大写

InstanceOf 类型

v2 引入 InstanceOf 替代 v1 中可能需要的 Type 验证，用于验证某个值是某个类的实例（而不是类本身）。

• 用法：

  from pydantic import BaseModel, InstanceOf
  class MyClass:
      pass
  class Container(BaseModel):
      item: InstanceOf[MyClass]  # 必须传入 MyClass 的实例，不能是 MyClass 本身

未来特性（v2.10+）

• model_config 中的 use_enum_values：不再需要手动设置 validate_default，枚举字段的行为更可控。
• pydantic.Field 的 init_var：Pydantic 的 Field 也支持类似 dataclasses 的字段初始化控制。

v2 新增字段类型速查表

如果你正在从 Pydantic v1 升级到 v2，除了关注这些新类型，还需要特别注意 model.dict() 改为 model.model_dump()、__get_validators__ 改为 __get_pydantic_core_schema__ 等深层变化。