Go json.Decoder区分 null、空串和缺失字段的结构设计

在更新接口里，name 没传、传了 null、传了 "" 往往是三种完全不同的意图：不修改、清空，或写入空文本。直接把字段声明成 string 后，缺失和空串都会落到零值，使用普通指针又会让缺失和 null 都变成 nil。更稳妥的做法是让 json.Decoder 解码到包含 json.RawMessage 的补丁结构，再集中转换字段状态。

官方地址：https://pkg.go.dev/encoding/json

先把三种输入映射成三种状态

先看目标，不急着写解析代码：缺失字段代表调用方没有提出修改；null 通常代表明确清空；空字符串是一个真实的字符串值，是否允许要由业务规则决定。这个区别必须在解码阶段保留，否则进入服务层后就很难恢复原意。

用 RawMessage 保留存在性与原始值

json.RawMessage 本质上是一段延迟解析的 JSON 数据。结构体字段没有出现在输入对象中时保持 nil；字段出现并且值是 null 时，原始内容仍是 null。这正好把“有没有传”和“传了什么”拆开。

type Patch struct {
    // RawMessage 先保留字段是否出现以及原始 JSON 值。
    Name json.RawMessage `json:"name"`
}

type FieldState struct {
    // Present 区分缺失；Null 区分显式 JSON null。
    Present     bool
    Null        bool
    EmptyString bool
    Value       string
}

func parseStringField(raw json.RawMessage) (FieldState, error) {
    state := FieldState{Present: raw != nil}
    if raw == nil {
        return state, nil // 没传字段：交给上层保持原值
    }
    if string(raw) == "null" {
        state.Null = true // 显式 null：通常对应清空动作
        return state, nil
    }

    var value string
    if err := json.Unmarshal(raw, &value); err != nil {
        return FieldState{}, fmt.Errorf("name must be a JSON string: %w", err)
    }
    state.Value = value
    state.EmptyString = value == ""
    return state, nil
}

这里没有用 strings.TrimSpace 把空格也当成空串，因为“空字符串”和“只含空格的字符串”可能是两种业务值。若接口要求去除首尾空格，应在状态判定之后明确写出这个规则。

用 Decoder 解码并集中校验

补丁对象可以直接从请求体创建 Decoder。解析函数只负责表达 JSON 事实，是否允许空串、是否允许清空则放在业务校验表或服务层，避免把存储策略塞进通用解析器。

func decodePatch(input string) (FieldState, error) {
    // Reader 模拟 HTTP 请求体；Decoder 负责读取 JSON 对象。
    dec := json.NewDecoder(strings.NewReader(input))
    var patch Patch
    if err := dec.Decode(&patch); err != nil {
        return FieldState{}, fmt.Errorf("decode patch: %w", err)
    }
    return parseStringField(patch.Name)
}

func applyName(state FieldState) error {
    // 业务层把三种状态映射成三种动作，不依赖 string 零值猜测。
    switch {
    case !state.Present:
        return nil // 缺失：保持数据库原值
    case state.Null:
        return clearName() // null：执行清空
    case state.EmptyString:
        return errors.New("name cannot be empty") // 按规则拒绝空串
    default:
        return updateName(state.Value) // 普通字符串：执行更新
    }
}

如果请求体可能带多个 JSON 值，还要在第一次 Decode 后继续检查是否存在非空尾部；单次 Decode 成功只说明第一个值合法。生产接口通常还会限制请求大小，并在读取失败时返回明确的客户端错误。

落库前的边界与检查清单

• 解析错误、类型错误和业务校验错误分开返回，便于定位调用方问题。
• 多个可更新字段都使用同样的状态模型时，可把 FieldState 扩展成泛型或按类型定义解析函数，但不要为了抽象而丢掉原始错误。
• 如果字段必须“传且非空”，检查 Present 与 EmptyString；如果字段可清空，再单独开放 Null。
• 不要用 omitempty 反推请求字段是否出现，它主要影响编码，不会替你恢复输入对象的存在性。

相关问题

为什么普通 string 不能区分缺失和空串？

因为缺失字段不会覆盖结构体字段，字段保留零值，而空串解码后也是同一个零值。需要 RawMessage、额外的存在标记，或专门的可选类型。

指针字段能不能解决 null 和缺失？

不能单独解决。普通 *string 下，缺失与 null 都通常是 nil；它适合表达是否有字符串值，不适合完整记录三态输入。

空串一定要拒绝吗？

不一定。显示名称、备注等字段可能允许空文本；关键是先保留状态，再由领域规则决定拒绝、写入或转换。