Pydantic中的联合类型(Union)验证机制详解-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00596/article/details/148361617

Pydantic中的联合类型(Union)验证机制详解

pydantic Data validation using Python type hints 项目地址: https://gitcode.com/gh_mirrors/py/pydantic

联合类型验证的基本概念

在Pydantic中，联合类型(Union)的验证与其他类型有着本质区别。对于普通类型，验证要求所有字段/项/值都必须有效；而对于联合类型，只需要其中一个成员验证通过即可。

这种特性带来了两个核心问题：

应该按什么顺序验证联合类型的各个成员？
验证失败时应返回哪些错误信息？

Pydantic的三种联合类型验证模式

Pydantic提供了三种主要的联合类型验证策略：

1. 从左到右模式(left_to_right)

这是最简单的验证方式，按定义顺序依次尝试每个成员，返回第一个验证成功的成员。

from typing import Union
from pydantic import BaseModel, Field

class User(BaseModel):
    id: Union[str, int] = Field(union_mode='left_to_right')

特点：

验证顺序至关重要
可能导致意外结果（如数字字符串被解析为整数）
Pydantic 2.x版本后不再是默认模式

2. 智能模式(smart)

这是Pydantic 2.x的默认验证模式，它会尝试为输入选择最匹配的联合成员。

from typing import Union
from uuid import UUID
from pydantic import BaseModel

class User(BaseModel):
    id: Union[int, str, UUID]
    name: str

智能匹配算法：

对于模型、数据类和类型字典：
- 计算有效字段数量
- 评估匹配精确度
- 优先选择有效字段多的成员
- 数量相同时选择匹配更精确的成员
对于其他数据类型：
- 评估匹配精确度（精确匹配 > 严格模式匹配 > 宽松模式匹配）
- 遇到精确匹配立即返回
- 否则返回最左侧的严格或宽松匹配

3. 鉴别联合(discriminated unions)

这是最高效的验证方式，通过鉴别器字段明确指定要验证的成员。

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

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

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

class Model(BaseModel):
    pet: Union[Cat, Dog] = Field(discriminator='pet_type')

优势：

验证性能最佳
错误信息最清晰
生成的JSON模式符合OpenAPI规范

高级鉴别联合用法

使用可调用鉴别器

当联合成员没有统一的鉴别字段时，可以使用可调用函数作为鉴别器。

from typing import Annotated, Any, Literal
from pydantic import BaseModel, Discriminator, Tag

def get_discriminator_value(v: Any) -> str:
    if isinstance(v, dict):
        return v.get('fruit', v.get('filling'))
    return getattr(v, 'fruit', getattr(v, 'filling', None))

class ThanksgivingDinner(BaseModel):
    dessert: Annotated[
        Union[
            Annotated[ApplePie, Tag('apple')],
            Annotated[PumpkinPie, Tag('pumpkin')],
        ],
        Discriminator(get_discriminator_value),
    ]

嵌套鉴别联合

通过嵌套Annotated类型可以实现多级鉴别：

from typing import Annotated, Literal
from pydantic import BaseModel, Field

class BlackCat(BaseModel):
    pet_type: Literal['cat']
    color: Literal['black']
    black_name: str

Cat = Annotated[Union[BlackCat, WhiteCat], Field(discriminator='color')]
Pet = Annotated[Union[Cat, Dog], Field(discriminator='pet_type')]