本教程演示如何在 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 装饰器，在模型序列化过程中对输出字典进行后处理。这种方法允许我们在默认序列化逻辑执行完毕后，对结果进行精细控制，从而实现自动排除额外字段。
核心思路是：
- 定义一个继承自 BaseModel 的 MyBaseModel。
- 在 MyBaseModel 中使用 @model_serializer(mode=”wrap”) 装饰器定义一个序列化方法。
- 在这个序列化方法中，首先调用 handler(self) 获取 Pydantic 默认的序列化结果。
- 然后，遍历这个结果字典，只保留那些键存在于 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 模型的额外字段也已成功排除。")
核心机制解析
- MyBaseModel 基类： 所有需要自动排除额外字段的模型都应继承自此基类。
- @model_serializer(mode=”wrap”)：
- @model_serializer 是 Pydantic V2 中用于自定义模型序列化行为的装饰器。
- mode=”wrap” 是关键。它表示我们的序列化器将“包装”默认的序列化逻辑。这意味着我们的方法会在默认序列化器执行之前或之后被调用，并能够修改其结果。
- _serialize(self, handler: SerializerFunctionWrapHandler) 方法：
- self 指的是当前模型实例。
- handler 是一个可调用对象，它代表了 Pydantic 默认的序列化逻辑。当我们调用 handler(self) 时，它会返回模型实例的默认序列化字典。
- default_dumped_data = handler(self)： 这一步获取了包含所有字段（包括额外字段）的原始序列化字典。
- 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 无法直接排除额外字段的问题。这种方法不仅简化了代码，提高了可维护性，也确保了序列化输出的数据结构始终符合预期，从而更好地适应各种数据交换场景。