Pydantic项目中自定义类型序列化与JSON Schema生成的深度解析

在Python生态中，Pydantic作为数据验证和设置管理的核心工具，其V2版本带来了更强大的类型系统支持。本文将深入探讨一个典型场景：当处理不可修改的外部类时，如何实现类型适配器与JSON Schema的完美配合。

问题现象

开发者在使用Pydantic V2时遇到一个特定现象：为外部电压类Voltage实现自定义序列化后，虽然运行时数据转换正常，但JSON Schema生成时出现警告提示默认值不可序列化。核心矛盾在于：

1. 通过Annotated组合了类型转换器（BeforeValidator）和序列化器（PlainSerializer）
2. 模型类设置了Voltage(17)作为字段默认值
3. Schema生成时无法自动应用序列化逻辑处理默认值

技术原理

Pydantic的JSON Schema生成机制存在两种模式：

1. 验证模式（validation）：关注输入数据的校验规则
2. 序列化模式（serialization）：描述输出数据的形态

在V2.10版本中，Schema生成器对Annotated内元数据的处理存在顺序敏感性。关键在于：

• 序列化器必须位于注解的最外层
• 验证器需要明确指定json_schema_input_type参数

解决方案

临时方案（V2.10）

调整注解顺序，将PlainSerializer置于最外层：

PydanticVoltage = Annotated[
    Voltage,
    pydantic.WithJsonSchema({"type": "number"}),
    pydantic.BeforeValidator(lambda v: Voltage(v)),
    pydantic.PlainSerializer(lambda v: v.get())
]

永久方案（V2.12+）

新版本将改进处理逻辑，同时建议开发者：

1. 显式指定schema生成模式

model_json_schema(mode='serialization')

2. 为验证器补充类型提示

pydantic.BeforeValidator(
    lambda v: Voltage(v),
    json_schema_input_type=float
)

最佳实践

1. 复杂类型适配建议采用__get_pydantic_core_schema__方案
2. 始终测试验证和序列化两种模式下的Schema生成
3. 为自定义类型同时实现__str__和__repr__方法
4. 考虑使用@property替代getter方法以保持Pythonic风格

架构思考

这个案例揭示了数据转换管道的三个关键阶段：

1. 输入验证（将原始数据转为领域对象）
2. 业务处理（保持对象形态的内部流转）
3. 输出序列化（将对象转为传输格式）

Pydantic的强大之处在于通过统一的类型系统将这三个阶段有机整合，开发者需要明确每个注解作用的阶段范围，才能构建出健壮的数据处理管道。