Go 多态 JSON 字段反序列化类型选择

当一个 JSON 接口的 data 字段可能是用户事件、订单事件或其他对象时，直接把它声明成 any 往往会丢掉类型边界：数字会落成 float64，后续还要靠断言补救。更稳妥的做法是先读取公共的判别字段，再用 json.RawMessage 延迟解析真正的 payload。

本文只讨论“判别字段 + RawMessage + 错误分类”这条边界。Go 官方 encoding/json 文档说明，RawMessage 可以延迟 JSON 解码；它本质上保存一段原始 JSON，适合等类型确定后再交给 json.Unmarshal。

官方资料：https://pkg.go.dev/encoding/json

先解外层 envelope，再根据 kind 选择具体 Go 结构，最后只对对应的 data 调用一次反序列化。缺少 kind、kind 不支持、payload 格式错误应该分别处理。

先把公共字段与多态 payload 分开

外层结构只放所有事件都拥有的字段，把变化最大的内容声明为 json.RawMessage。这样第一次解码不会猜测 data 的具体类型，也不会把它提前变成 map[string]any。

package main

import "encoding/json"

// Envelope 只描述所有事件共有的元数据和延迟解析的载荷。
type Envelope struct {
	ID   string          `json:"id"`
	Kind string          `json:"kind"`
	Data json.RawMessage `json:"data"`
}

// 两种事件各自保留自己的字段，避免调用方到处做类型断言。
type UserCreated struct {
	UserID string `json:"user_id"`
}

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

这里的关键不是把原始字节永久保留下来，而是把“选择类型”和“解析字段”拆成两个明确动作。对只读、转发或需要记录原文的场景，RawMessage 也能让外层结构先完成处理。

按 kind 选择具体结构

拿到 Envelope 后，用显式 switch 选择目标类型。每个分支都把解码错误包上当前 kind，排查日志时不用再猜是哪一种 payload 失败。

package main

import (
	"encoding/json"
	"fmt"
)

// Decode 将判别字段和具体 payload 的解析责任集中在一个边界内。
func (e Envelope) Decode() (any, error) {
	if e.Kind == "" {
		return nil, fmt.Errorf("missing event kind") // 缺少判别字段时不要猜类型
	}

	switch e.Kind {
	case "user.created":
		var v UserCreated
		if err := json.Unmarshal(e.Data, &v); err != nil {
			return nil, fmt.Errorf("decode %s: %w", e.Kind, err) // 保留底层 JSON 错误
		}
		return v, nil
	case "order.paid":
		var v OrderPaid
		if err := json.Unmarshal(e.Data, &v); err != nil {
			return nil, fmt.Errorf("decode %s: %w", e.Kind, err)
		}
		return v, nil
	default:
		return nil, fmt.Errorf("unsupported event kind %q", e.Kind) // 新类型先显式拒绝
	}
}

示例把返回值写成 any，只是为了展示类型选择点；在业务代码中也可以返回自定义接口，例如让 UserCreated 和 OrderPaid 都实现 EventPayload。重要的是，具体类型只在一个地方决定，调用方收到的是已经选择好的值或带上下文的错误。

把三类错误分开，调用方才好处理

多态字段最容易混在一起的有三类失败。第一类是 kind 缺失，说明消息契约不完整；第二类是 kind 存在但不支持，说明生产者新增了消费者尚未认识的类型；第三类是类型已知但 data 结构不符合约定，属于载荷内容错误。

// HandleEvent 只展示错误边界，真实系统可替换为日志或重试策略。
func HandleEvent(raw []byte) error {
	var e Envelope
	if err := json.Unmarshal(raw, &e); err != nil {
		return fmt.Errorf("decode envelope: %w", err) // 外层 JSON 本身不合法
	}

	payload, err := e.Decode()
	if err != nil {
		// 未知 kind 通常不能盲目重试，载荷错误则应进入坏消息处理。
		return err
	}

	_ = payload // 这里交给业务分发器处理已经确定类型的值。
	return nil
}

不要为了“兼容未知类型”把所有 data 都塞进 map[string]any。如果确实要透传未知事件，可以在错误中带上原始 Envelope，或把未识别 kind 交给独立的兼容分支；不要让已知类型也失去编译期结构。

新增类型时只扩展选择分支

当协议增加 invoice.issued 时，新增一个具体 struct 和一个 case 即可。判别字段的字符串应当来自稳定的协议约定，避免用 Go 类型名直接暴露内部重构。对必须严格校验字段的接口，可以在对应 struct 上增加自定义 UnmarshalJSON，但不要把所有事件的规则塞进一个巨大方法。

最后可以按这三点检查实现：外层是否只负责公共字段；每个 kind 是否有明确的目标类型；错误是否能区分契约缺失、类型未知和 payload 不合法。满足这三个边界，多态 JSON 就不会退化成一堆运行时断言。

常见问题

为什么不直接把 data 解成 map[string]any？

这种方式适合字段完全不稳定的临时数据，但会牺牲结构化字段、数字类型和重构提示。类型固定的事件更适合 RawMessage 加具体 struct。

RawMessage 会自动帮我选择结构吗？

不会。它只负责保存原始 JSON；类型选择仍需要判别字段、注册表或明确的分支逻辑。