如何在单个Pydantic类中实现字段间的取值依赖约束？

方法1：使用联合类型+Literal（推荐，Schema更清晰） #

这种方式直接把每种动物的合法组合定义为独立子模型，再通过Union组合，FastAPI会自动生成明确的Schema，清晰展示每种type对应的voice取值。

from pydantic import BaseModel, Literal
from typing import Union

class Dog(BaseModel):
    type: Literal["dog"]
    voice: Literal["barks"]

class Cat(BaseModel):
    type: Literal["cat"]
    voice: Literal["meows"]

class Duck(BaseModel):
    type: Literal["duck"]
    voice: Literal["croaks"]

Animal = Union[Dog, Cat, Duck]

在FastAPI的自动文档中，会显示三个可选的Schema选项，每个都明确绑定了对应的type和voice，完全满足你对Schema清晰度的要求。

方法2：使用模型验证器（单类实现） #

如果必须保持单个Animal类的结构，可以用Pydantic的模型验证器来检查type和voice的匹配关系：

Pydantic v2 版本 #

from pydantic import BaseModel, model_validator, Literal

class Animal(BaseModel):
    type: Literal["dog", "cat", "duck"]
    voice: Literal["barks", "meows", "croaks"]

    @model_validator(mode="after")
    def check_voice_match_type(self) -> "Animal":
        voice_map = {
            "dog": "barks",
            "cat": "meows",
            "duck": "croaks"
        }
        if self.voice != voice_map[self.type]:
            raise ValueError(f"{self.type} must have voice '{voice_map[self.type]}', got '{self.voice}'")
        return self

Pydantic v1 版本 #

from pydantic import BaseModel, validator, Literal

class Animal(BaseModel):
    type: Literal["dog", "cat", "duck"]
    voice: Literal["barks", "meows", "croaks"]

    @validator("voice")
    def check_voice_match_type(cls, v, values):
        if "type" in values:
            voice_map = {
                "dog": "barks",
                "cat": "meows",
                "duck": "croaks"
            }
            if v != voice_map[values["type"]]:
                raise ValueError(f"{values['type']} must have voice '{voice_map[values['type']]}', got '{v}'")
        return v

这种方式维持了单个类的结构，但注意：FastAPI的Schema不会直接显示type和voice的关联关系，只会列出各自的可选值，约束依赖验证逻辑来保证。

两种方法对比 #

• 联合类型法：Schema直观易懂，前端能直接获取每种动物的合法声音组合，自动完成输入提示，适合需要明确展示约束的场景。
• 模型验证器法：保留单个类结构，适合已有代码依赖单个Animal类的场景，但Schema无法体现关联关系，需额外说明约束规则。

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