Go HTTP PATCH 怎么区分字段缺失和显式置空：指针字段、null 语义与兼容返回

订单编辑场景下，用户主动清空备注和完全没碰备注两个操作，传到服务端不该当成同一种逻辑处理。针对 Go 写的 HTTP PATCH 接口来说，字段缺失、字段值为 null、字段传入新有效值，至少对应三种语义；要是直接把请求体解码到普通值类型结构体里，前两种情况很容易被统一转成零值，后续服务端完全分不清用户真实意图。

先把 PATCH 的三种输入状态分开

假设订单有 remark 和 receiver_phone 两个可编辑字段，下面三段不同请求的含义完全不一样：

{"remark":"放在前台"}
{"remark":null}
{}

第一种是设置新备注，第二种是明确清空备注，第三种是完全不改动备注。用普通字段做接收结构体时，请求里没出现的字符串会直接落成 ""；如果字段类型再加了 omitempty 标签，返回 JSON 时又可能把合法的空值给隐藏掉。接口契约最好先整理成一张对照表：

用指针字段承接“缺失”和“有值”

只需要区分“不修改该字段”和“把字段改成某个值”两种场景时，指针字段是成本最低的可用方案。指针非 nil 就代表该字段在请求里出现了，哪怕指针指向的是空字符串，也仍然是一次明确的更新操作。

type PatchOrder struct {
    Remark        *string `json:"remark"`
    ReceiverPhone *string `json:"receiver_phone"`
}

func applyPatch(old Order, p PatchOrder) (Order, error) {
    next := old
    if p.Remark != nil {
        if len([]rune(*p.Remark)) > 200 {
            return Order{}, errors.New("remark too long")
        }
        next.Remark = *p.Remark
    }
    if p.ReceiverPhone != nil {
        if !validPhone(*p.ReceiverPhone) {
            return Order{}, errors.New("invalid receiver_phone")
        }
        next.ReceiverPhone = *p.ReceiverPhone
    }
    return next, nil
}

这个写法适合“空字符串本身也是合法值”的字段，但它没法单独区分 JSON 里的 null 和空字符串：两种情况最终都会落到非 nil 的指针上，只是后者指向空字符串而已。如果数据库允许对应列存 NULL，接口还得把 null 语义单独拆解出来。

需要保留 null 语义时检查 json.RawMessage

更稳妥的做法是先把请求体读成 map[string]json.RawMessage，通过 key 是否存在判断字段有没有缺失，再用原始字节内容识别是不是 null。这样字段本身的语义完全由请求内容决定，不会被结构体的默认零值覆盖替换。

func parsePatch(body []byte) (map[string]json.RawMessage, error) {
    var fields map[string]json.RawMessage
    dec := json.NewDecoder(bytes.NewReader(body))
    dec.DisallowUnknownFields()
    if err := dec.Decode(&fields); err != nil {
        return nil, err
    }
    if fields == nil {
        return nil, errors.New("patch body must be an object")
    }
    return fields, nil
}

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

落库之前再逐个字段做类型校验。比如 remark 出现 null 就走清空分支，出现字符串就跑长度、格式校验；空字符串是不是允许作为有效值，要在这个分支里明确判断，拒绝不合规的输入或者直接放行。

1. 先检查字段名是否在允许集合里，未知字段直接返回 400。
2. 再判断原始值是否为 null，决定清空还是继续解码。
3. 最后把值解码到目标类型，并校验长度、格式和业务状态。

错误模型和返回体要让调用方能顺畅处理

部分字段更新失败的时候，不要只返回一串难以定位原因的笼统提示。状态码、错误字段名和可读描述要保持稳定规范，前端才能直接把错误提示贴到对应的输入框边上。

type FieldError struct {
    Field   string `json:"field"`
    Message string `json:"message"`
}

type ErrorResponse struct {
    Code   string       `json:"code"`
    Errors []FieldError `json:"errors,omitempty"`
}

请求格式错误、字段类型不匹配这类场景返回 400；资源不存在返回 404；版本冲突返回 409。接口处理成功后直接返回更新完成的完整订单数据，不要只返回一个 {"ok":true}，这样调用方可以直接用服务端的最终值替换本地缓存的旧对象。

兼容旧客户端：先约定字段规则，再逐步收紧校验

旧版本客户端可能把“清空备注”的操作直接发成空字符串，只有新版本客户端才会正确传入 null。服务端可以短时间内同时兼容两种写法，把它们映射到同一个内部处理逻辑，同时在接口文档里标注迁移的时间边界。不要偷偷把空字符串当成字段缺失处理，不然用户点保存后看似操作成功，旧值其实完全没变化。

如果更新操作涉及库存、订单状态或者金额这类敏感数据，建议请求里额外携带资源版本号：

type PatchOrderRequest struct {
    Version int64 `json:"version"`
    Fields  map[string]json.RawMessage
}

更新 SQL 可以把 version 加到查询条件里，执行后影响行数为 0 就直接返回 409。这样两个用户同时编辑同一条订单时，后提交的用户不会毫无感知地覆盖掉前一个人的修改内容。

用几组小测试覆盖真实的接口边界场景

别只测试“传入一个新字符串”的正常场景，下面几组不同的请求都要分别校验数据库存储结果和 HTTP 返回状态：

• {}：原值不变。
• {"remark":null}：可空列被清除。
• {"remark":""}：按契约接受或返回字段错误。
• {"remark":123}：返回 400，且错误指向 remark。
• 旧版本号更新：返回 409，不产生部分写入。

这几条测试通过后，再接数据库事务和审计日志。接口层已经把状态拆清楚，存储层只需要执行明确的“保持、清空、写入”动作。

常见问题

PATCH 一定要使用指针字段吗？

不一定。只区分缺失和有值时，指针字段足够；需要区分缺失、null 和具体值时，使用原始 JSON 或三态类型更稳妥。

为什么不直接用 PUT？

PUT 更适合提交完整资源。只改订单备注这类局部场景用 PATCH，可以避免客户端为了保留未改字段而重复发送整份资源。

成功返回只给 200 和 ok 字段可以吗？

能用，但不利于处理服务端规范化、默认值和并发版本。返回最终资源与版本号，调用方更容易同步本地状态。

把三态语义明确写进接口契约

PATCH 接口的难点从来不是写路由分发逻辑，而是字段的三种状态有没有被准确保留下来。先明确定义字段缺失、null、空字符串各自代表的业务含义，再选择指针字段方案或者 json.RawMessage 方案；补全未知字段拦截、类型错误校验和版本冲突相关的测试，接口在客户端逐步升级的过程中，就不会出现“返回操作成功但数据完全没按预期变更”的奇怪问题。