FastAPI中Union多模型校验返回冗余422错误的问题问询

问题原因 #

这不是Union的使用错误，而是FastAPI默认的多模型校验逻辑导致的：当你用Union[Foo, Bar, Xyz]作为请求体类型时，FastAPI会尝试匹配所有Union中的模型，只要某一个模型校验失败，就会把所有模型的校验错误信息汇总返回。

比如你的请求结构接近Foo，但缺少Foo的foo3字段，此时Foo校验失败；同时Bar和Xyz因为请求体里没有它们的专属字段，也会校验失败。最终422错误就会包含三个模型的缺失字段信息。

解决方法 #

核心思路是让FastAPI只校验匹配的单个模型，以下是几种可行方案：

1. 使用鉴别器（最推荐） #

给每个模型添加一个专属的标识字段，FastAPI会根据这个字段直接匹配对应模型，仅校验该模型的字段。

示例代码：

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

app = FastAPI()

class Foo(BaseModel):
    type: Literal["foo"]  # 专属标识字段
    temp: int
    foo3: str

class Bar(BaseModel):
    type: Literal["bar"]
    temp: int
    bar_field: bool

class Xyz(BaseModel):
    type: Literal["xyz"]
    temp: int
    xyz_value: float

@app.post("/test")
async def test(body: Union[Foo, Bar, Xyz]):
    return body

请求时携带"type": "foo"，FastAPI只会校验Foo的字段，缺失foo3时只会返回Foo的错误信息。

2. 自定义请求体依赖 #

如果不想添加标识字段，可以手动判断请求体结构，选择对应模型校验，仅返回该模型的错误。

示例代码：

from fastapi import FastAPI, Depends, HTTPException
from pydantic import BaseModel, ValidationError
from typing import Dict, Any

app = FastAPI()

class Foo(BaseModel):
    temp: int
    foo3: str

class Bar(BaseModel):
    temp: int
    bar_field: bool

class Xyz(BaseModel):
    temp: int
    xyz_value: float

async def parse_body(raw_body: Dict[str, Any]):
    # 根据专属字段判断匹配的模型
    if "foo3" in raw_body:
        try:
            return Foo(**raw_body)
        except ValidationError as e:
            raise HTTPException(status_code=422, detail=e.errors())
    elif "bar_field" in raw_body:
        try:
            return Bar(**raw_body)
        except ValidationError as e:
            raise HTTPException(status_code=422, detail=e.errors())
    elif "xyz_value" in raw_body:
        try:
            return Xyz(**raw_body)
        except ValidationError as e:
            raise HTTPException(status_code=422, detail=e.errors())
    else:
        raise HTTPException(status_code=422, detail="请求体不符合任何模型结构")

@app.post("/test")
async def test(body: Foo | Bar | Xyz = Depends(parse_body)):
    return body

3. 使用Pydantic v2的OneOf类型 #

Pydantic v2及以上版本支持OneOf类型，它会按顺序尝试匹配模型，找到第一个结构接近的模型后，仅校验该模型的字段，停止后续模型的校验。

示例代码：

from fastapi import FastAPI
from pydantic import BaseModel, OneOf

app = FastAPI()

class Foo(BaseModel):
    temp: int
    foo3: str

class Bar(BaseModel):
    temp: int
    bar_field: bool

class Xyz(BaseModel):
    temp: int
    xyz_value: float

@app.post("/test")
async def test(body: OneOf[Foo, Bar, Xyz]):
    return body

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