FastAPI中鉴别联合类型pet_type字段OpenAPI schema优化方案咨询

核心目标是让Python构造对象时无需手动传入pet_type，同时保证OpenAPI schema中将其标记为必填字段，解决TypeScript无法穷尽匹配的问题。

推荐方案：使用Pydantic验证器自动填充字段 #

通过验证器在对象初始化时自动设置pet_type的值，同时保持字段定义为必填（不设置默认值）。这样既满足Python侧构造的便捷性，又能让OpenAPI schema正确标记该字段为必填。

Pydantic v1 实现示例 #

from pydantic import BaseModel, Literal, validator, Field
from typing import Union

class Cat(BaseModel):
    pet_type: Literal['cat']
    meows: int

    @validator('pet_type', pre=True, always=True)
    def auto_set_pet_type(cls, value):
        # 强制设置pet_type为'cat'，构造时无需传入
        return 'cat'

class Dog(BaseModel):
    pet_type: Literal['dog']
    barks: float

    @validator('pet_type', pre=True, always=True)
    def auto_set_pet_type(cls, value):
        return 'dog'

class PetCollection(BaseModel):
    pet: Union[Cat, Dog] = Field(..., discriminator='pet_type')
    n: int

Pydantic v2 实现示例（更简洁） #

from pydantic import BaseModel, Literal, BeforeValidator
from typing import Annotated, Union

def set_cat_type(_):
    return 'cat'

def set_dog_type(_):
    return 'dog'

class Cat(BaseModel):
    pet_type: Annotated[Literal['cat'], BeforeValidator(set_cat_type)]
    meows: int

class Dog(BaseModel):
    pet_type: Annotated[Literal['dog'], BeforeValidator(set_dog_type)]
    barks: float

class PetCollection(BaseModel):
    pet: Union[Cat, Dog] = Field(..., discriminator='pet_type')
    n: int

方案对比 #

• 方案1（手动传参）：繁琐易出错，每次构造Cat/Dog都要重复传入pet_type，不符合DRY原则。
• 方案2（元类重写__init__）：实现复杂，且可能破坏类型检查工具（mypy、Pylance）的类型推断，增加维护成本。
• 推荐方案：利用Pydantic原生验证器能力，逻辑清晰，不破坏类型推断，同时完美兼顾Python侧便捷性和OpenAPI schema的正确性。

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