Pydantic 自动排除额外字段技巧

本教程演示如何在 Pydantic 模型序列化时自动排除未声明的“额外”字段。针对 model_dump 缺乏直接 exclude_extras 选项的问题，我们提出一种通用解决方案：通过创建一个自定义 MyBaseModel 类，并利用 model_serializer（mode="wrap"）在序列化过程中过滤掉不在 self.model_fields 中的键，从而确保生成的字典只包含模型中明确定义的字段，尤其适用于处理嵌套模型。

Pydantic model_dump 的“额外”字段处理挑战

在使用 Pydantic 进行数据验证和序列化时，我们经常需要将模型实例转换为 Python 字典 (dict) 格式。Pydantic 提供了强大的 model_dump 方法来实现这一功能，并附带了多种 exclude 选项，例如 exclude_none、exclude_unset 等，用于控制输出字典中包含哪些字段。然而，对于模型中通过 ConfigDict(extra="allow") 允许的“额外”（extra）字段，model_dump 并没有提供一个直接的 exclude_extras 选项来方便地将其排除。

当模型定义允许额外字段时，这些未在模型中明确声明的字段在序列化后，会原封不动地保留在生成的字典中。这在某些场景下可能不是我们期望的行为，特别是当我们需要将模型数据传递给严格要求字段结构的 API 或系统时。手动遍历并清除这些额外字段，尤其是在涉及多层嵌套的复杂模型时，会变得非常繁琐且容易出错。

考虑以下 Pydantic 模型示例，其中 Nested 模型允许额外字段：

from pydantic import BaseModel, ConfigDict

class Nested(BaseModel):
    model_config = ConfigDict(extra="allow")
    baz: str

class Root(BaseModel):
    foo: int = 10
    bar: int
    nested: Nested

if __name__ == "__main__":
    # 创建一个包含额外字段的模型实例
    model = Root(foo=10, bar=20, nested={"baz": "boing", "extra": "so special"})

    # 默认的 model_dump 会包含额外字段
    dumped_data = model.model_dump()

    print(f"默认 dump 结果: {dumped_data}")
    # 期望 "extra" 不在 dumped_data["nested"] 中，但实际会存在
    # assert "extra" not in dumped_data["nested"] # 此断言将失败

运行上述代码，你会发现 dumped_data["nested"] 中依然包含了 "extra": "so special" 这一额外字段，这不符合我们的预期。

解决方案：利用 model_serializer 自定义序列化行为

为了解决上述问题，我们可以通过创建一个自定义的基类 MyBaseModel，并利用 Pydantic V2 提供的 @model_serializer 装饰器，在模型序列化过程中对输出字典进行后处理。这种方法允许我们在默认序列化逻辑执行完毕后，对结果进行精细控制，从而实现自动排除额外字段。

核心思路是：

1. 定义一个继承自 BaseModel 的 MyBaseModel。
2. 在 MyBaseModel 中使用 @model_serializer(mode="wrap") 装饰器定义一个序列化方法。
3. 在这个序列化方法中，首先调用 handler(self) 获取 Pydantic 默认的序列化结果。
4. 然后，遍历这个结果字典，只保留那些键存在于 self.model_fields 中的字段。self.model_fields 存储了模型中所有明确声明的字段信息。

以下是实现这一解决方案的代码示例：

from typing import Any
from pydantic import BaseModel, ConfigDict, model_serializer, SerializerFunctionWrapHandler, FieldSerializationInfo


class MyBaseModel(BaseModel):
    """
    一个自定义的 Pydantic 基类，用于在序列化时自动排除额外字段。
    """
    @model_serializer(mode="wrap")
    def _serialize(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:
        """
        通过包装默认序列化器，过滤掉不在模型字段定义中的额外键。
        """
        # 调用 handler(self) 获取 Pydantic 默认的序列化结果
        default_dumped_data = handler(self)

        # 过滤字典，只保留在 self.model_fields 中声明的字段
        # self.model_fields 包含所有明确定义的字段名
        filtered_data = {
            k: v for k, v in default_dumped_data.items()
            if k in self.model_fields
        }
        return filtered_data


class Nested(MyBaseModel):
    model_config = ConfigDict(extra="allow") # 允许额外字段
    baz: str


class Root(MyBaseModel):
    foo: int = 10
    bar: int
    nested: Nested


if __name__ == "__main__":
    # 创建一个包含额外字段的模型实例
    model = Root(foo=10, bar=20, nested={"baz": "boing", "extra": "so special"})

    # 调用 model_dump，现在它会自动排除额外字段
    dumped_data = model.model_dump()

    print(f"过滤后 dump 结果: {dumped_data}")

    # 断言 "extra" 不在 dumped_data["nested"] 中
    assert "extra" not in dumped_data["nested"]
    print("断言成功：额外字段已成功排除。")

    # 进一步验证 Root 模型的额外字段（如果存在）也会被排除
    model_with_root_extra = Root(foo=10, bar=20, nested={"baz": "boing"}, root_extra_field="test")
    dumped_root_extra = model_with_root_extra.model_dump()
    print(f"Root 额外字段过滤结果: {dumped_root_extra}")
    assert "root_extra_field" not in dumped_root_extra
    print("断言成功：Root 模型的额外字段也已成功排除。")

核心机制解析

1. MyBaseModel 基类： 所有需要自动排除额外字段的模型都应继承自此基类。
2. @model_serializer(mode="wrap")：
   • @model_serializer 是 Pydantic V2 中用于自定义模型序列化行为的装饰器。
   • mode="wrap" 是关键。它表示我们的序列化器将“包装”默认的序列化逻辑。这意味着我们的方法会在默认序列化器执行之前或之后被调用，并能够修改其结果。
3. _serialize(self, handler: SerializerFunctionWrapHandler) 方法：
   • self 指的是当前模型实例。
   • handler 是一个可调用对象，它代表了 Pydantic 默认的序列化逻辑。当我们调用 handler(self) 时，它会返回模型实例的默认序列化字典。
4. default_dumped_data = handler(self)： 这一步获取了包含所有字段（包括额外字段）的原始序列化字典。
5. filtered_data = {k: v for k, v in default_dumped_data.items() if k in self.model_fields}：
   • 这是核心的过滤逻辑。self.model_fields 是一个字典，其键是模型中所有明确声明的字段名称。
   • 通过这个字典推导式，我们遍历 default_dumped_data 中的所有键值对，只保留那些键存在于 self.model_fields 中的项。这样，所有未在模型中声明的额外字段都会被排除。

使用场景与注意事项

• 全局应用： 通过让所有 Pydantic 模型继承 MyBaseModel，你可以为整个应用程序实现统一的额外字段排除策略，避免了在每个模型或每次 model_dump 调用时重复逻辑。
• 嵌套模型支持： 这种方法自然地支持嵌套模型。当 Root 模型被序列化时，其 nested 字段（如果也是 MyBaseModel 的子类）也会应用相同的过滤逻辑。
• 性能考量： 对于大多数应用而言，这种过滤操作的性能开销可以忽略不计。但如果你的模型非常庞大且序列化操作极其频繁，可以考虑进行性能测试。
• Pydantic 版本： 此解决方案基于 Pydantic V2 的 model_serializer 和 ConfigDict 语法。对于 Pydantic V1，需要使用不同的方法（例如 __post_init_validator__ 或自定义 json_encoders）。
• 选择性排除： 如果你只需要在特定模型或特定情况下排除额外字段，而不是全局排除，你可以将 _serialize 方法直接添加到需要此行为的特定模型中，而不是定义一个通用的 MyBaseModel。

总结

通过创建自定义的 MyBaseModel 并巧妙地运用 Pydantic V2 的 @model_serializer(mode="wrap") 装饰器，我们提供了一种优雅且可重用的方法来解决 model_dump 无法直接排除额外字段的问题。这种方法不仅简化了代码，提高了可维护性，也确保了序列化输出的数据结构始终符合预期，从而更好地适应各种数据交换场景。