本文介绍通过泛型（Generic）结合 TypeVar 约束实现 Pydantic 嵌套模型中子类完整序列化的方案，确保 model_dump() 保留子类特有字段，同时维持类型安全与运行时验证。
本文介绍通过泛型（generic）结合 typevar 约束实现 pydantic 嵌套模型中子类完整序列化的方案，确保 `model_dump()` 保留子类特有字段，同时维持类型安全与运行时验证。
在 Pydantic 中，若将字段声明为父类类型（如 action: Action），即使传入子类实例（如 LogAction），默认序列化行为（model_dump()）也仅输出父类定义的字段——这是由 Pydantic 的类型擦除机制和 JSON Schema 兼容性设计导致的。要真正支持「任意 Action 子类」并完整保留其字段，关键在于让模型感知具体子类类型，而非静态绑定到基类。
✅ 推荐方案：泛型 + TypeVar 约束
使用 typing.Generic 和 TypeVar(bound=BaseModel) 可为模型引入类型参数，使 Alert 成为一个可参数化的泛型模型。这样，action 字段的实际类型会在实例化时被精确推断，Pydantic 从而能正确校验并序列化所有子类字段。
from typing import Generic, TypeVar
from pydantic import BaseModel, ValidationError
class Action(BaseModel):
name: str
class LogAction(Action):
log_level: str
timestamp: str
class AnotherAction(Action):
something: str
# 定义受约束的类型变量
T = TypeVar("T", bound=Action)
class Alert(BaseModel, Generic[T]):
id: int
message: str
action: T # 类型 T 在实例化时确定，如 LogAction 或 AnotherAction
# ✅ 正确序列化子类全部字段
alert1 = Alert[LogAction](
id=1,
message="Alert Message",
action=LogAction(name="Error Log", log_level="ERROR", timestamp="2024-04-20T10:45:00"),
)
print(alert1.model_dump())
# 输出包含：'name', 'log_level', 'timestamp'
alert2 = Alert[AnotherAction](
id=2,
message="Another Alert",
action=AnotherAction(name="Custom", something="123"),
)
print(alert2.model_dump())
# 输出包含：'name', 'something'? 注意：Alert[LogAction] 是显式参数化写法（推荐），也可省略泛型参数直接实例化（Pydantic 会尝试从 action 值推断），但显式标注更清晰、IDE 支持更好。
⚠️ 注意事项与限制
- JSON Schema 局限性：泛型模型生成的 OpenAPI Schema 仍以 Action 为基准（因 Schema 需静态描述），无法自动展开所有可能子类。若需完整 Schema 支持，应考虑 Union 显式枚举或使用 Field(discriminator=...)（Pydantic v2.6+ 的 discriminator 支持多态）。
- 类型检查友好：配合 mypy 或 PyCharm，泛型能提供精准的属性补全与类型错误提示。
- 非继承类会被拒绝：传入未继承 Action 的模型（如 AnotherAction2）将在运行时触发 ValidationError，保障类型安全。
✅ 替代方案对比（不推荐）
- action: Action | LogAction | AnotherAction：需手动维护联合类型，扩展性差，且无法覆盖未来新增子类。
- action: Any：失去类型安全与校验能力。
- action: dict：放弃结构化验证与 IDE 支持。
综上，泛型 + TypeVar 是兼顾类型安全、序列化完整性与可扩展性的最佳实践，适用于需要灵活支持继承体系的领域建模场景。
