Union模型与extra='forbid'的Pydantic验证异常问题

当你把RCSMessage定义为多个Pydantic模型的Union类型，且每个模型都设置了extra='forbid'，但传入所有模型都未定义的属性时没触发验证错误，核心原因是Pydantic的Union匹配逻辑是依次尝试每个模型，若没有明确的匹配规则，可能出现模糊匹配导致验证未严格执行。下面给出两种可靠的解决方式：

方案1：使用鉴别器（Discriminator）明确模型匹配逻辑 #

这是Pydantic官方推荐的处理Union类型的方式，通过一个固定字段区分不同模型，让Pydantic明确用哪个模型做验证，从而严格执行extra='forbid'规则。

代码示例 #

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

app = FastAPI()

# 定义各子模型，设置extra='forbid'并添加固定鉴别字段
class TextMessage(BaseModel):
    message_type: str = Field("text", const=True)
    content: str

    class Config:
        extra = "forbid"

class ImageMessage(BaseModel):
    message_type: str = Field("image", const=True)
    url: str

    class Config:
        extra = "forbid"

# 用__root__包裹Union，并指定鉴别字段
class RCSMessage(BaseModel):
    __root__: Union[TextMessage, ImageMessage] = Field(..., discriminator="message_type")

# 接口定义
@app.post("/send-rcs")
async def send_rcs(message: RCSMessage):
    return message.__root__

效果验证 #

发送包含未知字段的请求时：

{
    "message_type": "text",
    "content": "Hello World",
    "isTypingNoExiste": true
}

Pydantic会根据message_type明确使用TextMessage验证，触发extra='forbid'规则，抛出如下错误：

{
  "detail": [
    {
      "loc": ["__root__", "isTypingNoExiste"],
      "msg": "Extra inputs are not allowed",
      "type": "extra_forbidden"
    }
  ]
}

方案2：自定义验证器检查所有字段 #

如果不想用鉴别器，可以给RCSMessage添加自定义验证器，收集所有子模型的允许字段，检查输入是否有超出范围的字段。

代码示例 #

from fastapi import FastAPI
from pydantic import BaseModel, validator, ValidationError
from typing import Union

app = FastAPI()

class TextMessage(BaseModel):
    content: str
    class Config:
        extra = "forbid"

class ImageMessage(BaseModel):
    url: str
    class Config:
        extra = "forbid"

class RCSMessage(BaseModel):
    __root__: Union[TextMessage, ImageMessage]

    @validator("__root__")
    def reject_unknown_fields(cls, value):
        # 收集所有子模型的允许字段
        allowed_fields = set()
        for model in cls.__fields__["__root__"].type_.__args__:
            allowed_fields.update(model.__fields__.keys())
        
        # 获取输入的所有字段并检查
        input_fields = set(value.dict().keys())
        extra_fields = input_fields - allowed_fields
        
        if extra_fields:
            raise ValidationError(f"未知字段: {', '.join(extra_fields)}")
        return value

@app.post("/send-rcs")
async def send_rcs(message: RCSMessage):
    return message.__root__

注意事项 #

• 该方案适用于简单模型，若模型有嵌套字段或继承关系，需要递归收集所有允许字段。
• 性能略低于鉴别器方案，因为需要遍历所有子模型的字段。

原方案不生效的原因 #

原方案中，没有明确的匹配规则时，Pydantic会尝试用每个模型匹配输入：

1. 如果某个模型没有必填字段，输入仅包含未知字段时，Pydantic可能误判为匹配该模型，导致验证逻辑失效。
2. FastAPI的请求解析逻辑在Union模糊匹配时，可能未严格传递extra='forbid'的验证规则，而鉴别器能强制Pydantic使用指定模型做完整验证。

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