Pydantic模型序列化中子类字段丢失问题解析

问题背景

在使用Pydantic V2进行模型序列化时，开发者可能会遇到一个典型问题：当父类模型定义了自定义序列化器，而子类模型作为嵌套字段使用时，子类特有的字段在序列化过程中会被意外丢弃。

问题复现

让我们通过一个具体示例来说明这个问题：

from pydantic import BaseModel, model_serializer

class Base(BaseModel):
    name: str

    @model_serializer(mode="wrap")
    def custom_serializer(self, base_serializer, info):
        return {"__class__": self.__class__.__name__} | base_serializer(self, info)

class Inheriting(Base):
    custom: str

class Other(BaseModel):
    nested: Base | None

当创建实例并序列化时：

o = Other(nested=Inheriting(name="test", custom="custom"))
print(o.model_dump_json(indent=2))

输出结果中会丢失子类的custom字段：

{
  "nested": {
    "__class__": "Inheriting",
    "name": "test"
  }
}

问题原因

这个问题的根本原因在于Pydantic的序列化机制是基于类型提示工作的。当字段类型被声明为父类（如Base）时，Pydantic会使用父类的序列化逻辑，即使实际传入的是子类实例。

具体来说：

1. Pydantic在序列化时会检查字段的类型注解
2. 对于nested: Base | None字段，Pydantic会使用Base模型的序列化器
3. 虽然运行时传入的是Inheriting实例，但序列化过程仍遵循Base的定义
4. 导致子类特有的custom字段被忽略

解决方案

方法一：使用类型验证器

可以通过自定义验证器确保字段类型检查，同时保留完整的序列化能力：

from typing import Annotated, Any
from pydantic import AfterValidator

def check_is_base(val):
    if val is None:
        return None
    if not isinstance(val, Base):
        raise ValueError(f"Expected {val} to be an instance of Base")
    return val

Nested = Annotated[Any, AfterValidator(check_is_base)]

class Other(BaseModel):
    nested: Nested

这种方法：

1. 使用Annotated和AfterValidator进行运行时类型检查
2. 将字段类型设为Any避免Pydantic的类型约束
3. 保留完整的序列化能力

方法二：使用联合类型

更简洁的方式是直接使用子类的联合类型：

class Other(BaseModel):
    nested: Base | Inheriting | None

这种方法明确告诉Pydantic可能接收的类型，使其能够正确选择序列化器。

最佳实践建议

1. 在设计模型继承体系时，明确考虑序列化场景
2. 对于可能被子类替代的字段，使用更宽泛的类型提示
3. 考虑使用@model_serializer的mode="plain"替代"wrap"，除非确实需要包装逻辑
4. 在复杂场景下，可以自定义json_encoders来处理特定类型的序列化

总结

Pydantic的序列化行为严格遵循类型系统设计，理解这一原理对于处理继承模型的序列化问题至关重要。通过合理使用类型提示和验证器，开发者可以灵活控制序列化过程，确保数据完整性和类型安全。