本教程详细介绍了在Pydantic V2中如何使用判别式联合（Discriminated unions）来解决多态数据模型解析时的歧义问题。当多个模型共享相同的字段名，导致Pydantic难以区分实际类型时，判别式联合通过指定一个“判别器”字段，确保数据能够被正确地验证和解析到预期的模型类型，从而提升数据模型的准确性和健壮性。
理解问题：多态数据模型的解析歧义
在构建复杂的应用程序时，我们经常会遇到需要处理多态数据结构的情况，即一个列表或字段可能包含多种不同但相关的对象类型。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，即使它们在某些字段上结构相似。
注意事项与总结
- Pydantic V2 专属特性：判别式联合是 Pydantic V2 引入的特性。如果你还在使用 Pydantic V1，需要考虑升级或寻找其他兼容 V1 的解决方案（例如，使用 parse_obj_as 结合自定义逻辑）。
- Literal 类型的重要性：确保判别器字段在每个模型中都使用了 Literal 类型来明确其固定的值。这是 Pydantic 识别和区分不同模型的基础。
- 判别器字段存在性：作为判别器的字段必须存在于联合中的每个模型中，并且其值能够唯一地标识该模型。
- 清晰的类型提示：使用 Annotated 和 Union 结合 Field(discriminator=…) 能够提供清晰的类型提示，使得代码更易于理解和维护。
通过利用 Pydantic V2 的判别式联合功能，开发者可以优雅而健壮地处理复杂的、多态的数据结构，避免解析歧义，确保数据验证的准确性，从而构建更可靠的应用程序。
