Go问答：json.RawMessage怎样延迟解析不同结构的 JSON 字段怎样完成一个可复用的最小示例

当同一个 JSON 接口的 payload 会因为 kind 不同而拥有不同字段时，直接把它声明成一个固定结构体，往往会遇到字段缺失、类型不匹配或结构越来越臃肿的问题。更稳妥的做法是先解析稳定的外层信封，把可变字段交给 json.RawMessage 暂存，等确定事件类型后再解析成具体结构。

核心做法是“两次解析”：第一次只读取 kind 和原始 payload，第二次依据 kind 将 payload 解码为目标结构。RawMessage 不会替你完成类型分派，分派规则仍要由代码明确写出。

官方地址：https://pkg.go.dev/encoding/json

问题现场：一个字段为什么不能只配一个结构体

例如事件接口统一返回下面的外层格式，但 payload 会随事件类型变化：

{
  "kind": "user.created",
  "payload": {
    "id": "u-101",
    "email": "dev@example.com"
  }
}

用户创建事件可能有 id 和 email，用户删除事件则可能只有 id 和 reason。如果把 payload 直接写成 UserCreated，删除事件的字段就没有合适的位置；如果写成 map[string]any，调用方又需要自己断言字符串、数字和数组，类型安全会明显下降。

这里真正稳定的是 kind，真正变化的是 payload 的结构。先把两者拆开，后面的分派逻辑才不会被某一个具体事件绑死。

先把外层信封和可变 payload 分开

json.RawMessage 表示一段原始 JSON 值。它可以作为结构体字段接收 JSON，但不会要求你在第一次解码时就决定这段值最终对应哪个业务结构。这正是“延迟解析”的关键。

先定义一个只包含稳定字段的外层类型：

package main

import "encoding/json"

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

第一次调用 json.Unmarshal 时，Kind 会被解码成字符串，Payload 则保留为原始 JSON。此时不要急着把它强行解成某一个具体结构。

先读取 kind，再决定目标类型

延迟解析并不是自动多态。程序必须给出一张明确的“类型标识到目标结构”的映射表，最小实现可以直接使用 switch。这样未知的 kind 能尽早返回错误，而不是悄悄落到一个不匹配的结构里。

import (
    "encoding/json"
    "fmt"
)

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

type UserDeleted struct {
    ID     string `json:"id"`
    Reason string `json:"reason"`
}

// decodeEvent 根据稳定的 kind 选择 payload 的目标类型。
func decodeEvent(data []byte) (any, error) {
    var env Envelope
    if err := json.Unmarshal(data, &env); err != nil {
        // 外层 JSON 都无法读取时，不进入第二次解析。
        return nil, err
    }

    switch env.Kind {
    case "user.created":
        var event UserCreated
        // 只有确认事件类型后，才把原始 payload 解成具体结构。
        if err := json.Unmarshal(env.Payload, &event); err != nil {
            return nil, err
        }
        return event, nil
    case "user.deleted":
        var event UserDeleted
        // 删除事件使用另一套字段，避免复用错误的目标类型。
        if err := json.Unmarshal(env.Payload, &event); err != nil {
            return nil, err
        }
        return event, nil
    default:
        // 未知类型要显式失败，便于调用方记录或降级。
        return nil, fmt.Errorf("unsupported event kind %q", env.Kind)
    }
}

上面的代码还需要把 fmt 一起导入。为了突出边界，这里保留了两个目标结构：同一份外层格式可以承载不同的业务对象，但每个对象都在第二次解析时拥有自己的字段约束。

用一次可复用函数完成第二次解析

把外层解析、类型分派和第二次解码集中在一个函数里，调用方只需要关心返回的具体对象。下面是完整的最小示例，输入字符串使用普通 JSON 双引号书写，复制到 Go 文件后即可继续扩展。

package main

import (
    "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 UserDeleted struct {
    ID     string `json:"id"`
    Reason string `json:"reason"`
}

// DecodeEvent 负责统一处理外层信封和可变 payload。
func DecodeEvent(data []byte) (any, error) {
    var env Envelope
    if err := json.Unmarshal(data, &env); err != nil {
        // 外层语法错误直接返回，避免产生半成品对象。
        return nil, fmt.Errorf("decode envelope: %w", err)
    }

    switch env.Kind {
    case "user.created":
        var event UserCreated
        // kind 已明确，第二次解析使用创建事件结构。
        if err := json.Unmarshal(env.Payload, &event); err != nil {
            return nil, fmt.Errorf("decode user.created payload: %w", err)
        }
        return event, nil
    case "user.deleted":
        var event UserDeleted
        // 删除事件的 payload 使用另一套字段定义。
        if err := json.Unmarshal(env.Payload, &event); err != nil {
            return nil, fmt.Errorf("decode user.deleted payload: %w", err)
        }
        return event, nil
    default:
        // 新事件类型没有对应结构时，明确告诉调用方。
        return nil, fmt.Errorf("unsupported event kind %q", env.Kind)
    }
}

func main() {
    input := []byte("{\"kind\":\"user.created\",\"payload\":{\"id\":\"u-101\",\"email\":\"dev@example.com\"}}")

    event, err := DecodeEvent(input)
    if err != nil {
        // 真实服务中可以把错误交给日志或消息重试策略。
        fmt.Println("decode failed:", err)
        return
    }

    // 通过类型分派读取第二次解析后的具体对象。
    switch value := event.(type) {
    case UserCreated:
        fmt.Println(value.ID, value.Email)
    case UserDeleted:
        fmt.Println(value.ID, value.Reason)
    }
}

这里的 any 只出现在函数边界，用来承载两种可能的返回结构；真正读取字段时仍然通过类型分派获得明确的 UserCreated 或 UserDeleted。如果业务事件很多，可以把这段分派继续抽成注册表，但不建议一开始就引入反射。

第二次解析时，错误应该落在哪一层

排查时可以把错误分成三层。第一层是外层 JSON 语法错误，例如缺少逗号；第二层是 kind 没有在分派表中注册；第三层是 payload 结构与目标类型不匹配，例如 id 应为字符串却收到数字。三层错误的处理动作不同，不要都包装成“解析失败”。

如果字段可能缺失，还要区分“字段不存在”和“字段值为 JSON null”。外层字段缺失时，RawMessage 可能为空；值为 null 时，原始值仍然是一个合法 JSON 值。对必须存在的 payload，可以在第二次解析之前做一个轻量判断：

func requirePayload(env Envelope) error {
    if len(env.Payload) == 0 {
        // 没有 payload 通常表示字段缺失，而不是一个完整事件。
        return fmt.Errorf("payload is missing")
    }
    if !json.Valid(env.Payload) {
        // 原始值不是合法 JSON 时，不要继续猜测目标结构。
        return fmt.Errorf("payload is invalid JSON")
    }
    return nil
}

这不是业务校验的替代品。它只能说明原始片段在 JSON 语法上可读，不能保证其中具备 UserCreated 所需的全部字段，也不能验证业务规则。

怎样把结果接回调用方

调用方通常有三种选择：

• 在单个请求内立即消费对象：返回 any 并做类型分派，适合事件处理器。
• 需要统一响应：保留 Envelope，只在真正用到 payload 的分支中再次解码。
• 需要原样转发：不要第二次解码，直接使用 RawMessage 作为下游请求中的原始 JSON 值。

如果要把原始 payload 再编码进新的响应，RawMessage 适合做“保留原样”的桥接字段；如果要读取业务字段，则仍然应该解码到明确的结构体。延迟解析解决的是“何时决定类型”，不是“从此不需要类型”。

哪些场景不适合使用 RawMessage

当 JSON 结构从协议上已经固定，例如用户资料、分页结果或配置文件，直接使用普通结构体更简单，也更容易让编译器和文档工具表达字段含义。为了“看起来灵活”而给所有字段都套上 RawMessage，会把错误推迟到业务代码。

它更适合以下情况：

• 外层字段稳定，只有少数字段根据类型标识变化。
• 服务需要先读取元数据，再决定是否解析大字段。
• 网关或转发层需要暂存、检查或原样转发一段 JSON。

对于完全未知且需要动态遍历的结构，map[string]any 更直接；对于类型集合固定但事件数量很多，可以保留 RawMessage 作为入口，再通过注册表统一管理各个解码器。

常见问题

json.RawMessage 会自动根据 kind 选择结构体吗？

不会。它只保留原始 JSON 值，kind 到目标结构的映射需要由 switch、注册表或自定义解码器明确实现。

第一次 Unmarshal 后就能直接读取 payload.ID 吗？

不能。第一次解析得到的是 RawMessage，要读取具体字段必须再次解码到目标结构，或者把它交给专门的 JSON 查询层。

payload 缺失时为什么没有立即报错？

普通结构体解码默认不会替你完成所有业务必填校验。可以在第二次解析前检查 len(env.Payload)，并在目标结构生成后补充业务字段校验。

什么时候应该直接使用 map[string]any？

当结构本来就不固定、调用方需要遍历任意字段，且可以接受数字默认解码为浮点数时，map[string]any 更方便。只要结构集合可枚举，优先使用具体结构体。

总结

json.RawMessage 的价值在于把“读取外层信息”和“决定内部类型”拆成两个时机。先用稳定的 kind 做分派，再把原始 payload 解码为具体结构，最后对未知类型、空字段和类型不匹配分别返回清晰错误，就能得到一个小而可靠的多结构 JSON 入口。