如何引导FastAPI从Union类型中基于tag匹配正确的Pydantic模型

解决方案 #

你可以直接使用Pydantic原生支持的**鉴别联合（Discriminated Union）**特性实现基于tag字段的自动模型匹配，不需要手动解析请求体，完全保留类型标注能力。

具体实现步骤

1. 给每个模型的tag字段定义固定字面量类型，明确每个模型对应的tag固定值
2. 在路由的请求类型标注中，指定tag为联合类型的鉴别字段

完整代码示例

from typing import Union, Literal, Annotated
from fastapi import FastAPI, Body
from pydantic import BaseModel

# 定义模型，tag固定为对应字面量
class A(BaseModel):
    tag: Literal['A'] = 'A'
    field1: str

class B(BaseModel):
    tag: Literal['B'] = 'B'
    field1: str
    field2: str

app = FastAPI()

# 路由中指定discriminator为tag字段
@app.post('/route')
def handle(request: Annotated[Union[A, B], Body(discriminator='tag')]):
    if request.tag == 'A':
        # 此处request会自动被推导为A类型，可直接访问A的字段
        return {"model": "A", "field1": request.field1}
    elif request.tag == 'B':
        # 此处request会自动被推导为B类型，可直接访问B的特有字段field2
        return {"model": "B", "field2": request.field2}

特性说明

• 该方案会严格按照tag字段的值匹配对应模型，不需要调整Union中模型的排序，不会出现高匹配度模型被误判的问题
• 如果请求传入的tag值不在预设的范围内，FastAPI会自动返回422参数校验错误，无需额外手动处理
• 编辑器和类型检查工具可以正常推导不同分支下的模型类型，不会出现类型报错

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