Go JSON PATCH 如何区分字段缺失与显式 null：指针、RawMessage 与参数语义

做用户资料的PATCH更新的时候，前端不传 nickname，和明确传入 "nickname": null，实际代表的是完全不同的两种逻辑：前者是不需要修改该字段，后者往往是要把对应字段清空。Go里如果直接把JSON解码到普通结构体，这两种请求最后得到的都是一样的零值，接口根本没办法准确识别调用方的真实意图。

PATCH参数需要同时覆盖三种状态：字段压根没出现在请求里、字段显式传了null、字段传了合法有效值。普通可选字段直接用指针实现就足够应对大部分场景；如果要更细粒度区分不同JSON形态，再把对应字段保留为 json.RawMessage 原始结构即可。

普通结构体为什么会吞掉PATCH的字段语义

先看很多人随手就写出来的参数结构：

type ProfilePatch struct {
    Nickname string `json:"nickname"`
    Age      int    `json:"age"`
}

当请求体分别是 {}、{"nickname":""} 和 {"nickname":null} 的时候，Nickname 最后解析出来都可能是空字符串。结构体只存了解码后的结果，完全没留下「这个键到底有没有出现在请求里」的证据。

这个问题会直接影响后续的更新语句。如果业务代码判断字段是空字符串就执行清空，那只想改年龄的请求也可能把原本正常的昵称给覆盖清空；如果业务代码直接忽略所有空字符串，又没法支持用户主动清空昵称的需求。没必要直接往SQL层堆一堆if判断，参数模型本身就应该把调用方的需求先表达完整。

只需要三种状态时，用指针表达更新意图

面对「保持原值不动」和「写入指定新值」这类常见场景，指针结构用起来最省心：

type ProfilePatch struct {
    Nickname *string `json:"nickname"`
    Age      *int    `json:"age"`
}

解码完成后，字段缺失和显式传 null 得到的都是nil，而正常非空字符串会得到一个非nil的指针。这样就能稳定实现「只更新请求里出现过且带有效值的字段」的逻辑：

var patch ProfilePatch
if err := json.NewDecoder(r.Body).Decode(&patch); err != nil {
    return badRequest("JSON 格式不正确")
}

if patch.Nickname != nil {
    updateNickname(*patch.Nickname)
}
if patch.Age != nil {
    if *patch.Age  150 {
        return badRequest("age 超出范围")
    }
    updateAge(*patch.Age)
}

这种方案很适合「null也按不更新处理」的接口约定。但如果产品逻辑要求传null就清空数据库字段，纯指针的方案就不够用了：nil根本没法区分你是「压根没传这个字段」还是「专门传了null」。

需要区分null时，把原始JSON留在参数层

json.RawMessage 可以完整保存字段对应的原始JSON字节，你可以先判断字段有没有出现，再判断它是不是null，最后再按对应业务类型做解码：

type ProfilePatch struct {
    Nickname json.RawMessage `json:"nickname"`
    Age      json.RawMessage `json:"age"`
}

func hasValue(raw json.RawMessage) bool {
    return len(raw) > 0
}

func isNull(raw json.RawMessage) bool {
    return bytes.Equal(bytes.TrimSpace(raw), []byte("null"))
}

这里有个很实用的细节：缺失字段对应的RawMessage切片长度是0，显式传 null 的长度会大于0。别只直接写 raw != nil 做判断，因为空切片的解码行为很容易让后续看代码的人产生误判，用长度校验加去空白检查的写法会更直观。

字段级解析可以把三种情况完全拆开：

func parseNullableString(raw json.RawMessage) (value string, present bool, clear bool, err error) {
    if !hasValue(raw) {
        return "", false, false, nil
    }
    if isNull(raw) {
        return "", true, true, nil
    }
    if err := json.Unmarshal(raw, &value); err != nil {
        return "", true, false, fmt.Errorf("nickname 必须是字符串或 null")
    }
    return value, true, false, nil
}

之后直接转成明确的更新动作，不用让底层存储层去猜用户意图：

value, present, clear, err := parseNullableString(patch.Nickname)
if err != nil {
    return badRequest(err.Error())
}
switch {
case !present:
    // 保持原值
case clear:
    clearNickname()
default:
    updateNickname(value)
}

参数设计还要回答哪些调用方问题

API契约不能只笼统写「字段可选」，调用方至少要明确知道三件事：

• 字段不传的时候是否保留数据库原值；
• 显式传null是清空字段、直接拒绝请求，还是等同于字段缺失；
• 空字符串、0、false这类零值算不算合法的新值。

如果数据库列允许存NULL，你可以在接口文档里明确说明用 null 来清空字段；如果数据库列根本不允许NULL，就应该在参数层直接返回400错误，别等到执行SQL的时候才抛错。对年龄这类数值字段，0 本身就是合法的真实值，不能用除了指针是否为nil之外的「零值判断」逻辑替代业务校验。

更新多个字段的时候，建议先生成一个内部专用的变更对象，比如 NicknameAction 只有 Keep、Set、Clear 这三种动作。之后不管是调HTTP接口、发消息队列还是后台跑任务，存储层收到的都是统一语义的变更，不用重复实现一遍JSON解析逻辑。

错误处理和兼容策略怎么定

客户端传了数组、对象或者和定义类型不匹配的数字时，服务端要返回明确带字段名的400响应，比如提示「nickname 必须是字符串或null」。别直接把非法类型静默转成空字符串，也不要出现一部分字段已经更新成功了，才发现另一部分字段是非法的情况。

更稳妥的处理顺序是：先把所有字段全部解码完成，做完类型和范围校验，得到合法的变更对象之后，再放到同一个数据库事务里执行写入。新字段刚上线的时候，可以先约定不传就保留原值；等所有客户端都升级完，再考虑要不要开放用null清空字段的能力。旧客户端只发自己已经有的字段，不会因为服务端新增了可选字段就意外改掉原有数据。

回归测试至少要覆盖这些请求场景：

• {}：不做任何字段变更；
• {"nickname":"小周"}：正常设置新昵称；
• {"nickname":""}：设置为空字符串，按照接口契约判断是否允许该操作；
• {"nickname":null}：清空字段或者直接返回400错误；
• {"nickname":12}：直接返回类型错误提示，数据库不能写入任何变更。

一个可落地的选择结论

如果接口只需要区分「没传这个字段」和「传了有效值」两种状态，优先用指针字段就好，代码简洁，Go的类型检查也能自然覆盖所有场景。如果接口必须支持主动清空、保留默认值、区分空数组和字段缺失这类更细的能力，就用 json.RawMessage 或者自定义带状态的类型，把三态转换的逻辑全部集中在参数层处理。

最终验收不能只看接口返回了HTTP 200。每发一组回归测试请求，都要同时核对响应JSON、数据库列值和审计日志里记录的变更动作；尤其要确认传非法类型的请求之后，数据库里没有留下半条不完整的更新记录。

相关问题

PATCH接口能不能直接复用PUT的结构体？

可以复用字段定义，但不能直接默认复用「全量替换」的语义。PATCH要保留字段是否缺失的信息，不然原本的可选字段很容易被误覆盖。

为什么不直接用map[string]any判断字段是否存在？

它确实能判断键有没有出现在请求里，但类型断言和数字默认转float64的问题会把校验逻辑散落到代码各处。字段少且迭代快的场景可以临时用，长期维护的公开接口更适合用RawMessage或者自定义参数类型来实现。

显式null是不是一定代表删除？

不一定。null的具体含义属于接口契约的一部分，你可以把它定义成清空字段、直接拒绝请求或者等同于字段缺失，但一定要在接口文档和测试用例里把这个逻辑固定下来，别前后实现不一致。

小结

PATCH接口的难点从来不是JSON解码本身，而是怎么把调用方的真实意图完整传递到最终更新层。指针可以搞定大部分普通的可选字段场景，RawMessage可以处理字段缺失、null和具体值的细分语义；再配合字段级校验、事务写入和完整的回归用例，接口的行为不管是新读者还是后续维护者，都能准确理解和验证。