本文详解如何让 Pydantic 在泛型约束下支持任意 Action 子类作为嵌套字段，并完整保留子类字段进行序列化（如 model_dump()），避免仅导出基类字段的常见陷阱。
本文详解如何让 pydantic 在泛型约束下支持任意 `action` 子类作为嵌套字段，并完整保留子类字段进行序列化（如 `model_dump()`），避免仅导出基类字段的常见陷阱。
在 Pydantic 中，若将嵌套字段声明为基类类型（如 action: Action），即使传入子类实例（如 LogAction），默认序列化行为（model_dump() / model_json()）也只会输出基类定义的字段——子类特有属性（如 log_level、timestamp）会被静默忽略。这是因为 Pydantic 的类型注解在运行时未携带具体子类信息，模型校验与序列化均按声明类型（Action）执行。
解决该问题的核心思路是：利用 Python 泛型 + TypeVar 限定类型边界（bound），使字段类型动态适配实际传入的子类，而非固定为基类。这样既保持类型安全，又确保序列化时完整保留子类字段。
✅ 正确实现方式：泛型模型 + 类型变量约束
from typing import Generic, TypeVar
from pydantic import BaseModel
class Action(BaseModel):
name: str
class LogAction(Action):
log_level: str
timestamp: str
class AnotherAction(Action):
something: str
# 定义可接受任意 Action 子类的类型变量
T = TypeVar("T", bound=Action)
class Alert(BaseModel, Generic[T]):
id: int
message: str
action: T # 类型随实例化时传入的具体子类动态确定
✅ 实例化与序列化效果验证
# 使用 LogAction 实例 → action 字段完整包含 name, log_level, timestamp
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'}}
# 使用 AnotherAction 实例 → 自动包含其特有字段 `something`
alert2 = Alert(
id=2,
message="Another Alert",
action=AnotherAction(name="Custom Action", something="123")
)
print(alert2.model_dump())
# 输出：{'id': 2, 'message': 'Another Alert', 'action': {'name': 'Custom Action', 'something': '123'}}
⚠️ 注意事项与限制
- JSON Schema 兼容性：泛型模型生成的 OpenAPI Schema 中，action 字段仍显示为 Action（因 Schema 不支持运行时泛型推导），但运行时序列化完全正确。若需精确 Schema，需配合 Field(..., discriminator='type') + Union（Pydantic v2.4+ 支持 TaggedUnion），但会牺牲“任意子类”的灵活性。
- 类型检查友好：IDE 和 mypy 能正确识别 alert1.action.log_level 等子类属性，提供完整补全与静态检查。
- 校验安全性：传入非 Action 子类的实例（如独立定义的 AnotherAction2）会在初始化时触发 ValidationError，保障类型安全。
✅ 总结
通过 Generic[T] 与 TypeVar(bound=BaseModel) 组合，Pydantic 可实现“基类声明、子类实例化、全字段序列化”的优雅解法。该方案无需硬编码 Union[Action, LogAction, ...]，具备良好的扩展性与类型严谨性，是处理多态嵌套模型的推荐实践。
