Go json.RawMessage按字段类型分流的解析方案

同一个 Go 接口如果会返回订单、支付、库存等多种事件，直接把 payload 解码成 map[string]any 很快就会失去字段类型；直接绑定某一个结构体，又会让其他事件不断报错。更稳的做法是保留一个公共信封：先解析 kind 等公共字段，把动态部分放进 json.RawMessage，确认类型后再进行第二次解码。

公共字段和动态 payload 先拆成两层

先定义事件信封，只让第一轮 Unmarshal 负责公共字段和原始载荷。RawMessage 本质上是一段原始 JSON 值，适合把解码时机推迟到已经知道 Kind 之后。

package event

import (
    "encoding/json"
    "fmt"
)

// EventEnvelope 只描述所有事件都共有的字段。
type EventEnvelope struct {
    ID      string          `json:"id"`
    Kind    string          `json:"kind"`
    Version int             `json:"version"`
    Payload json.RawMessage `json:"payload"`
}

// decodeEnvelope 先拆公共字段，避免把动态载荷误解码成固定类型。
func decodeEnvelope(data []byte) (EventEnvelope, error) {
    var env EventEnvelope
    if err := json.Unmarshal(data, &env); err != nil {
        return EventEnvelope{}, fmt.Errorf("解析事件信封失败: %w", err)
    }
    if env.Kind == "" {
        return EventEnvelope{}, fmt.Errorf("事件缺少 kind")
    }
    if len(env.Payload) == 0 || string(env.Payload) == "null" {
        return EventEnvelope{}, fmt.Errorf("事件 %q 缺少 payload", env.Kind)
    }
    return env, nil
}

这里的边界很重要：第一轮只负责 JSON 语法和公共字段，不能因为暂时不认识某种 payload 就把整条消息当成无效。缺少 kind 或载荷时则应尽早返回，因为后续没有可靠的分流依据。

用 Kind 建立集中式类型分流表

不要让每个调用方各自判断字符串。把 Kind 到具体对象的选择集中在一个函数里，新增事件时只增加一个分支和对应结构体，错误也能统一包装。

// 订单创建事件的业务载荷。
type OrderCreated struct {
    OrderID string `json:"order_id"`
    Amount  int64  `json:"amount"`
}

// PaymentReceived 表示支付回执载荷。
type PaymentReceived struct {
    PaymentID string `json:"payment_id"`
    Success   bool   `json:"success"`
}

// DecodePayload 根据 Kind 选择目标类型，再做第二次解码。
func DecodePayload(data []byte) (any, error) {
    env, err := decodeEnvelope(data)
    if err != nil {
        return nil, err
    }

    var target any
    switch env.Kind {
    case "order.created":
        target = new(OrderCreated)
    case "payment.received":
        target = new(PaymentReceived)
    default:
        // 未知类型显式报错，避免把新事件静默当成旧事件。
        return nil, fmt.Errorf("不支持的事件类型: %s", env.Kind)
    }

    // 第二次解码只处理已经选定的业务载荷。
    if err := json.Unmarshal(env.Payload, target); err != nil {
        return nil, fmt.Errorf("解析 %s payload 失败: %w", env.Kind, err)
    }
    return target, nil
}

返回值使用 any 是为了保留不同 DTO 的类型；如果调用方需要更强约束，可以进一步返回带有 Kind 的接口，或在业务层把结果转换为统一命令。关键是不要把错误吞掉：未知 Kind 和字段类型不匹配应当让上层决定记录、重试还是兼容。

兼容新事件时保留清晰的错误边界

协议演进时，新事件可能先到达旧消费者。旧消费者不认识它并不等于 JSON 损坏，因此未知类型最好使用可观测的业务错误，让消息系统或调用方选择隔离、重试或升级。对于同一 Kind 的字段新增，Go 结构体通常可以自然忽略未知字段；但如果字段类型改变，就应通过 Version 或新的 Kind 明确区分，避免把兼容问题隐藏在宽松解析里。

如果载荷很大，RawMessage 只解决“何时解码”的组织问题，不会让载荷凭空消失；真正需要降低内存峰值时，要再考虑流式读取、消息大小限制和超时策略。测试时至少覆盖：已知类型、未知类型、缺失载荷、null、字段类型错误和新增字段。

常见问题

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

它适合临时探查，但数字、嵌套对象和可选字段的类型边界需要调用方重复判断。RawMessage 配合具体 DTO 能把类型错误集中在第二次解码处。

RawMessage 能判断 payload 的业务类型吗？

不能。它保留原始 JSON，业务类型仍应由可信的 Kind、版本字段或协议规则决定。

新增字段会不会让旧消费者失败？

对同一结构体新增未知字段通常可以继续解析；如果改变已有字段类型或语义，应升级版本或拆出新的 Kind，并保留可观测的兼容路径。