Pydantic 模型更新时区分未提供字段与显式空值

结论先说：Pydantic 部分更新不能靠字段值是不是 None 判断客户端有没有提供它。Pydantic v2 应用 model_dump(exclude_unset=True) 只导出请求中真正出现的字段。这样，字段省略时不会进入更新集，而显式传入 null 时会保留为 Python 的 None。

不要把 exclude_none=True 当成替代方案。它会删除所有值为 None 的字段，连客户端明确表达的“请清空这个字段”也一起删除。

Pydantic 官方序列化文档：https://docs.pydantic.dev/latest/concepts/serialization/

升级范围：从整模型覆盖改为补丁模型

这个问题通常出现在 HTTP PATCH、表单草稿保存、用户资料局部修改和配置增量更新中。以个人简介 bio 为例，下面三种请求不能混为一谈：

因此需要两个模型：完整模型负责表达最终数据必须满足的约束，Patch 模型负责接收“哪些字段可能缺席”的请求。Patch 模型中的默认 None 只表示字段可以不提供，并不等于“提供了空值”。字段是否出现，由 model_fields_set 记录。

变更表：Pydantic v1 到 v2 相关 API

迁移时最容易忽略的是“必填”和“可空”已经是两个维度。email: str | None 表示字段必须出现，但允许值为 None；email: str | None = None 才表示字段可以不出现，而且出现时可以为 None。Patch 模型通常需要后一种声明。

三种输入状态必须分开

下面这段最小示例直接展示 model_fields_set 与 exclude_unset 的关系：

from pydantic import BaseModel


class ProfilePatch(BaseModel):
    # 默认 None 允许字段缺席，是否出现由 model_fields_set 记录
    bio: str | None = None


omitted = ProfilePatch.model_validate({})
explicit_null = ProfilePatch.model_validate({"bio": None})
explicit_empty = ProfilePatch.model_validate({"bio": ""})

# 未提供字段：显式字段集合为空，更新字典也为空
assert omitted.model_fields_set == set()
assert omitted.model_dump(exclude_unset=True) == {}

# 显式 null：字段集合包含 bio，None 会保留在更新字典中
assert explicit_null.model_fields_set == {"bio"}
assert explicit_null.model_dump(exclude_unset=True) == {"bio": None}

# 空字符串是独立业务值，不应该和 null 合并
assert explicit_empty.model_dump(exclude_unset=True) == {"bio": ""}

model_fields_set 很适合调试、审计和编写针对性测试；真正构造更新字典时，直接调用 model_dump(exclude_unset=True) 更简洁。官方文档还说明，模型创建后给某个字段赋值，会把它记为已设置字段。因此最好从原始请求直接建立 Patch 模型，并在导出更新数据前不要修改它。

旧代码风险：三个看似合理的写法

直接 model_dump 会覆盖未提供字段

changes = patch.model_dump()

# 错误原因：未提供字段也会带着默认 None 进入 changes
for field_name, value in changes.items():
    setattr(stored, field_name, value)

当请求只修改 name 时，email 和 bio 仍可能以默认 None 出现在导出结果中，原数据就会被意外清空。

exclude_none 会丢失“主动清空”

changes = patch.model_dump(exclude_none=True)

# 错误原因：显式传入的 null 也会被过滤掉
assert "bio" not in changes

这个写法适合“所有空值都不发送”的序列化需求，却不适合必须保留显式空值的 PATCH 语义。

逐字段判断 is not None 仍然混淆状态

if patch.bio is not None:
    # 错误原因：bio=null 时不会进入这里，无法执行清空
    stored.bio = patch.bio

值判断回答的是“现在的值是什么”，而部分更新需要回答“请求中有没有这个键”。这是两个问题。

推荐的 Pydantic v2 更新写法

下面的实现把输入模型、更新集合和完整模型校验分开。extra="forbid" 让拼错的字段名尽早失败，避免客户端以为更新成功。

from pydantic import BaseModel, ConfigDict, model_validator


class User(BaseModel):
    model_config = ConfigDict(extra="forbid")

    name: str
    email: str | None
    bio: str | None = None

    @model_validator(mode="after")
    def check_contact_rule(self) -> "User":
        # 示例业务约束：姓名与邮箱不能同时为空
        if not self.name.strip() and self.email is None:
            raise ValueError("姓名与邮箱不能同时为空")
        return self


class UserPatch(BaseModel):
    model_config = ConfigDict(extra="forbid")

    # 默认 None 仅表示字段可以省略，显式 null 仍会被记录
    name: str | None = None
    email: str | None = None
    bio: str | None = None


def apply_patch(stored: User, patch: UserPatch) -> User:
    # 只提取客户端实际提供的键，显式 None 会保留
    changes = patch.model_dump(exclude_unset=True)

    # 在完整旧数据上覆盖指定键，避免遗漏字段被默认值替换
    merged = stored.model_dump()
    merged.update(changes)

    # 重建完整模型，让字段校验和跨字段约束重新执行
    return User.model_validate(merged)

如果 Patch 模型已经完整验证了更新值，而且目标模型没有需要重新执行的跨字段约束，也可以写成 stored.model_copy(update=changes)。但 model_copy(update=...) 的更新数据不会重新走完整验证，所以面向业务实体时，我更推荐合并后调用 User.model_validate()。这样即使单个字段合法，组合后违反业务约束也会被拦住。

嵌套模型、别名和默认值的边界

嵌套对象不能默认按浅层字典合并

假设用户模型中有 address 对象，请求只传 {"address": {"city": "杭州"}}。虽然嵌套 Patch 模型同样可以用 exclude_unset=True 导出显式字段，但普通 dict.update() 会把整个 address 替换掉，而不是只改 city。应为嵌套对象建立独立 Patch 模型，并按领域规则递归合并，不能把“过滤未提供字段”和“深度合并”当成同一件事。

是否使用 by_alias 取决于更新目标

若 API 使用 userName，而 Python 字段是 user_name，写回数据库或模型字段时通常应保留字段名，也就是使用默认的 by_alias=False。只有目标系统确实以别名为键时，才使用 model_dump(by_alias=True)。

exclude_defaults 也不等于 exclude_unset

exclude_defaults=True 会删除与默认值相等的字段。可是假如客户端明确希望把重试次数设回默认值 3，这个意图仍应保留。因此只要业务关心“键是否出现”，就应使用 exclude_unset=True。

回归检查：至少锁住这四类请求

def make_user() -> User:
    # 每个测试使用全新的完整模型，避免状态互相污染
    return User(name="Ada", email="ada@example.com", bio="Python")


def test_omitted_field_is_not_updated() -> None:
    patch = UserPatch.model_validate({"name": "Grace"})
    updated = apply_patch(make_user(), patch)

    # name 被修改，但省略的 email 和 bio 保持原值
    assert updated.name == "Grace"
    assert updated.email == "ada@example.com"
    assert updated.bio == "Python"


def test_explicit_null_is_preserved() -> None:
    patch = UserPatch.model_validate({"bio": None})
    updated = apply_patch(make_user(), patch)

    # 显式 null 表示主动清空，因此最终值应为 None
    assert updated.bio is None


def test_empty_string_is_not_null() -> None:
    patch = UserPatch.model_validate({"bio": ""})
    updated = apply_patch(make_user(), patch)

    # 空字符串是独立业务值，不能自动转换成 None
    assert updated.bio == ""


def test_unknown_field_is_rejected() -> None:
    from pydantic import ValidationError

    try:
        UserPatch.model_validate({"bi0": "typo"})
    except ValidationError:
        # 拼错字段名应明确报错，不能静默忽略
        return
    raise AssertionError("未知字段没有被拒绝")

真实项目还应补上完整模型的跨字段校验失败、嵌套 Patch 合并、字段别名和数据库事务回滚测试。测试断言不要只看 HTTP 状态码，还要确认未提供字段确实保持原值。

迁移清单

1. 分离模型：完整实体模型与 Patch 输入模型不要共用一套必填规则。
2. 迁移 API：把 v1 的 dict() 改为 v2 的 model_dump()，把字段集合读取改为 model_fields_set。
3. 固定导出策略：更新字典统一来自 model_dump(exclude_unset=True)。
4. 拒绝误用：不要用 exclude_none、exclude_defaults 或 is not None 判断字段是否出现。
5. 重新校验：存在跨字段约束时，合并完整字典后调用目标模型的 model_validate()。
6. 处理嵌套：为嵌套对象设计专门的 Patch 模型与合并规则。
7. 补齐测试：至少覆盖字段省略、显式 null、空字符串和未知字段。

常见问题

Patch 模型把字段默认值写成 None，会不会把数据库值清空？

只要更新字典使用 exclude_unset=True 就不会。未提供字段虽然在模型属性上可能读到 None，但它不在 model_fields_set 中，也不会进入导出的更新字典。

什么时候可以使用 exclude_none=True？

只有业务明确规定“任何 None 都不参与序列化或更新”时才适合。只要 null 有“清空字段”的业务含义，就不能使用它。

直接检查 field_name in patch.model_fields_set 可以吗？

可以，尤其适合单字段特殊处理。但普通批量更新仍建议先导出 changes，这样逻辑集中、测试也更简单。

model_copy(update=changes) 与 model_validate 哪个更好？

前者简洁，适合更新数据已经可信且无需重跑完整模型约束的场景；后者会重新验证合并结果，更适合包含跨字段规则的业务实体。

总结

Pydantic 部分更新的关键不是判断值，而是保留“字段是否出现”这层信息。model_fields_set 记录显式输入，model_dump(exclude_unset=True) 把这层信息转成安全的更新字典，于是省略、显式 null 和空字符串可以各自表达不同意图。

完成 v2 迁移时，再把完整模型重建、嵌套合并和四类回归测试补上，就能避免未提供字段被覆盖，也不会误删客户端主动清空字段的请求。