Pydantic 嵌套模型自定义序列化器与字段排除问题解析

概述

在使用 Pydantic V2 进行数据模型序列化时，开发者可能会遇到嵌套模型中自定义序列化器与字段排除/包含功能配合使用的问题。本文将深入分析这一问题的成因，并提供正确的解决方案。

问题现象

当开发者尝试在 Pydantic 模型中使用 field_serializer 装饰器以 wrap 模式自定义字段序列化逻辑时，可能会发现嵌套模型中的字段排除(exclude)和包含(include)功能失效。具体表现为：

1. 排除规则不生效，预期应该被排除的字段仍然出现在输出中
2. 使用包含规则时抛出 PydanticSerializationError 异常

问题根源

问题的核心在于 wrap 模式序列化器的参数传递方式。在 wrap 模式中，序列化处理器(handler)的正确调用方式应该是直接传递值，而不应该包含额外的 info 参数。

错误示例中的调用方式：

@field_serializer('a', mode='wrap')
def _serialize_a(self, value, handler, info):
    return handler(value, info)  # 错误地传递了 info 参数

正确解决方案

正确的 wrap 模式序列化器实现应该如下：

@field_serializer('a', mode='wrap')
def _serialize_a(self, value, handler):
    return handler(value)  # 仅传递值本身

技术原理

Pydantic 的 wrap 模式序列化器设计用于在现有序列化逻辑前后添加自定义处理。其工作原理是：

1. 开发者定义 wrap 序列化器，接收值和 handler 两个参数
2. handler 参数是一个可调用对象，负责执行默认的序列化逻辑
3. 开发者可以在调用 handler 前后添加自定义逻辑
4. 对于列表类型的字段，handler 会自动处理每个元素的序列化

最佳实践

1. 对于简单的字段排除/包含需求，优先考虑使用 Pydantic 内置的 exclude/include 参数
2. 当需要自定义序列化逻辑时，确保 wrap 模式序列化器正确实现：
   • 只接收 value 和 handler 两个参数
   • 直接调用 handler(value) 而不传递额外参数
3. 使用类型注解可以帮助静态类型检查器发现潜在问题

总结

Pydantic 提供了强大的序列化控制能力，但需要正确理解各种序列化模式的使用方法。wrap 模式序列化器特别适合在保持默认序列化行为的同时添加额外处理逻辑的场景。通过遵循正确的参数传递约定，可以确保嵌套模型中的字段排除/包含功能正常工作。