Go encoding/json 怎样区分缺失字段和显式 null处理空输入并保留错误边界

在 Go 服务里处理用户资料 PATCH 时，下面三个请求看起来都很像：字段没有传、字段传了 null、字段传了空字符串。对普通的 string 字段来说，encoding/json 解码后很容易都变成 ""，更新层就无法判断“保持原值”还是“清空原值”。

需要区分缺失和显式 null 时，不要只给字段换成指针：指针可以区分具体值和 nil，却不能单独区分“字段缺失”和“字段为 null”。更稳妥的做法是让字段类型记录是否出现、是否为 null，以及具体值。

官方资料：https://pkg.go.dev/encoding/json

官方教程：https://go.dev/doc/tutorial/json

普通字段为什么看不出缺失和 null

Unmarshal 会按 JSON key 找到目标结构体字段。JSON 对象里没有这个 key 时，字段保持原来的 Go 值；如果把 null 解到普通字符串，标准库也不会把它变成一个特殊字符串，而是保持原值。新建零值结构体时，这两种输入自然都表现为 ""。

package main

import (
    "encoding/json"
    "fmt"
)

type Patch struct {
    Nickname string `json:"nickname"`
}

func main() {
    inputs := []string{`{}`, `{"nickname":null}`, `{"nickname":""}`, `{"nickname":"小林"}`}
    for _, input := range inputs {
        var patch Patch
        // 每次使用新结构体，避免上一次解码留下的值干扰当前结果。
        err := json.Unmarshal([]byte(input), &patch)
        fmt.Printf("input=%-24s nickname=%q err=%v\n", input, patch.Nickname, err)
    }
}

这段代码的前 3 个结果都会让 Nickname 看起来像空字符串，只有最后一个输入能直接得到具体值。把字段改成 *string 后，具体字符串和 nil 可以区分，但缺失与 null 仍然都会是 nil。这个差异正是局部更新接口最容易踩到的地方。

先用 RawMessage 拆出字段状态

如果只需要处理少量字段，可以先把 JSON 对象解码到 map[string]json.RawMessage。map 的 ok 结果负责回答“字段是否出现”，原始字节负责回答“它是不是 null”，最后再把具体值解到目标类型。这样三种语义不会在第一步就被压平。

package patch

import (
    "bytes"
    "encoding/json"
    "errors"
    "fmt"
)

type StringPatch struct {
    Present bool
    Null    bool
    Value   string
}

func readStringPatch(data []byte, name string) (StringPatch, error) {
    if len(bytes.TrimSpace(data)) == 0 {
        // 空请求体不是“字段缺失”，而是调用方没有提供 JSON 文档。
        return StringPatch{}, errors.New("JSON 请求体为空")
    }

    var fields map[string]json.RawMessage
    if err := json.Unmarshal(data, &fields); err != nil {
        // 语法错误停留在输入边界，调用方可以返回 400，而不是继续更新。
        return StringPatch{}, fmt.Errorf("解析 JSON 对象失败: %w", err)
    }

    raw, ok := fields[name]
    if !ok {
        // key 不存在表示保持原值，不能和显式 null 混用。
        return StringPatch{}, nil
    }

    result := StringPatch{Present: true}
    if bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
        // null 表示调用方明确要求清空或设置为空状态。
        result.Null = true
        return result, nil
    }

    if err := json.Unmarshal(raw, &result.Value); err != nil {
        // 类型错误与 null 是两条不同的业务路径，不能静默吞掉。
        return StringPatch{}, fmt.Errorf("字段 %q 类型错误: %w", name, err)
    }
    return result, nil
}

调用层可以把结果映射成明确的更新动作：

用泛型 Nullable 把判断放进字段类型

当多个 PATCH 结构都需要同样的语义时，重复写 RawMessage 解析会让每个 handler 都变长。可以定义一个泛型包装器，让 UnmarshalJSON 只负责“字段已经出现”的情况：缺失字段不会调用这个方法，显式 null 会调用它并设置 Null=true。

package patch

import (
    "bytes"
    "encoding/json"
    "fmt"
)

type Nullable[T any] struct {
    Present bool
    Null    bool
    Value   T
}

func (n *Nullable[T]) UnmarshalJSON(data []byte) error {
    // 先清零，保证同一个目标对象被重复解码时不会残留旧状态。
    *n = Nullable[T]{Present: true}
    if bytes.Equal(bytes.TrimSpace(data), []byte("null")) {
        // UnmarshalJSON 会收到显式 null，但缺失字段不会进入这里。
        n.Null = true
        return nil
    }

    var value T
    if err := json.Unmarshal(data, &value); err != nil {
        // 保留底层类型错误，让上层可以区分 400 输入错误和业务清空。
        return fmt.Errorf("Nullable 值类型错误: %w", err)
    }
    n.Value = value
    return nil
}

type UserPatch struct {
    Nickname Nullable[string] `json:"nickname"`
    Age      Nullable[int]    `json:"age"`
}

因此，UserPatch{} 中的 Nickname.Present 是 false；当输入包含 "nickname":null 时，Present 为 true、Null 为 true；当输入包含 "nickname":"小林" 时，Present 和 Value 有效。这个类型还可以扩展 MarshalJSON，但读写语义最好分别设计，不要为了复用解码包装器而改变已有响应格式。

把空输入、非法类型和未知字段分开

“缺失字段”只表示 JSON 对象里没有某个 key，不表示请求体为空，也不表示 JSON 语法错误。建议在入口处保留三个边界：

1. 空白请求体：先判断 bytes.TrimSpace 后长度，返回“缺少 JSON 文档”的输入错误。
2. 非法 JSON：让 json.Unmarshal 返回 SyntaxError，不要把失败对象当作空 patch。
3. 字段类型不匹配：保留 UnmarshalTypeError 的上下文；例如数字不能静默变成字符串。

如果接口不允许客户端传入未认识的字段，可以改用 json.Decoder 并调用 DisallowUnknownFields。但这是另一项接口策略：它解决的是“字段名是否受支持”，不能代替 Present/Null 状态。

func decodeStrict(data []byte, dst any) error {
    decoder := json.NewDecoder(bytes.NewReader(data))
    decoder.DisallowUnknownFields() // 将拼写错误的字段名留在请求层处理。
    if err := decoder.Decode(dst); err != nil {
        return fmt.Errorf("解码请求失败: %w", err)
    }
    return nil
}

还要注意对象复用：标准库对结构体解码会把新数据合并到已有对象，缺失字段不会自动替换旧值。因此，做 PATCH 合并时可以利用这一点，但做独立请求解析时最好每次创建新目标，或者在解码前显式清零。Nullable 的自定义方法已经在字段出现时重置自身；整个结构体是否复用仍由调用方负责。

三种场景怎么选

落地时可以按这个顺序检查：先问业务是否真的区分“保持原值”和“清空”；再决定是否需要三态包装；接着为 null、空字符串、具体值、非法类型和空请求体分别写用例；最后确认 handler 没有复用带旧值的目标对象。这样处理后，encoding/json 的默认宽松行为仍然保留，但不会再悄悄吞掉更新意图。

相关问题

指针字段能不能区分缺失和 null？

单独的 *T 不能。具体值会是非 nil 指针，缺失和显式 null 都通常是 nil；要区分后两者，需要额外的 Present 标志、RawMessage 或自定义解码类型。

null 解到 string 为什么不报错？

这是 encoding/json 的既定语义：null 解到 interface、map、pointer 或 slice 会置 nil；解到其他 Go 类型通常对值不产生影响，也不报错。要把 null 禁止掉，需要在字段类型或业务层显式检查。

空字符串和 null 应该都当成“清空”吗？

不要由解码器替业务决定。Nullable 可以把两者分开，最终是写入空字符串、数据库 NULL 还是拒绝请求，应由字段契约和存储层规则决定。

什么时候直接用 map[string]any？

只在字段结构确实动态、且你愿意承担数字默认解为 float64 等类型转换成本时使用。固定 DTO 的局部更新更适合 RawMessage 或 Nullable，错误边界更容易维护。