Pydantic v2 中临时排除字段用 .model_dump(exclude=...),永久排除用 Field(exclude=True);私有字段不再自动忽略,必须显式设置 exclude;exclude=True 不影响验证,仅控制序列化输出。

pydantic v2 中用 exclude 参数临时跳过字段序列化
最直接的方式是在调用 .model_dump() 或 .model_dump_json() 时传入 exclude 参数。它支持字段名字符串、set、dict(用于嵌套排除)等多种形式:
-
exclude={"password"}—— 忽略顶层字段password -
exclude={"credentials": {"token"}}—— 忽略嵌套模型中credentials.token -
exclude={"_internal_id", "cache_ttl"}—— 一次排除多个字段
注意:exclude 是运行时控制,不影响模型定义,也不影响验证逻辑;同一实例多次调用可传不同 exclude 值。
用 Field(exclude=True) 让字段默认不参与序列化
若某个字段**永远不该出现在序列化结果里**(比如敏感缓存、内部状态),在字段定义时加 exclude=True 即可:
from pydantic import BaseModel, Fieldclass User(BaseModel): name: str password: str = Field(exclude=True) # 序列化时自动忽略 _version: int = Field(default=1, exclude=True)
这个设置会作用于所有序列化方法(.model_dump()、.model_dump_json()、.json() 等),且不会出现在 .model_json_schema() 的输出中。
⚠️ 容易踩的坑:exclude=True 不等于“不参与验证”——字段仍会校验类型、约束(如 min_length),只是不输出。如果真想完全跳过校验和序列化,得用私有字段 + Field(default=None, exclude=True) 并确保初始化时不传值。
用私有字段(下划线开头)配合 model_config = ConfigDict(ignored_types=(type,))?别这么干
pydantic v2 **不再自动忽略以下划线开头的字段**。私有字段(如 _temp_cache)默认仍会参与序列化,除非显式设 exclude=True。
有人试图通过配置 ignored_types 或自定义 __pydantic_core_schema__ 绕过,但这些方式要么无效,要么破坏模型一致性。正确做法就是老老实实写 Field(exclude=True)。
另外,Field(default_factory=...) 配合 exclude=True 是安全的,适用于需要动态生成但不暴露的内部值。
序列化时字段消失但反序列化仍需传入?检查 default 或 default_factory
如果字段设置了 exclude=True,但它在构造模型实例时又必须提供(比如没有默认值),那它虽然不出现在输出里,却仍是必填项。这时容易误以为“被忽略了所以可以不传”,结果报 ValidationError。
- 要彻底移出输入/输出双通道:用
Field(default=None, exclude=True)+ 初始化时确保不传该字段 - 或改用
typing.ClassVar(仅限真正只读的类级别常量) -
Field(init=False)可让字段不参与__init__,但需配合exclude=True才能不出现在序列化中
最稳妥的组合是:field_name: str = Field(default="fallback", exclude=True, init=False) —— 既不进初始化,也不进序列化,只在模型内部用。










