Go json.RawMessage 如何区分字段缺失和显式 null

在部分更新接口里，字段“没有出现”和字段“明确传入 null”往往不是一回事：前者通常表示不修改，后者可能表示清空。如果直接把 JSON 解码到 *string 或 *int，这两种输入都可能落到 nil，业务层就失去了判断依据。

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

json.RawMessage 会保留字段对应的原始 JSON：字段缺失时通常保持空切片，显式 null 时保留字节串 null，传入具体值时则保留该值的 JSON 文本。用这三个状态就能把“不修改、清空、更新”分开。

先看三种输入的差别

假设请求结构中有一个 nickname 字段，下面三种 JSON 的业务意思可能完全不同：

这也是普通指针不够用的地方。指针可以区分“有值”和“没有值”，但在许多解码场景里，缺失和显式 null 都会让目标指针保持或变成 nil。RawMessage 保存的是原始 JSON 字节，因此可以把“是否出现”和“出现后是什么值”拆开判断。

用 RawMessage 保存字段状态

先把可能参与部分更新的字段声明成 json.RawMessage。判断顺序建议固定为：先判断长度，再判断是否为 JSON 的 null，最后把剩余内容解码成目标类型。

package main

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

type PatchProfile struct {
    Nickname json.RawMessage `json:"nickname"`
}

func describe(data []byte) (string, error) {
    var patch PatchProfile
    if err := json.Unmarshal(data, &patch); err != nil {
        // 输入不是合法 JSON 时，不能把它误判成“字段缺失”。
        return "", fmt.Errorf("解析请求失败: %w", err)
    }

    if len(patch.Nickname) == 0 {
        // 空切片表示没有匹配到 nickname 字段。
        return "不修改", nil
    }
    if bytes.Equal(patch.Nickname, []byte("null")) {
        // 原始 JSON 明确是 null，和字段缺失保持不同语义。
        return "清空", nil
    }

    var nickname string
    if err := json.Unmarshal(patch.Nickname, &nickname); err != nil {
        // 字段出现但类型不符合约定时，应返回类型错误。
        return "", fmt.Errorf("nickname 类型错误: %w", err)
    }
    // 这里拿到的是具体值，后续可以交给更新逻辑。
    return "更新为 " + nickname, nil
}

func main() {
    for _, raw := range []string{`{}`, `{"nickname":null}`, `{"nickname":"阿明"}`} {
        result, err := describe([]byte(raw))
        // 示例只展示三种状态的分类结果，不代表线上接口输出。
        fmt.Println(raw, result, err)
    }
}

这里的关键不是 RawMessage 直接完成了业务更新，而是它把原始字段状态留到了业务判断层。只有确认不是缺失、也不是 null 后，才把字节解码为字符串、整数或嵌套结构。

把三种状态映射到部分更新

在 PATCH 类接口中，可以把判断结果固定映射成三种动作：字段缺失时跳过赋值，显式 null 时清空存量数据，具体 JSON 值则先解码并执行更新。这样业务规则不会依赖字符串的零值。

type UserPatch struct {
    DisplayName json.RawMessage `json:"display_name"`
}

func applyDisplayName(user *User, raw json.RawMessage) error {
    if len(raw) == 0 {
        // 字段缺失：保留数据库中的原值，不执行更新。
        return nil
    }
    if bytes.Equal(raw, []byte("null")) {
        // 显式 null：按接口约定清空可空字段。
        user.DisplayName = nil
        return nil
    }

    var value string
    if err := json.Unmarshal(raw, &value); err != nil {
        // 具体值仍需经过类型解码，避免把数字或对象强行转成字符串。
        return fmt.Errorf("display_name 类型错误: %w", err)
    }
    // 有值输入：只有成功解码后才覆盖原值。
    user.DisplayName = &value
    return nil
}

上例中的 User 只是业务对象示意，重点在于更新动作由三种输入状态驱动。不要把 null 当作空字符串，也不要把缺失字段当作“把数据库列更新为空”。如果接口有审计或权限逻辑，也应在这一步之前明确记录调用方的意图。

处理复用结构体和非法 JSON

json.Unmarshal 会把输入字段合并到目标值中，因此长期复用同一个结构体时，旧的 RawMessage 可能影响下一次判断。最简单的方式是每次请求创建新的请求对象；如果必须复用，就在解码前清空字段。

var patch UserPatch
patch.DisplayName = nil
if err := json.Unmarshal(body, &patch); err != nil {
    // 解码失败要直接返回，不能把半成品当成合法的部分更新。
    return err
}

还要注意，RawMessage 只解决字段原文保留，不会自动完成业务校验。字符串长度、允许的空值、嵌套对象字段以及字段之间的互斥关系，仍然需要在解码后由业务代码判断。若字段结构非常复杂，可以为请求类型实现自定义 UnmarshalJSON，但仍建议保留清晰的三态语义。

迁移时怎么选类型

如果只需要判断一个字段是否出现，指针或 map 可能已经足够；如果接口要支持“忽略、清空、设置”三种 PATCH 语义，RawMessage 更容易把协议表达完整。

总结

json.RawMessage 的价值是延后具体类型解码，同时保留字段对应的原始 JSON。字段缺失时检查 len(raw) == 0，显式 null 时比较 []byte("null")，其他内容再解码成目标类型。迁移部分更新接口时，把三种状态分别对应不修改、清空和更新，就能避免普通指针带来的语义丢失。

相关问题

为什么不用 *string 区分缺失和 null？ 因为两者在不少结构体解码场景都会表现为 nil，无法继续判断字段是否真的出现在 JSON 中。

RawMessage 能代替 JSON Schema 校验吗？ 不能。它只保留原始值，类型、范围和字段关系仍需要业务代码或专门的校验层处理。