在 Pydantic v2 中，BaseModel 默认会忽略输入数据里未声明的字段，只有显式定义的字段会被构造进实例。不过很多项目为了提高容错性，会把 model_config 中的 extra 改成 allow，让模型先把外部接口返回的所有数据都接收下来。这样实例内部会多出一个专门保存额外字段的字典，导出时这些字段也会跟着序列化。要想在导出时忽略额外字段，不能简单依赖 exclude_unset，而需要理解额外字段的存储位置以及 model_dump 的过滤机制。

先弄清楚额外字段被存放在哪里

当 model_config 设置 extra='allow' 时，Pydantic 会把未声明的字段放进实例的 __pydantic_extra__ 字典。如果使用较新版本的 Pydantic，还可以通过 model_extra 属性访问同一份数据。这个字典与模型字段完全分离，不会参与校验，也不会出现在 model_fields 中。也就是说，从数据校验的角度看，额外字段是被保留的原始输入，但从模型结构角度看，它们并不属于类型定义的一部分。理解这一点很重要，因为后续过滤操作需要从这个内部字典里取出键名。

下面代码创建了一个带额外字段的模型实例，并查看存储结果。运行后，__pydantic_extra__ 会输出 {'role': 'admin', 'level': 5}，而 model_dump() 则包含全部字段。

from pydantic import BaseModel, ConfigDict
class User(BaseModel):
    model_config = ConfigDict(extra='allow')
    id: int
    name: str
user = User(id=1, name='Tom', role='admin', level=5)
print(user.__pydantic_extra__)
print(user.model_dump())

从输出结果可以明显看到，默认序列化行为并没有区分声明字段与额外字段。如果不希望额外字段进入导出结果，可以从这个字典中取出所有键，再交给 model_dump 的 exclude 参数进行过滤。这个思路非常直接，而且不改变模型定义，不影响实例内部继续保留额外数据。下面小节会展开具体写法。

使用 model_dump 的 exclude 参数实现过滤

model_dump 是 Pydantic v2 中最常用的序列化方法，它接收多个控制输出内容的参数。其中 exclude 参数可以接收字段名集合、字典或可调用对象，用来在导出阶段移除指定字段。对于额外字段，最简单的做法是把 __pydantic_extra__ 的键集合传给 exclude。由于额外字段不参与校验，这种过滤不会触发字段缺失或类型错误。

extra_keys = set(user.__pydantic_extra__.keys())
clean = user.model_dump(exclude=extra_keys)
print(clean)

这里输出 {'id': 1, 'name': 'Tom'}，额外字段不再出现。如果业务上只需要保留部分额外字段，可以先取差集再传入 exclude。比如想保留 level，但过滤掉 role，可以这样写：

keep = {'level'}
exclude_keys = set(user.__pydantic_extra__.keys()) - keep
clean = user.model_dump(exclude=exclude_keys)
print(clean)

输出结果为 {'id': 1, 'name': 'Tom', 'level': 5}。这种方式既保留了容错能力，又能精确控制输出结构。需要注意的是，exclude 参数不会修改原实例，每次调用都会返回新字典，因此可以安全地用于缓存前的序列化场景。

有人可能会想到 exclude_unset=True，但这里要特别说明：额外字段在构造时也会被 Pydantic 标记为已设置，因此 exclude_unset 通常不会过滤额外字段。实际测试可以发现 user.model_dump(exclude_unset=True) 依然包含 role 和 level。所以如果想只输出声明字段，exclude 加 __pydantic_extra__ 键集合才是可靠做法。

把过滤逻辑封装成可复用的导出方法

如果多个模型都需要在导出时忽略额外字段，为每个调用点重复写 set(obj.__pydantic_extra__.keys()) 显然不够友好。更推荐的做法是在基类或混入类中定义一个方法，比如 to_clean_dict，内部统一完成过滤。对于简单的扁平模型，这个方法只需要一行逻辑。

class BaseCleanModel(BaseModel):
    def to_clean_dict(self):
        return self.model_dump(exclude=set(self.__pydantic_extra__.keys()))

不过真实项目中的模型往往包含嵌套结构。一个模型字段的值可能是另一个 BaseModel，或者包含 BaseModel 的列表。此时仅在外层模型上调用 model_dump 并排除外层额外字段，嵌套模型里的额外字段仍会被导出。例如 Order 里包含 Item，Item 也设置了 extra='allow'，那么 order.to_clean_dict() 只会过滤 Order 的额外字段，Item 的额外字段依然存在。要解决这个问题，需要递归处理。

from typing import Any
def dump_without_extra(obj: Any) -> Any:
    if not isinstance(obj, BaseModel):
        return obj
    result = {}
    for field_name in obj.model_fields:
        value = getattr(obj, field_name)
        if isinstance(value, BaseModel):
            result[field_name] = dump_without_extra(value)
        elif isinstance(value, list):
            result[field_name] = [
                dump_without_extra(item) if isinstance(item, BaseModel) else item
                for item in value
            ]
        else:
            result[field_name] = value
    return result

这个函数只遍历 model_fields 中的声明字段，因此天然忽略所有额外字段。如果字段值是 BaseModel，就递归调用；如果是列表，就逐项处理。可以根据需要继续扩展 dict 或 set 类型。

下面给出一个完整的使用示例：

class Item(BaseModel):
    model_config = ConfigDict(extra='allow')
    id: int
class Order(BaseModel):
    model_config = ConfigDict(extra='allow')
    order_id: int
    item: Item
order = Order(order_id=100, item=Item(id=1, note='inner extra'), note='outer extra')
print(dump_without_extra(order))

输出 {'order_id': 100, 'item': {'id': 1}}。这样即使存在多层嵌套，输出也能保持干净。如果后续还希望保留部分额外字段，可以在函数中增加白名单参数，从 __pydantic_extra__ 中按需复制键值。

在模型定义层过滤与导出层过滤之间做选择

需求确定后，首先要判断是否真的需要 extra='allow'。如果模型只是用来接收数据并立即落库或返回，后续完全不会使用未声明的字段，那么最简单的做法是保留默认的 extra='ignore'。这样额外字段在构造阶段就被丢弃，实例中不会保存它们，model_dump 自然只包含声明字段。这个方案没有任何额外代码，也没有内存负担，适合数据源相对稳定、字段变化较少的场景。

但如果外部接口返回的字段频繁变化，或者团队希望在联调阶段观察没有建模的数据，那么 extra='allow' 就有实际价值。此时模型像一个宽容的容器，先把所有数据保存下来，方便后续排查问题和扩展字段。导出时再通过前面介绍的 exclude 或递归方法过滤，形成“宽进严出”的流水线。这样既能提高对接时的容错性，又能保证输出给下游的结构稳定。

总体来看，忽略额外字段并不是一个单一开关，而是与模型生命周期和团队协作方式相关。在定义层忽略更简单，在导出层过滤更灵活。选择哪种方案，取决于未声明字段在你的业务中究竟是噪声还是潜在资产。理解清楚这一点，Pydantic 的 extra 配置和 model_dump 参数就能组合出适合项目的处理方式。