Python Pydantic怎样对多个字段实施联合约束

表单里同时有 password 和 password_repeat，或者有 start_at 与 end_at，这类规则不是单个字段能决定的。Python Pydantic 实施联合约束时，优先把“比较完整模型”的规则放到 @model_validator(mode='after')；只有确实依赖字段定义顺序、且只需要读取已验证字段时，才用 @field_validator 配合 ValidationInfo.data。

官方地址：https://docs.pydantic.dev/latest/

判断标准很简单：规则描述的是对象之间的关系，就放模型级；规则只修正或检查某一个字段，就放字段级。模型级校验更不依赖字段顺序，也更适合表达“两个字段必须同时满足”的业务条件。

先把联合约束拆成两类规则

第一次设计模型时，最容易把所有检查都写进字段校验器。这样做的问题是：一个字段的校验器可能在另一个字段尚未完成解析时运行，规则会悄悄依赖类中字段的排列顺序。

把规则先按边界分组，后面的权限配置、验证阶段和失败处理才不会互相缠绕。下面用一个注册模型说明完整落点。

把跨字段规则放进 model_validator

Pydantic 2.x 的 model_validator(mode='after') 在整个模型完成字段验证后运行。它收到的是模型实例，适合直接比较多个已经解析好的属性；校验通过时必须返回当前实例。

from typing_extensions import Self

from pydantic import BaseModel, ValidationError, model_validator


class RegisterForm(BaseModel):
    password: str
    password_repeat: str
    start_at: int
    end_at: int

    @model_validator(mode="after")
    def check_relation(self) -> Self:
        # 完整模型已完成字段解析，适合集中比较多个字段。
        if self.password != self.password_repeat:
            raise ValueError("两次密码不一致")
        # 区间规则和密码规则共享同一模型级失败边界。
        if self.end_at 

这里的关键不是把错误写成一行，而是让模型承担一个清晰的“联合约束门禁”：密码规则和时间区间规则都在对象完整之后判断。若任意一条失败，调用方得到 ValidationError，而不是一个半完成的对象。

字段级校验只读取已经准备好的数据

有些规则只围绕一个字段，但需要参考另一个前置字段，例如确认字段必须与已经解析的密码相等。这时可以使用 ValidationInfo.data，但要注意 Pydantic 按字段定义顺序校验；被读取的字段必须写在前面。

from pydantic import BaseModel, ValidationInfo, field_validator


class PasswordForm(BaseModel):
    # password 必须先定义，password_repeat 的 data 中才可能读到它。
    password: str
    password_repeat: str

    @field_validator("password_repeat", mode="after")
    @classmethod
    def match_password(cls, value: str, info: ValidationInfo) -> str:
        # 只读取已验证的前置字段，避免依赖未完成的字段。
        if value != info.data["password"]:
            raise ValueError("两次密码不一致")
        # 字段校验器也必须返回当前字段值。
        return value

这种写法适合小而局部的比较，但它有一个明确的维护成本：一旦有人把 password 移到后面，info.data 的内容就会改变。涉及三个以上字段、可选字段或复杂分支时，回到模型级校验通常更稳。

把触发器、门禁和失败处理写成一条工作流

实际项目里可以把一次模型验证看成一条小型自动化工作流：输入触发模型解析，字段门禁先处理类型和格式，模型门禁再处理字段关系，最后由接口层统一接收失败信息。这样排查时不会把“类型错误”和“业务关系错误”混成一类。

1. 触发场景：请求体、配置文件或消息进入 RegisterForm。
2. 字段阶段：用 Field 与 field_validator 处理单字段规则；字段级比较只读取已完成的前置字段。
3. 模型阶段：用 model_validator(mode="after") 处理密码、时间区间等联合约束。
4. 失败处理：保留 ValidationError 的结构化错误，交给接口层映射为可读提示；不要用空值或默认值掩盖不一致。
5. 通知复盘：按规则名称统计失败原因，检查是客户端输入问题还是模型约束写错。

如果需要检查原始输入是否包含某个不应出现的字段，可用 model_validator(mode="before")，但它拿到的是未经解析的数据，不能假定输入一定是字典，也不应在抛错前随意修改原始对象。

默认值和测试边界不要漏掉

Pydantic 文档特别提醒：默认值默认不会自动参与验证，自定义校验器也不会因此被调用。如果联合约束依赖默认字段，必须在模型配置和测试用例中明确这条策略，不要以为声明了校验器就等于覆盖所有输入路径。

这套复查表就是质量门禁：它不要求把每条规则都塞进同一个装饰器，而是要求每条规则都有稳定的触发位置、失败出口和测试样例。

几个容易踩坑的地方

• 不要用字段顺序隐藏复杂关系。两三个字段的比较还能读懂，关系继续增长时应迁移到 model_validator。
• 不要忘记返回值。after 模型校验要返回实例，字段校验要返回字段值。
• 谨慎使用 before。它面对的是原始输入，类型可能完全不符合注解；要先判断输入形态。
• 不要把错误吞成空对象。联合约束失败通常意味着请求不满足业务条件，应保留结构化错误供接口层处理。

总结

Python Pydantic 实施多个字段联合约束时，先按“单字段”与“对象关系”分层：字段格式交给 Field 或 field_validator，跨字段关系优先交给 model_validator(mode="after")。只有局部且有明确字段顺序的规则，才通过 ValidationInfo.data 读取前置字段。再把默认值、失败错误和字段顺序纳入测试，验证工作流就会清晰许多。

相关问题

Pydantic 联合约束一定要用 model_validator 吗？

不一定。只依赖一个前置字段的局部规则可以用 field_validator，但复杂关系、可选字段组合和多个分支更适合模型级校验。

ValidationInfo.data 为什么读不到另一个字段？

字段校验按定义顺序进行，目标字段可能还没有完成验证。调整字段顺序或改用模型级校验，通常比依赖隐含顺序更容易维护。