FastAPI结合Pydantic如何在数组中声明AnyOf类型

你当前编写的List[Union[RedPill, BluePill]]实现方式，完全可以达到Pydantic层面的AnyOf校验效果；加上你提前在两个模型里定义了Literal类型的kind标识字段，这套写法刚好是官方推荐的高可靠联合类型实现，没有核心逻辑问题。

现有写法的有效性说明 #

• 从Pydantic的校验逻辑看，Union类型在入参校验时会执行逐匹配判断：只要传入对象能匹配Union声明中任意一个模型的字段要求，就会通过校验，这和OpenAPI规范中AnyOf的语义完全一致，不会出现和预期不符的校验行为。
• 这里澄清一个常见认知误区：很多开发者会误以为Pydantic的Union和OpenAPI的OneOf语义完全对等，实际上只要不存在同时匹配多个Union内模型的入参场景（也就是你加了固定字面值kind字段之后的情况），Union的校验行为就和AnyOf完全一致，没有强制要求“只能匹配一个模型”的硬校验逻辑。
• 你在两个Pill模型中分别定义的kind: str = Literal['red']/Literal['blue']字段，会直接触发Pydantic的*可辨识联合（Discriminated Union）*机制：校验时会优先根据传入对象的kind字段值，直接定位需要匹配的模型，不会出现当传入对象同时满足两个模型字段要求时的错配问题，校验效率也比无标识的裸Union高很多。
• 这套代码运行后，FastAPI自动生成的OpenAPI接口文档里，pills字段的数组项Schema会自动标注为AnyOf结构，前端开发可以直接根据文档的字段要求构造请求，不需要额外做自定义Schema调整。

多类型对象混合数组的定义优化 #

要让这个混合类型的数组完全可靠运行，有几个容易踩的细节需要调整：

• 不要直接给数组设置可变默认值：你当前写的pills: List[Union[RedPill, BluePill]] = []是Pydantic里的典型反模式，因为列表是可变对象，多请求场景下可能出现默认值被意外修改的问题，正确写法是用Field(default_factory=list)初始化空数组：

  from pydantic import Field
  
  class Matrix(BaseModel):
      year: int
      pills: List[Union[RedPill, BluePill]] = Field(default_factory=list)
  

• 如果使用Pydantic v2版本，可以直接用内置的AnyOf类型替代Union，语义上更直观：

  from pydantic import AnyOf
  
  pills: List[AnyOf[RedPill, BluePill]] = Field(default_factory=list)
  

  这种写法会自动识别两个模型里的kind字面值字段作为鉴别器，和之前的Union写法校验逻辑完全一致。
• 如果是使用Pydantic v1版本，需要手动为联合类型指定鉴别器参数，否则不会自动触发可辨识联合的校验逻辑，写法为：

  from typing import Union
  from pydantic import Field
  
  pills: List[Union[RedPill, BluePill]] = Field(default_factory=list, discriminator="kind")
  

校验效果验证 #

按照调整后的写法，传入的合法pills数组可以正常通过校验，比如：

{
  "year": 1999,
  "pills": [
    {"kind": "red", "name": "Neo", "size": 12},
    {"kind": "blue", "serialnumber": "CP-002"}
  ]
}

如果传入的对象缺少kind字段、kind值不匹配固定字面值、或者对应模型要求的必填字段缺失，FastAPI会自动返回符合预期的422校验错误，不会出现静默校验通过的问题。

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