Go JSON 中 null 和字段缺失为什么结果不同

Go 的 encoding/json 解码时，JSON 中“没有这个字段”和“字段存在但值是 null”不是同一件事。前者表示输入没有覆盖该键，后者表示输入明确给出了空值；最终差异还取决于接收目标是普通值、指针还是 map。更新接口时如果把两者都当成零值，最容易出现“客户端没传却被清空”的问题。

这篇文章按一个排障场景拆开判断：先看输入状态，再看结构体字段如何落地，最后用 map 的 ok 结果保留“是否出现过”这个信息。示例只讨论 Go 标准库 encoding/json。

触发信号：为什么没传字段也可能看见旧值

假设服务收到两个补丁请求：第一个完全没有 nickname，第二个写成 "nickname": null。在 JSON 层面，前者没有键，后者有键且值为空；它们携带的业务意图并不相同。

官方 Unmarshal 规则可以先记成两句话：结构体只更新输入中匹配到的字段；JSON null 解码到指针、map、slice 或 interface 时会设置为 nil，解码到其他 Go 类型通常不改变原值，也不会因此报错。

因此，排查时不要只打印结构体最终值。一个零值可能来自“没有传”，也可能来自“传了 null 后被清空”，还可能只是字段本来就是零值。

快速判断：普通字段和指针字段的结果不同

先用同一个目标结构体接收两种输入。为了看出“缺失是否覆盖”，代码故意把目标字段预先设成旧值；这段代码是静态示例，不代表本文已经运行过它。

package main

import (
    "encoding/json"
    "fmt"
)

type Profile struct {
    Name  string  `json:"name"`
    Alias *string `json:"alias"`
}

func main() {
    oldAlias := "旧昵称"
    absent := Profile{Name: "旧姓名", Alias: &oldAlias}
    explicitNull := absent

    // 缺失 name 和 alias 时，输入没有覆盖已有字段。
    _ = json.Unmarshal([]byte(`{}`), &absent)

    // null 对指针字段表达“明确清空”，普通值字段另有规则。
    _ = json.Unmarshal([]byte(`{"name":null,"alias":null}`), &explicitNull)

    // 这里的输出用于观察状态：缺失保留旧指针，null 让指针变成 nil。
    fmt.Println(absent.Name, absent.Alias != nil)
    fmt.Println(explicitNull.Name, explicitNull.Alias == nil)
}

对 Profile 来说，{} 不会覆盖 Name 或 Alias，所以旧值仍在；"alias": null 会把指针设为 nil。"name": null 则不会把普通 string 自动变成某种“空值对象”，它对这个非可空目标没有覆盖效果。

这里有一个很容易被忽略的边界：如果目标结构体一开始就是零值，那么缺失和 null 在普通字段上都可能看起来一样。只有预先保留旧值，或额外保存字段存在性，差异才可观察。

处理步骤：用 map 的 ok 区分不存在和存在但为空

当业务关心“客户端是否明确传过这个键”时，map[string]any 的查值必须同时接收值和 ok。只看 value == nil 会把两种状态混在一起。

package main

import (
    "encoding/json"
    "fmt"
)

func main() {
    var patch map[string]any
    if err := json.Unmarshal([]byte(`{"nickname":null}`), &patch); err != nil {
        // 输入不是合法 JSON 时，不能把错误误判成字段缺失。
        panic(err)
    }

    value, ok := patch["nickname"]
    // ok=true 表示键出现过；value 为 nil 表示它的 JSON 值是 null。
    fmt.Printf("value=%v, ok=%t\n", value, ok)

    _, missing := patch["email"]
    // 读取不存在的键时，零值也可能是 nil，所以要看第二个返回值。
    fmt.Printf("email-present=%t\n", missing)
}

在这个模型中，nickname 的结果是“键存在、值为 nil”，而 email 的结果是“键不存在”。如果补丁语义是“传 null 就清空，没传就保持”，这一对状态正好可以映射到业务动作。

如果希望保留原始 JSON 片段，也可以使用 map[string]json.RawMessage：缺失键仍然没有 map 项，显式 null 则会保留内容为 null 的原始消息。这样比把所有输入先压成 any 更适合需要区分多种输入状态的补丁协议。

回滚路径：不要用 omitempty 修复解码语义

omitempty 主要影响结构体编码成 JSON 时是否省略空值，不会把解码阶段的字段缺失和 null 自动变成两个可追踪事件。把它加到 tag 上，不能解决“更新接口如何判断客户端意图”的问题。

如果新改动把 null 当成“不更新”，回滚时应回到字段级规则，而不是整段覆盖对象：

对部分更新接口，比较稳妥的做法是先定义字段语义：普通字段只表示“最终值”，指针字段表示“可清空的值”，map 或 RawMessage 表示“是否出现以及原始内容”。不要在同一个接口里让调用者猜测零值的含义。

告警确认：遇到结果相同先查这三件事

1. 目标对象是否在解码前已经有旧值？如果每次都新建零值对象，缺失和 null 的差别可能被掩盖。
2. 字段是普通值、指针、map 还是 interface？null 对不同目标类型的处理规则不同。
3. 你是否只读取了 map 的第一个返回值？没有使用 ok 时，键不存在和键值为 nil 都会像“查到 nil”。

最后可以把结论压缩成一句排障口诀：先判断键是否存在，再判断值是否为 null，最后才按 Go 目标类型解释落点。这样处理后，字段缺失与显式清空就不会因为一次零值比较而失去边界。

常见问题

字段缺失和 null 在普通 string 上为什么经常看起来一样？

因为结构体字段的默认值就是空字符串，而 null 解码到非指针等普通目标时不会产生可见的特殊值。若业务必须区分两者，应使用指针、存在位或 map 搭配 ok。

给字段加 omitempty 能区分输入状态吗？

不能。它解决的是编码输出是否省略空值；输入是否出现、是否为 null，需要在解码目标或自定义解码逻辑中单独表达。