本文旨在解决 Pydantic 中 `ForwardRef` 无法延迟加载的问题，通过介绍 discriminated unions 的使用方法，并提供代码示例，帮助开发者在处理包含子类的对象模型时，避免繁琐的隐藏机制，实现更简洁、灵活的代码结构，特别是在模块化开发中跨模块引用时。
在使用 Pydantic 构建复杂的数据模型时，经常会遇到类之间相互引用的情况，特别是当涉及到继承关系时。ForwardRef 可以用于解决循环依赖的问题，但有时我们需要延迟 ForwardRef 的解析，例如，当子类定义在其他模块中，且加载顺序无法保证时。本文将介绍一种使用 discriminated unions 的方法，避免手动隐藏类型变量，实现更优雅的延迟加载。
使用 Discriminated Unions
Discriminated Unions 是一种 Pydantic 特性，它允许根据某个字段的值来区分联合类型中的不同子类型。这可以有效地解决需要在运行时才能确定具体类型的问题。
以下是一个使用 discriminated unions 的示例，该示例定义了 Pet 基类和 Dog、Cat 子类，并使用 AnyPet 类型来表示它们的联合类型：
from pydantic import BaseModel, Field
from typing import Literal, Annotated, Union
class Pet(BaseModel):
"""Animal class"""
name: str
age: int
class Dog(Pet):
"""Dog class"""
type: Literal["dog"] = "dog"
breed: str
class Cat(Pet):
"""Cat class"""
type: Literal["cat"] = "cat"
breed: str
AnyPet = Annotated[Union[Dog, Cat], Field(discriminator="type")]
class Home(BaseModel):
"""Home class"""
pet: AnyPet
data = {
"pet": {
"type": "dog",
"name": "Buddy",
"age": 4,
"breed": "Golden Retriever"
}
}
home = Home(**data)
print(home)在这个例子中，AnyPet 使用 Annotated 和 Union 定义，Field(discriminator="type") 指定了使用 type 字段来区分 Dog 和 Cat 类型。当 Pydantic 解析 Home 模型时，会根据 pet 字典中的 type 字段的值来确定具体的 Pet 子类型。
跨模块场景下的应用
如果你的模型分布在多个模块中，并且无法轻易地生成所有子类的列表，可以考虑以下几种方法：
-
集中管理子类定义： 尽量将所有相关的子类定义放在同一个模块或子模块中，并在 __init__.py 中定义 AnyPet 类型。这样可以确保所有子类在定义 AnyPet 之前都被加载。
pets/ ├── __init__.py # 定义 AnyPet ├── cats.py # 定义 Cat └── dogs.py # 定义 Dog
-
自动生成联合类型： 如果无法集中管理子类，可以编写代码自动检测基类的所有子类，并生成联合类型。
from pydantic import BaseModel from typing import Union, Annotated, Field class Pet(BaseModel): name: str age: int # 假设 Dog 和 Cat 在其他模块中定义并导入 from .dogs import Dog from .cats import Cat valid_sub_classes = [] for sub_class in Pet.__subclasses__(): field = sub_class.model_fields.get("type", None) if field is None: raise ValueError(f"{sub_class.__name__} is missing a 'type' field") valid_sub_classes.append(sub_class) AnyPet = Annotated[Union[tuple(valid_sub_classes)], Field(discriminator="type")] print(AnyPet)这种方法可以动态地发现所有子类，并将其合并到联合类型中。
-
延迟执行： 如果上述方法都不可行，可以定义一个函数来延迟执行生成联合类型的代码。
from pydantic import BaseModel from typing import Union, Annotated, Field def get_any_pet(): class Pet(BaseModel): name: str age: int # 假设 Dog 和 Cat 在其他模块中定义并导入 from .dogs import Dog from .cats import Cat valid_sub_classes = [] for sub_class in Pet.__subclasses__(): field = sub_class.model_fields.get("type", None) if field is None: raise ValueError(f"{sub_class.__name__} is missing a 'type' field") valid_sub_classes.append(sub_class) return Annotated[Union[tuple(valid_sub_classes)], Field(discriminator="type")] AnyPet = get_any_pet() class Home(BaseModel): pet: AnyPet这种方法可以将类型定义推迟到运行时，确保所有子类都已加载。
注意事项
- 确保所有子类都定义了一个用于区分类型的字段，并在 Field(discriminator="type") 中正确指定。
- 在跨模块场景下，仔细考虑模块的加载顺序，并选择合适的解决方案。
- 如果使用自动生成联合类型的方法，确保基类的所有子类都符合预期。
总结
通过使用 discriminated unions，可以有效地解决 Pydantic 中 ForwardRef 无法延迟加载的问题，并避免繁琐的隐藏机制。在跨模块场景下，可以结合集中管理子类定义、自动生成联合类型或延迟执行等方法，实现更灵活、可维护的代码结构。选择哪种方法取决于具体的项目结构和需求。
