本文介绍如何通过泛型（Generic）与类型变量（TypeVar）约束，使 Pydantic 模型能正确接收并完整序列化 BaseModel 子类实例（如 LogAction），突破 Union 手动枚举的局限，实现灵活、类型安全的继承式嵌套建模。
本文介绍如何通过泛型（generic）与类型变量（typevar）约束，使 pydantic 模型能正确接收并完整序列化 `basemodel` 子类实例（如 `logaction`），突破 `union` 手动枚举的局限，实现灵活、类型安全的继承式嵌套建模。
在 Pydantic 中，若希望父类字段（如 action: Action）能接受任意继承自 Action 的子类（如 LogAction、AlertAction 等），并在 .model_dump() 或 JSON 序列化时保留子类全部字段，直接使用基类注解（action: Action）会导致子类特有字段被忽略——这是因 Pydantic 默认按声明类型（即 Action）进行序列化，仅导出基类定义的字段。
解决方案是引入 泛型 + 有界类型变量（TypeVar with bound=Action），将嵌套字段声明为类型参数 T，从而让模型在实例化时“记住”实际传入的子类类型，并据此执行完整序列化。
✅ 正确实现方式（Pydantic v2+）
from typing import Generic, TypeVar
from pydantic import BaseModel
class Action(BaseModel):
name: str
class LogAction(Action):
log_level: str
timestamp: str
class Alert(BaseModel, Generic[T]):
id: int
message: str
action: T
# 使用时指定具体子类类型（类型推断自动生效）
alert1 = Alert(
id=1,
message="Alert Message",
action=LogAction(name="Error Log", log_level="ERROR", timestamp="2024-04-20T10:45:00"),
)
print(alert1)
# Alert[id=1, message='Alert Message', action=LogAction(name='Error Log', log_level='ERROR', timestamp='2024-04-20T10:45:00')]
print(alert1.model_dump())
# {'id': 1, 'message': 'Alert Message', 'action': {'name': 'Error Log', 'log_level': 'ERROR', 'timestamp': '2024-04-20T10:45:00'}}
✅ 优势：
- 类型安全：T = TypeVar("T", bound=Action) 确保 action 只能是 Action 或其子类；传入非继承类（如独立 BaseModel）会触发 ValidationError；
- 完整序列化：.model_dump() 自动包含子类所有字段（log_level, timestamp），无需手动 Union 枚举；
- 多态友好：同一 Alert 模型可复用于不同子类实例（LogAction、AnotherAction 等）。
⚠️ 注意事项：
- JSON Schema 局限性：生成的 OpenAPI schema 中，action 字段仍显示为 Action（而非具体子类），因 schema 是静态结构，无法反映运行时泛型实参。若需精确 schema，需配合 Field(..., discriminator='type') 实现联合类型（discriminator-based union），但会牺牲泛型的简洁性；
- 必须显式继承 BaseModel：子类（如 LogAction）须直接或间接继承 Action（即 BaseModel），否则类型检查失败；
- 避免裸 BaseModel 子类：AnotherAction2 若未继承 Action，实例化 Alert[AnotherAction2] 会因类型约束失败，在开发阶段即可捕获错误。
总结
泛型方案是 Pydantic 中处理“基类字段需接纳任意子类并完整序列化”的推荐实践。它兼顾类型安全性、序列化完整性与代码可维护性，尤其适用于插件化、策略模式或事件驱动架构中需要扩展动作类型（Action）的场景。对于强 schema 需求，可结合 Union + discriminator 作为补充方案，但日常开发中，泛型已足够优雅高效。
