Go RawMessage 怎样延迟解析联合字段

当一个 JSON 对象的 payload 会因为 type 不同而拥有不同字段时，不要一开始就把它解码成 map[string]any。更稳妥的做法是先用 json.RawMessage 保存这段原始 JSON，读取公共的 type 后再把它解码到对应的 Go 结构体。这就是 RawMessage 延迟解析联合字段的核心。

官方文档：https://pkg.go.dev/encoding/json

RawMessage 适合“先判断类型、后决定目标结构”的协议。第一阶段只负责分派，第二阶段才负责字段解析；未知类型和坏载荷都要显式返回错误。

• 公共字段：放在外层结构中，例如 type。
• 变化字段：使用 json.RawMessage 暂存，例如 payload。
• 分派规则：用明确的 switch 或注册表把类型映射到目标结构。
• 错误边界：未知 type、缺少载荷和二次解码失败都不能静默忽略。

为什么要把联合字段拆成两次解析

JSON 本身没有 Go 里的接口实现或泛型类型信息。假设同一个接口返回图片颜色数据，type 为 RGB 时载荷有 r、g、b，为 YCbCr 时又换成 y、cb、cr。如果直接把载荷接到一个固定结构体上，就会在还不知道分支的情况下丢失模型边界。

两次解析把责任分开：第一次只读取稳定的路由字段；第二次只处理已经选定的载荷类型。这样既不需要把所有字段塞进一个“大而全”的结构体，也不必让调用方到处做类型断言。

先用 RawMessage 保留未决定形状的 payload

外层结构只描述所有分支都共有的部分。RawMessage 的底层形式是原始 JSON 值，它实现了 JSON 的编解码接口，可以把解析动作推迟到真正知道目标类型之后。

package main

import "encoding/json"

// Envelope 只保存所有联合分支都共有的路由字段和原始载荷。
type Envelope struct {
	Type    string          `json:"type"`
	Payload json.RawMessage `json:"payload"`
}

// RGB 与 YCbCr 是两个形状不同的载荷目标。
type RGB struct {
	R uint8 `json:"r"`
	G uint8 `json:"g"`
	B uint8 `json:"b"`
}

type YCbCr struct {
	Y  uint8 `json:"y"`
	Cb int8  `json:"cb"`
	Cr int8  `json:"cr"`
}

第一阶段执行 json.Unmarshal 时，Type 会被解析成字符串，Payload 则仍保留为可再次交给 JSON 解码器的原始值。这里的重点不是绕开解析，而是把解析时机推迟到路由信息已经明确之后。

第一次解码只做路由判断

分派函数可以先解析外层信封，再根据 Type 选择后续目标。示例返回 any，调用方也可以把它替换为项目自己的接口或结果包装类型。

package main

import (
	"encoding/json"
	"fmt"
)

// DecodePayload 只让 type 决定目标类型，不根据 payload 的偶然字段猜测。
func DecodePayload(data []byte) (any, error) {
	var envelope Envelope
	if err := json.Unmarshal(data, &envelope); err != nil {
		return nil, fmt.Errorf("decode envelope: %w", err)
	}

	// 空 RawMessage 通常意味着输入没有提供 payload，先给出明确错误。
	if len(envelope.Payload) == 0 {
		return nil, fmt.Errorf("type %q has no payload", envelope.Type)
	}

	switch envelope.Type {
	case "RGB":
		var value RGB
		if err := json.Unmarshal(envelope.Payload, &value); err != nil {
			return nil, fmt.Errorf("decode RGB payload: %w", err)
		}
		return value, nil
	case "YCbCr":
		var value YCbCr
		if err := json.Unmarshal(envelope.Payload, &value); err != nil {
			return nil, fmt.Errorf("decode YCbCr payload: %w", err)
		}
		return value, nil
	default:
		// 未知分支显式失败，避免调用方误把结果当成已支持类型。
		return nil, fmt.Errorf("unsupported payload type %q", envelope.Type)
	}
}

这段代码有三个重要判断。外层 JSON 解析失败时，错误说明是信封坏了；载荷为空时，错误说明是输入不完整；类型不在支持列表时，错误说明是协议扩展尚未接入。错误信息带上阶段和类型，调用方排查日志时不必猜测失败发生在哪里。

第二次解码到具体载荷

真正的载荷解码发生在 switch 的分支内部。此时目标结构体已经确定，字段拥有明确的 Go 类型，后续代码可以直接使用返回值，不需要从 map[string]any 中逐个断言。

package main

import (
	"encoding/json"
	"fmt"
)

func main() {
	inputs := [][]byte{
		[]byte(`{"type":"RGB","payload":{"r":98,"g":218,"b":255}}`),
		[]byte(`{"type":"YCbCr","payload":{"y":255,"cb":0,"cr":-10}}`),
	}

	for _, input := range inputs {
		value, err := DecodePayload(input)
		if err != nil {
			// 单条消息失败就记录上下文；批处理是否继续由上层决定。
			fmt.Println("decode failed:", err)
			continue
		}
		fmt.Printf("decoded as %T: %+v\n", value, value)
	}
}

输出的具体类型会分别是 main.RGB 和 main.YCbCr。这说明分派发生在 JSON 解析之后、业务处理之前，后续逻辑可以围绕明确的结构体组织，而不是让每个使用点重复判断字段。

未知类型和坏载荷要怎样处理

联合协议最容易出问题的地方不是 RawMessage 本身，而是分派表与服务端协议没有同步。建议把以下情况分开处理：

如果业务必须兼容未来类型，可以把未知分支封装为“暂存待转发”的结果，但仍要明确标记它没有完成业务解析。不要在默认分支里返回空结构体，因为那会把协议不兼容伪装成成功。

什么时候适合使用 RawMessage

当联合字段的分支确实具有不同 JSON 形状，并且路由字段先于业务字段出现或至少能独立读取时，RawMessage 很合适。它能让分派规则集中在一个位置，也能让每个分支保留自己的强类型结构。

如果所有输入的字段完全相同，只是某个值在数字与字符串之间变化，或只是部分字段可选，优先考虑自定义 UnmarshalJSON、明确的兼容类型或普通指针字段，不要为了使用 RawMessage 而强行做两次解析。两阶段结构会增加一处错误处理和一次载荷解码，只有在协议形状真正分叉时才值得承担。

常见问题

RawMessage 会不会让 payload 完全不解析？

不会。它只是把解析时间推迟，最终仍应把原始值交给 json.Unmarshal 或其他明确的解码逻辑。

能不能不读取 type，直接尝试多个结构体？

不建议把“依次尝试”当成路由。多个结构体可能都能接收部分字段，最后得到一个看似成功但语义错误的零值对象。协议已有判别字段时，应优先使用它。

为什么不直接使用 map[string]any？

通用 map 适合临时探查，但业务代码需要反复做类型断言，并且数字默认可能落到浮点表示。按 type 分派到结构体后，字段边界和错误更清晰。

分支很多时是否还要写很长的 switch？

分支较少时 switch 最直观；分支增多后可以把类型名映射到构造函数或解码器，但仍应保留未知类型错误、二次解码错误和统一的上下文包装。