如何在Pydantic v2模型中实现条件性必填字段

在Pydantic v2的开发场景中，条件性必填字段是非常常见的需求，比如当订单类型为线下订单时，必须填写线下门店编号，而线上订单则不需要该字段。Pydantic v2提供了多种灵活的方式来实现这类动态校验逻辑，不需要编写过于复杂的自定义代码。

使用field_validator实现单字段条件必填

如果只需要根据其他字段的值判断单个字段是否必填，可以使用field_validator装饰器。这种方式逻辑清晰，适合简单的条件判断场景。

以下是一个示例，当user_type为enterprise时，company_name字段为必填，否则可选：

from pydantic import BaseModel, field_validator, ValidationError

class UserModel(BaseModel):
    user_type: str  # 用户类型，可选值为personal或enterprise
    company_name: str | None = None  # 默认可选

    @field_validator('company_name')
    def check_company_name(cls, v, info):
        # 获取其他字段的值
        user_type = info.data.get('user_type')
        if user_type == 'enterprise' and v is None:
            raise ValueError('企业用户必须填写公司名称')
        return v

# 测试正常场景
try:
    user1 = UserModel(user_type='enterprise', company_name='测试公司')
    print('企业用户校验通过:', user1)
except ValidationError as e:
    print('校验失败:', e)

# 测试异常场景
try:
    user2 = UserModel(user_type='enterprise')
    print('校验通过:', user2)
except ValidationError as e:
    print('校验失败:', e)

# 测试个人用户场景
try:
    user3 = UserModel(user_type='personal')
    print('个人用户校验通过:', user3)
except ValidationError as e:
    print('校验失败:', e)

使用model_validator实现多字段联动条件必填

当需要根据多个字段的值判断多个字段是否必填，或者校验逻辑涉及多个字段的联动时，使用model_validator装饰器会更合适，它可以在模型整体校验阶段处理复杂的逻辑。

以下示例中，当delivery_type为express时，express_address和receiver_phone都为必填：

from pydantic import BaseModel, model_validator, ValidationError

class OrderModel(BaseModel):
    delivery_type: str  # 配送类型，可选值为self_pick或express
    express_address: str | None = None
    receiver_phone: str | None = None

    @model_validator(mode='after')
    def check_delivery_fields(self):
        if self.delivery_type == 'express':
            if not self.express_address:
                raise ValueError('快递配送必须填写收货地址')
            if not self.receiver_phone:
                raise ValueError('快递配送必须填写收货人电话')
        return self

# 测试正常快递订单
try:
    order1 = OrderModel(
        delivery_type='express',
        express_address='北京市朝阳区xx路',
        receiver_phone='13800138000'
    )
    print('快递订单校验通过:', order1)
except ValidationError as e:
    print('校验失败:', e)

# 测试异常快递订单
try:
    order2 = OrderModel(delivery_type='express', express_address='北京市朝阳区xx路')
    print('校验通过:', order2)
except ValidationError as e:
    print('校验失败:', e)

# 测试自提订单
try:
    order3 = OrderModel(delivery_type='self_pick')
    print('自提订单校验通过:', order3)
except ValidationError as e:
    print('校验失败:', e)

结合Annotated类型实现更简洁的条件必填

Pydantic v2支持Annotated类型配合AfterValidator或BeforeValidator实现更简洁的校验逻辑，适合将校验规则与字段定义更紧密结合的场景。

以下是使用Annotated和AfterValidator实现条件必填的示例：

from typing import Annotated, Any
from pydantic import BaseModel, AfterValidator, ValidationError

def check_optional_field(v: Any, info) -> Any:
    # 这里可以根据info中的其他字段值判断当前字段是否必填
    # 示例：当extra_info_required为True时，当前字段必填
    if info.data.get('extra_info_required') and v is None:
        raise ValueError('当前字段为必填项')
    return v

class InfoModel(BaseModel):
    extra_info_required: bool
    extra_info: Annotated[str | None, AfterValidator(check_optional_field)] = None

# 测试必填场景
try:
    info1 = InfoModel(extra_info_required=True, extra_info='附加信息内容')
    print('必填场景校验通过:', info1)
except ValidationError as e:
    print('校验失败:', e)

# 测试非必填场景
try:
    info2 = InfoModel(extra_info_required=False)
    print('非必填场景校验通过:', info2)
except ValidationError as e:
    print('校验失败:', e)

注意事项

• 使用field_validator时，要注意校验的执行顺序，默认情况下校验器会按照字段定义的顺序执行，如果需要依赖的字段还未被校验，可能需要调整校验器的执行顺序。
• model_validator的mode参数可以选择before或after，after模式下所有字段已经完成基础校验，更适合处理字段联动的逻辑。
• 条件必填的校验逻辑中，要明确判断的边界情况，比如字段值为空字符串、None等不同情况的区分，避免出现校验漏洞。

通过上述几种方式，开发者可以根据实际的业务场景选择最合适的实现方案，灵活处理Pydantic v2模型中的条件性必填字段需求，提升数据校验的准确性和灵活性。

Pydantic_v2数据校验条件必填模型字段pydantic修改时间：2026-07-14 07:39:27