Pydantic V2 中自定义复杂类型序列化行为的变更与修复

在 Pydantic V2.10.0 版本中，开发者发现了一个关于自定义复杂类型序列化行为的变更，这导致了一些现有代码在升级后出现兼容性问题。本文将深入分析这个问题及其解决方案。

问题背景

Pydantic 是一个强大的 Python 数据验证和设置管理库，它允许开发者定义数据模型并自动处理数据验证和序列化。在 V2.10.0 版本中，当开发者尝试自定义复杂类型（如复数 complex）的序列化行为时，发现 dump_python 方法的输出从原来的复数对象变成了字符串表示形式。

技术细节

问题的核心在于 json_or_python_schema 的使用方式。开发者原本通过以下方式定义复数类型的序列化：

1. 使用 json_or_python_schema 来区分 JSON 和 Python 的序列化路径
2. 在 JSON 路径中，将复数转换为元组形式 (real, imag)
3. 在 Python 路径中，直接保留复数对象

在 V2.10.0 中，当使用 is_instance_schema 作为 Python 路径的验证器时，复数对象会被意外转换为字符串形式。这是由 pydantic-core 内部的一个 bug 修复引起的。

解决方案

Pydantic 团队在 V2.10.1 版本中修复了这个问题。修复的关键在于正确指定 Python 路径的 schema 类型。对于复数类型，应该使用 complex_schema() 而不是 is_instance_schema。

以下是修复后的正确用法示例：

from pydantic import TypeAdapter
from pydantic_core import SchemaSerializer, core_schema

schema = core_schema.json_or_python_schema(
    json_schema=core_schema.no_info_plain_validator_function(lambda v: complex(*v)),
    python_schema=core_schema.complex_schema(),
    serialization=core_schema.plain_serializer_function_ser_schema(
        lambda v: (v.real, v.imag),
        info_arg=False,
        return_schema=TypeAdapter(tuple[float, float]).core_schema,
        when_used="json",
    ),
)

最佳实践

对于自定义类型的序列化，建议开发者：

1. 明确区分 JSON 和 Python 的序列化路径
2. 对于内置类型，使用对应的 schema 函数（如 complex_schema 等）
3. 在升级 Pydantic 版本时，特别注意序列化行为的测试
4. 对于复杂场景，考虑编写专门的测试用例验证序列化行为

总结

Pydantic V2.10.1 修复了自定义复数类型序列化的问题，确保了向后兼容性。这个案例展示了类型系统在数据序列化中的重要性，也提醒开发者在自定义复杂类型行为时需要更加谨慎。理解 Pydantic 的 schema 系统对于构建健壮的数据处理逻辑至关重要。