PydanticV2：多态模型新处理方式

本文深入解析了Pydantic V2中处理多态数据模型的全新方式——判别式联合（Discriminated Unions）。针对多个模型共享相同字段名导致解析歧义的问题，详细介绍了如何通过指定“判别器”字段，利用`typing.Annotated`和`pydantic.Field`，确保Pydantic能够准确地将数据验证并解析到预期的模型类型。文章通过`MealsService`和`CanapesService`的实例，展示了如何使用`Literal`类型明确判别器字段的值，并结合完整代码示例，演示了判别式联合在实际应用中的强大功能。掌握Pydantic V2的判别式联合，能够有效提升数据模型的准确性和健壮性，构建更可靠的应用程序。

理解问题：多态数据模型的解析歧义

在构建复杂的应用程序时，我们经常会遇到需要处理多态数据结构的情况，即一个列表或字段可能包含多种不同但相关的对象类型。Pydantic通过联合类型（Union）支持这种多态性。然而，当这些不同的模型在结构上存在重叠，特别是当它们都包含一个同名的字段，并且这个字段的值在特定情况下（如空列表或可选字段为None）不足以区分模型时，P识会出现解析歧义。

考虑以下Pydantic模型定义：

import datetime
from typing import List, Union, Annotated, Literal
import pydantic
from pydantic import Field

class MealsService(pydantic.BaseModel):
    class MealItem(pydantic.BaseModel):
        course: str
        name: str
        quantity: int
        unitPrice: float | None

    type: str = "meals"  # 默认值为 "meals"
    items: list[MealItem]
    time: datetime.time | None


class CanapesService(pydantic.BaseModel):
    class CanapeItem(pydantic.BaseModel):
        name: str
        quantity: int
        unitPrice: float | None

    type: str = "canapes" # 默认值为 "canapes"
    items: list[CanapeItem]
    time: datetime.time | None


class Event(pydantic.BaseModel):
    services: list[MealsService | CanapesService]

当我们尝试解析一个JSON负载，例如：

{
    "services": [
        {
            "type": "canapes",
            "items": [],
            "time": null
        }
    ]
}

尽管 type 字段明确指定为 "canapes"，但由于 MealsService 和 CanapesService 都包含 type、items 和 time 字段，且 items 字段为空列表，time 字段为 null，Pydantic在没有额外指导的情况下，可能会错误地将此负载解析为 MealsService 的实例，而非 CanapesService。这是因为Pydantic在默认情况下，会尝试按顺序匹配联合类型中的模型，并选择第一个成功验证的模型。

解决方案：Pydantic V2 的判别式联合（Discriminated Unions）

为了解决这种歧义，Pydantic V2引入了判别式联合的概念。判别式联合允许我们指定一个特定的字段（称为“判别器”或“discriminator”）来帮助Pydantic在联合类型中准确地选择正确的模型。当解析数据时，Pydantic会检查这个判别器字段的值，并根据其值来确定应使用联合中的哪个具体模型进行验证。

要实现判别式联合，我们需要使用 typing.Annotated 和 pydantic.Field，并指定 discriminator 参数。

步骤一：标记判别器字段

首先，为了让判别式联合正确工作，每个作为联合成员的模型必须在判别器字段上使用 Literal 类型来明确其具体的值。这告诉Pydantic，这个字段的值是固定的，并且可以作为区分不同模型的依据。

修改 MealsService 和 CanapesService 模型如下：

import datetime
from typing import List, Union, Annotated, Literal
import pydantic
from pydantic import Field

class MealsService(pydantic.BaseModel):
    class MealItem(pydantic.BaseModel):
        course: str
        name: str
        quantity: int
        unitPrice: float | None

    # 使用 Literal 明确 'type' 字段的值
    type: Literal["meals"] = "meals"
    items: list[MealItem]
    time: datetime.time | None


class CanapesService(pydantic.BaseModel):
    class CanapeItem(pydantic.BaseModel):
        name: str
        quantity: int
        unitPrice: float | None

    # 使用 Literal 明确 'type' 字段的值
    type: Literal["canapes"] = "canapes"
    items: list[CanapeItem]
    time: datetime.time | None

步骤二：定义判别式联合

接下来，在包含联合类型的字段上，使用 Annotated 和 Field(discriminator='your_field_name') 来定义判别式联合。

# 定义判别式联合
Services = Annotated[Union[MealsService, CanapesService], Field(discriminator='type')]

class Event(pydantic.BaseModel):
    services: List[Services] # 使用定义好的判别式联合

通过 Field(discriminator='type')，我们明确告诉Pydantic，在解析 services 列表中的每个元素时，应该检查其内部的 type 字段的值。如果 type 的值为 "meals"，则解析为 MealsService；如果值为 "canapes"，则解析为 CanapesService。

完整示例代码

结合上述修改，完整的代码如下：

import datetime
from typing import List, Union, Annotated, Literal
import pydantic
from pydantic import Field

class MealsService(pydantic.BaseModel):
    class MealItem(pydantic.BaseModel):
        course: str
        name: str
        quantity: int
        unitPrice: float | None

    type: Literal["meals"] = "meals" # 明确指定 'type' 的字面值
    items: list[MealItem]
    time: datetime.time | None


class CanapesService(pydantic.BaseModel):
    class CanapeItem(pydantic.BaseModel):
        name: str
        quantity: int
        unitPrice: float | None

    type: Literal["canapes"] = "canapes" # 明确指定 'type' 的字面值
    items: list[CanapeItem]
    time: datetime.time | None


# 定义判别式联合，指定 'type' 字段作为判别器
Services = Annotated[Union[MealsService, CanapesService], Field(discriminator='type')]


class Event(pydantic.BaseModel):
    services: List[Services] # 使用判别式联合


# 测试解析
payload = {
    "services": [
        {
            "type": "canapes",
            "items": [],
            "time": None
        },
        {
            "type": "meals",
            "items": [
                {"course": "main", "name": "Steak", "quantity": 1, "unitPrice": 25.0}
            ],
            "time": "19:00:00"
        }
    ]
}

try:
    event_instance = Event.model_validate(payload)
    print("成功解析 Event 实例:")
    for service in event_instance.services:
        print(f"  服务类型: {type(service).__name__}, Type字段: {service.type}")
        if isinstance(service, MealsService):
            print(f"    餐点数量: {len(service.items)}")
        elif isinstance(service, CanapesService):
            print(f"    小吃数量: {len(service.items)}")

    # 验证第一个服务是否为 CanapesService
    assert isinstance(event_instance.services[0], CanapesService)
    assert event_instance.services[0].type == "canapes"
    # 验证第二个服务是否为 MealsService
    assert isinstance(event_instance.services[1], MealsService)
    assert event_instance.services[1].type == "meals"

except pydantic.ValidationError as e:
    print(f"解析失败: {e}")

运行上述代码，你会看到 Pydantic 能够正确地将第一个服务解析为 CanapesService，将第二个服务解析为 MealsService，即使它们在某些字段上结构相似。

注意事项与总结

1. Pydantic V2 专属特性：判别式联合是 Pydantic V2 引入的特性。如果你还在使用 Pydantic V1，需要考虑升级或寻找其他兼容 V1 的解决方案（例如，使用 parse_obj_as 结合自定义逻辑）。
2. Literal 类型的重要性：确保判别器字段在每个模型中都使用了 Literal 类型来明确其固定的值。这是 Pydantic 识别和区分不同模型的基础。
3. 判别器字段存在性：作为判别器的字段必须存在于联合中的每个模型中，并且其值能够唯一地标识该模型。
4. 清晰的类型提示：使用 Annotated 和 Union 结合 Field(discriminator=...) 能够提供清晰的类型提示，使得代码更易于理解和维护。

通过利用 Pydantic V2 的判别式联合功能，开发者可以优雅而健壮地处理复杂的、多态的数据结构，避免解析歧义，确保数据验证的准确性，从而构建更可靠的应用程序。

今天关于《PydanticV2：多态模型新处理方式》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！