Pydantic自动忽略多余字段技巧

本篇文章主要是结合我之前面试的各种经历和实战开发中遇到的问题解决经验整理的，希望这篇《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 无法直接排除额外字段的问题。这种方法不仅简化了代码，提高了可维护性，也确保了序列化输出的数据结构始终符合预期，从而更好地适应各种数据交换场景。

终于介绍完啦！小伙伴们，这篇关于《Pydantic自动忽略多余字段技巧》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！