Pydantic 字段(Field)详解：模型字段的高级配置指南

Pydantic 字段(Field)详解：模型字段的高级配置指南

pydantic 项目地址: https://gitcode.com/gh_mirrors/pyd/pydantic

引言

在 Python 数据验证和设置管理领域，Pydantic 的 Field 功能提供了强大的字段定制能力。本文将深入探讨 Pydantic 中 Field 的各种用法和配置选项，帮助开发者更好地控制模型字段的行为。

默认值设置

基础默认值

通过 default 参数可以为字段设置静态默认值：

from pydantic import BaseModel, Field

class User(BaseModel):
    name: str = Field(default='John Doe')

动态默认值

使用 default_factory 可以指定一个可调用对象来生成默认值：

from uuid import uuid4

class User(BaseModel):
    id: str = Field(default_factory=lambda: uuid4().hex)

重要提示：

• default 和 default_factory 是互斥的，不能同时使用
• typing.Optional 并不等同于设置默认值为 None

字段别名系统

Pydantic 提供了灵活的别名机制，支持三种类型的别名：

1. 统一别名：alias 参数，同时用于验证和序列化
2. 验证别名：validation_alias 参数，仅用于验证
3. 序列化别名：serialization_alias 参数，仅用于序列化

别名优先级

当多种别名同时存在时，优先级顺序为：

1. validation_alias > alias (验证时)
2. serialization_alias > alias (序列化时)

数值约束

Pydantic 支持多种数值验证约束：

class NumberConstraints(BaseModel):
    positive: int = Field(gt=0)          # 必须大于0
    non_negative: int = Field(ge=0)      # 必须大于等于0
    negative: int = Field(lt=0)          # 必须小于0
    non_positive: int = Field(le=0)      # 必须小于等于0
    even: int = Field(multiple_of=2)     # 必须是2的倍数
    special: float = Field(allow_inf_nan=True)  # 允许无穷大和NaN

JSON Schema 映射：

• gt/lt → exclusiveMinimum/exclusiveMaximum
• ge/le → minimum/maximum
• multiple_of → multipleOf

字符串约束

字符串字段支持以下约束：

class StringConstraints(BaseModel):
    short: str = Field(min_length=3)     # 最小长度3
    long: str = Field(max_length=10)     # 最大长度10
    regex: str = Field(pattern=r'^\d*$') # 必须匹配正则表达式

JSON Schema 映射：

• min_length → minLength
• max_length → maxLength
• pattern → pattern

高级特性

严格模式

启用严格模式后，Pydantic 将禁止类型自动转换：

class StrictModel(BaseModel):
    strict_field: str = Field(strict=True)  # 必须严格匹配类型
    lax_field: int = Field(strict=False)    # 允许类型转换

字段不可变性

通过 frozen 参数可以使字段不可变：

class ImmutableModel(BaseModel):
    id: str = Field(frozen=True)  # 创建后不可修改

默认值验证

使用 validate_default 可以控制是否验证默认值：

class ValidatedDefault(BaseModel):
    age: int = Field(default='twelve', validate_default=True)  # 会验证默认值

最佳实践

1. 对于复杂类型，建议使用 Annotated 结合 Field 来避免潜在问题
2. 在团队协作中，明确别名策略以避免混淆
3. 生产环境中推荐启用严格模式以确保数据一致性
4. 对于关键字段，考虑设置不可变属性

通过合理运用 Pydantic 的 Field 功能，开发者可以构建出既灵活又健壮的数据模型，满足各种复杂业务场景的需求。

pydantic 项目地址: https://gitcode.com/gh_mirrors/pyd/pydantic