Go encoding/json RawMessage 如何延迟解析联合字段

接口返回的 payload 有时不是一种固定结构：kind=user.created 对应用户对象，kind=order.paid 又对应订单对象。如果一开始就把它解成 map[string]any，后续代码会充满类型断言；如果直接解成某个结构体，又会把另一种分支的字段丢掉。

更稳的做法是让外层结构体只接收稳定字段，把联合字段声明为 json.RawMessage。先判断 kind，再把 payload 延迟解码到对应的具体类型。这样既保留了输入边界，也让每个分支拥有清晰的 Go 类型。

先读取外层字段，再延迟解析 payload

先定义一个只描述公共字段的信封。Payload 不急着绑定成某个业务结构，RawMessage 会保留它的原始 JSON 字节，之后可以重复交给 json.Unmarshal：

package event

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

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

type UserCreated struct {
	ID   string `json:"id"`
	Email string `json:"email"`
}

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

func DecodeEvent(data []byte) (any, error) {
	var env Envelope
	// 第一阶段只读公共字段，暂时不决定 payload 的具体类型。
	if err := json.Unmarshal(data, &env); err != nil {
		return nil, fmt.Errorf("解析事件外层失败: %w", err)
	}
	trimmed := bytes.TrimSpace(env.Payload)
	// 联合字段必须有内容，null 不能悄悄变成一个零值结构体。
	if len(trimmed) == 0 || bytes.Equal(trimmed, []byte("null")) {
		return nil, fmt.Errorf("事件 %q 缺少 payload", env.Kind)
	}

	switch env.Kind {
	case "user.created":
		var value UserCreated
		// 第二阶段才按 kind 选择目标结构体。
		if err := json.Unmarshal(env.Payload, &value); err != nil {
			return nil, fmt.Errorf("user.created payload 无效: %w", err)
		}
		return value, nil
	case "order.paid":
		var value OrderPaid
		// 每个分支都保留自己的字段校验和错误上下文。
		if err := json.Unmarshal(env.Payload, &value); err != nil {
			return nil, fmt.Errorf("order.paid payload 无效: %w", err)
		}
		return value, nil
	default:
		// 未登记的联合类型不能静默落到 map 或空结构体。
		return nil, fmt.Errorf("未知事件类型: %s", env.Kind)
	}
}

这个函数把解析分成两道边界：第一道只确认外层 JSON 合法并取出 Kind，第二道才处理具体业务对象。新增事件类型时，只需要新增结构体和一个分支；如果服务端发来未知 kind，调用方还能保留错误上下文，而不是得到一个看似成功的零值。

把联合字段的未知分支挡在边界外

RawMessage 只负责保存一段原始 JSON，不会替你判断 kind 的业务含义。排查时可以按这张表区分错误来源：

特别容易忽略的是未知字段。标准库默认会忽略目标结构体中不存在的 JSON 字段，所以“解析成功”只说明已知字段能转换，不说明协议完全匹配。若某个分支对输入非常敏感，可以在该分支使用 json.Decoder 和 DisallowUnknownFields 做更严格的兼容策略；不要把所有接口都默认设成严格模式，先确认服务端确实承诺字段不会扩展。

利用 RawMessage 的复制语义保护延迟解析

标准库的 (*RawMessage).UnmarshalJSON 会把输入复制到消息字段中，因此外层解析结束后，延迟解析仍然有自己的字节数据。可以在真正进入业务分支前做一个轻量的 JSON 合法性检查：

func decodePayload(raw json.RawMessage, out any) error {
	// 先检查原始子值，避免把损坏的 payload 交给业务层。
	if !json.Valid(raw) {
		return fmt.Errorf("payload 不是合法 JSON")
	}
	// out 必须是具体结构体指针，例如 &UserCreated{}。
	if err := json.Unmarshal(raw, out); err != nil {
		return fmt.Errorf("payload 字段类型不匹配: %w", err)
	}
	return nil
}

这里的检查不是为了重复解析，而是为了把“原始子值损坏”和“目标结构体字段不匹配”区分开。实际项目还应在每个具体类型上补业务必填字段校验，例如检查用户 ID 是否为空、订单金额是否允许为零。

常见问题

RawMessage 和 map[string]any 应该怎么选？

字段结构已经由 kind 决定时，优先用 RawMessage 延迟解析到具体结构体；只有结构完全开放、无法建立稳定类型时，才考虑 map[string]any。

payload 缺字段时 Unmarshal 会报错吗？

普通结构体字段缺失通常不会报错，而是保留零值。因此必填字段必须在分支解析后单独校验，不能只看 json.Unmarshal 的返回值。

为什么不直接把整个 JSON 解到 interface{}？

这样会把对象变成 map[string]any，数字还可能落成 float64，类型和校验都要后移。联合字段有稳定判别字段时，RawMessage 更容易保持边界。