如何在Pydantic模型中实现二选一可选参数的清晰验证？

可以通过拆分职责的方式，把单个字段的独立验证、两个字段的互斥二选一逻辑完全分开，用Pydantic的内置特性替代臃肿的自定义验证器，代码会更清晰易维护：

1. 单个字段的独立验证：用内置类型约束替代自定义验证器 #

Pydantic提供了很多内置的类型和字段约束，可以直接实现id>0、len(txt)==4的要求，不需要写自定义验证器：

• 对于id：用PositiveInt类型，自动保证值大于0
• 对于txt：用constr(min_length=4, max_length=4)，自动约束字符串长度为4

2. 互斥二选一逻辑：用模型级验证器单独处理 #

单独编写模型级的验证器，只负责检查id和txt是否必须且只能存在一个，和单个字段的验证逻辑完全分离。

完整代码示例 #

from pydantic import BaseModel, PositiveInt, constr, model_validator, ValidationError
from typing import Optional

class RequestModel(BaseModel):
    id: Optional[PositiveInt] = None
    txt: Optional[constr(min_length=4, max_length=4)] = None

    @model_validator(mode='after')
    def check_exclusive_fields(self):
        # 统计非空字段的数量
        provided_fields = sum(1 for val in [self.id, self.txt] if val is not None)
        if provided_fields != 1:
            raise ValueError("必须且只能传入id或txt其中一个参数")
        return self

测试验证 #

# 合法场景
valid_id_request = RequestModel(id=123)
valid_txt_request = RequestModel(txt="abcd")

# 非法场景：同时传入id和txt
try:
    RequestModel(id=123, txt="abcd")
except ValidationError as e:
    print(e)  # 会抛出"必须且只能传入id或txt其中一个参数"的错误

# 非法场景：两个参数都不传
try:
    RequestModel()
except ValidationError as e:
    print(e)  # 同样抛出上述错误

# 非法场景：id为非正数
try:
    RequestModel(id=0)
except ValidationError as e:
    print(e)  # 抛出"Input should be a positive integer"的错误

# 非法场景：txt长度不符合要求
try:
    RequestModel(txt="abc")
except ValidationError as e:
    print(e)  # 抛出"String should have at least 4 characters"的错误

进阶优化（Pydantic v2+） #

如果使用Pydantic v2及以上版本，可以用ExclusiveUnion进一步简化互斥逻辑的实现，不过需要调整模型结构为根类型：

from pydantic import BaseModel, PositiveInt, constr, ExclusiveUnion

class RequestModel(BaseModel):
    __root__: ExclusiveUnion[
        dict[id, PositiveInt],
        dict[txt, constr(min_length=4, max_length=4)]
    ]

这种方式不需要手动编写模型验证器，由Pydantic自动处理互斥逻辑，但API请求的参数结构需要对应调整为根对象形式。

内容的提问来源于stack exchange，提问作者marcel h