Go json.RawMessage 什么时候值得用：延迟解析、字段分流与内存边界

接口同时接收订单、退款和通知三类 JSON 时，最容易写出一段难维护的代码：先把整个请求解成 map[string]any，再靠类型断言猜 payload。真正需要处理的往往只有一种事件，其他字段只是暂时放在请求里。json.RawMessage 的价值就在这里：先保留一段合法 JSON，等读出 kind 后再把 payload 解成对应结构体。

先看一个多事件请求：为什么不急着解析 payload

假设 webhook 的外层字段固定，只有 payload 随 kind 改变。订单事件带商品行，退款事件带支付流水，通知事件又是另一套字段。把它们都解析成 map[string]any，数字会落成 float64，嵌套对象也失去边界；把每一种结构都塞进一个大结构体，则会留下大量互斥字段。

外层只做路由，内层才做强类型解析，代码更容易检查失败位置：

type Envelope struct {
    ID      string          `json:"id"`
    Kind    string          `json:"kind"`
    Payload json.RawMessage `json:"payload"`
}

type OrderCreated struct {
    OrderID string `json:"order_id"`
    Amount  int64  `json:"amount"`
}

type RefundCreated struct {
    PaymentID string `json:"payment_id"`
    Reason    string `json:"reason"`
}

func route(data []byte) error {
    var env Envelope
    if err := json.Unmarshal(data, &env); err != nil {
        return fmt.Errorf("decode envelope: %w", err)
    }

    switch env.Kind {
    case "order.created":
        var event OrderCreated
        if err := json.Unmarshal(env.Payload, &event); err != nil {
            return fmt.Errorf("decode order payload: %w", err)
        }
        return handleOrder(event)
    case "refund.created":
        var event RefundCreated
        if err := json.Unmarshal(env.Payload, &event); err != nil {
            return fmt.Errorf("decode refund payload: %w", err)
        }
        return handleRefund(event)
    default:
        return fmt.Errorf("unsupported event kind %q", env.Kind)
    }
}

这里的关键不是少写一次 Unmarshal，而是把“外层路由失败”和“具体事件字段失败”分开。日志、重试和告警可以据此判断是坏 JSON、未知事件，还是某个版本的 payload 不兼容。

RawMessage 延迟了什么，又没有延迟什么

标准库把 RawMessage 定义为原始编码后的 JSON 值，并明确说明它可以延迟解码。上面的第一次 json.Unmarshal 会识别外层结构，并把 payload 保留下来；第二次解码只在命中对应 kind 时发生。

这不是“零成本引用”。在常规 encoding/json 实现中，RawMessage 是字节切片，解析时仍然需要承载 payload 的字节。若外层请求很大，先设置 HTTP 请求体上限，再决定是否把它放进事件对象：

const maxBody = 1 

在真实 HTTP handler 中，应把 http.MaxBytesReader 的第一个参数传入当前 ResponseWriter，这里把函数缩成示意代码只是为了突出“先限大小，再解析”。别把 RawMessage 当成上传限制、字段校验或权限校验。

三种场景怎么选：路由、透传还是预计算 JSON

如果每种事件都能提前确定，而且请求量不大，直接定义独立接口也很清楚。选择 RawMessage 的理由应该是“结构要延后决定”，而不是为了把所有输入都变成一段看不懂的字节。

最容易漏掉的四个检查

未知 kind 不能静默成功

上游增加新事件时，默认分支应该留下可检索的事件 ID 和 kind。若业务允许兼容发布，可以把原始 payload 放进隔离队列，但不要把它误当成已处理成功。

空 payload 与 JSON null 要单独判断

nil、空字节和文本 null 的含义并不相同。对必须有 payload 的事件，先检查长度和 string(bytes.TrimSpace(payload)) == "null"，再进入具体结构体解析。

跨协程前要明确是否复制

如果事件对象会交给异步队列，最好在队列边界复制需要长期持有的数据，并记录复制带来的成本。不要用“它只是一个切片”来掩盖所有权问题。

严格字段校验要放在具体结构体上

可以为具体事件使用 json.Decoder 和 DisallowUnknownFields，但它只约束那一次具体解码。外层路由、请求大小、签名和权限仍然要有各自的检查。

用一个小测试确认分流没有偷换类型

测试不必覆盖所有业务字段，先把路由边界锁住：订单能进订单处理器，未知 kind 返回错误，坏 payload 不会被当成外层 JSON 错误。

func TestRoute(t *testing.T) {
    data := []byte(`{"id":"evt-7","kind":"order.created","payload":{"order_id":"o-9","amount":1280}}`)
    if err := route(data); err != nil {
        t.Fatal(err)
    }
}

再补一条未知事件和一条 payload 类型错误的用例。看测试输出时，重点是错误上下文是否能指出 kind 和具体 payload，而不是只看到一条笼统的 invalid character。

相关问题

RawMessage 会不会比直接结构体更省内存？

不一定。它减少的是不必要的结构化对象和解析工作，但仍要保存原始 JSON；大 payload 仍应先限大小。

RawMessage 能不能替代 JSON Schema 校验？

不能。它只提供延迟解析的载体，字段类型、必填字段、签名和权限都要由独立校验逻辑负责。

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

临时探查或结构确实完全动态时可以用；只要事件结构稳定，优先让具体结构体承担类型检查。

把选择收束成一个判断

当外层字段稳定、payload 结构由一个明确的 kind 决定，而且只有命中事件才值得解析时，json.RawMessage 很合适。它让路由、解析、错误和版本兼容各自有了位置。若只是想逃避字段定义，或者输入可能很大却没有请求限制，换成 RawMessage 反而会把问题推迟到内存和异步边界。