Go json.UnmarshalJSON RawMessage 适合延迟解析哪些字段

如果一批 JSON 事件只有 id、kind 等外层字段稳定，而 payload 会随事件类型变化，直接把它解码成 map[string]any 往往会丢失类型约束。更合适的做法是给 payload 使用 json.RawMessage：第一次 json.Unmarshal 只读取外层结构，确认 kind 后，再把原始 JSON 解码到对应的 Go 结构体。

RawMessage 保留了什么：外层字段与原始 JSON 的分界

json.RawMessage 本质上是原始编码后的 JSON 值，并实现了 Marshaler 和 Unmarshaler。在标准库的行为里，反序列化到 RawMessage 时会复制输入字节，因此外层解码结束后，字段仍可独立用于第二次解析。

这使它特别适合下面这种消息：公共字段负责定位，payload 只在确定类型后才需要理解。第一层不必猜测每种事件的全部字段，也不必把数字、数组和对象都降级成空接口。

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

func decodeEnvelope(data []byte) (Envelope, error) {
	var env Envelope
	// 第一层只负责校验 JSON 并读取稳定的路由字段。
	if err := json.Unmarshal(data, &env); err != nil {
		return Envelope{}, fmt.Errorf("decode envelope: %w", err)
	}
	return env, nil
}

这里的边界很重要：RawMessage 不是字符串，也不是“跳过 JSON 校验”的开关。外层 JSON 语法错误会在第一次解码时暴露；只有 payload 对应的 Go 类型映射被推迟。

先读 kind，再把 payload 解码到具体结构

延迟解析最常见的收益来自“先路由、后建模”。例如支付事件和库存事件的 payload 结构完全不同，就不要先解析成通用 map。让 switch 只负责选择目标类型，具体结构的错误仍然从二次 json.Unmarshal 返回。

type Payment struct {
	Amount int64  `json:"amount"`
	State  string `json:"state"`
}

type StockChange struct {
	SKU   string `json:"sku"`
	Delta int    `json:"delta"`
}

func decodePayload(env Envelope) (any, error) {
	var dst any
	// 路由字段决定目标类型，避免把所有分支压成 map[string]any。
	switch env.Kind {
	case "payment.updated":
		dst = new(Payment)
	case "stock.changed":
		dst = new(StockChange)
	default:
		return nil, fmt.Errorf("unsupported event kind %q", env.Kind)
	}
	// 二次解析只处理选中的 payload，并保留类型错误。
	if len(env.Payload) == 0 || bytes.Equal(env.Payload, []byte("null")) {
		return nil, errors.New("payload is empty")
	}
	if err := json.Unmarshal(env.Payload, dst); err != nil {
		return nil, fmt.Errorf("decode %s payload: %w", env.Kind, err)
	}
	return dst, nil
}

生产代码里还可以把未知 kind 记录为可观测事件，或把原始 payload 放入死信队列，但不要把未知类型静默当成成功。这样才能区分“消息格式合法但业务版本未知”和“payload 字段类型错误”两类问题。

哪些字段适合延迟解析，哪些字段不值得这么做

还要注意内存生命周期：RawMessage 保存的是一份字节副本，适合短期路由和审计留存，但不应因为“延迟解析”就无限期缓存不受限的 payload。对外部输入仍应限制消息大小、允许的 kind 和单个分支的字段范围。

常见问题

RawMessage 和 map[string]any 有什么区别？

RawMessage 保留 JSON 字节，类型决定后可以再映射到结构体；map[string]any 已经把值降级为运行时类型，后续需要自己断言和检查。

第一次 Unmarshal 会不会完全跳过 payload？

不会。输入仍要是合法 JSON，RawMessage 只是把该值保留下来，推迟它与具体 Go 结构的绑定。

什么时候不该使用 RawMessage？

如果字段结构固定、每次都要访问，直接嵌套结构通常更简单。只有结构分叉、低频或需要透传时，延迟解析才值得引入。

参考资料：Go encoding/json 官方文档与标准库 RawMessage 示例，说明 RawMessage 可延迟 JSON 解码；文章示例按同一 API 语义重新组织。