Go json.RawMessage 怎样保留未知字段并二次编码

我在接一个字段会随业务类型变化的 JSON 接口时，最初把整个 payload 解成 map[string]any。这样虽然灵活，但数字类型、字段含义和二次编码都变得不稳定。后来改成 json.RawMessage：固定字段正常解码，暂时不建模的字段先保留原始 JSON，需要判断类型时再解码，最后仍能把它原样放回新的请求体。

这篇只解决一个边界：Go 怎样保留未知字段并完成二次编码。核心思路是把“接收”和“解释”拆开，RawMessage 负责保存值，具体结构体负责解释值。

先分清：RawMessage 保存的是一段 JSON 值

json.RawMessage 本质上是一段原始编码后的 JSON 值。它适合放在我们已经知道外层结构、但还不确定内层结构的字段上，例如事件消息的 payload。它不是自动把内容变成 map[string]any，也不会替我们判断字段代表哪种业务对象。

这一点很关键：如果一开始就解成 any，JSON 数字通常会落成浮点数，重新编码时还可能改变表示；如果直接保存 RawMessage，原始值会一直留到真正需要解释的那一刻。

用固定字段加 RawMessage 接住动态 payload

先定义一个外层信封，kind 用来说明 payload 的业务类型，payload 暂时只保存原始 JSON。这样外层路由逻辑不需要知道每一种 payload 的全部字段。

package main

import (
	"encoding/json"
	"fmt"
)

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

func main() {
	data := []byte(`{"id":"e-17","kind":"order","payload":{"number":"A-100","amount":88}}`)

	var envelope Envelope
	if err := json.Unmarshal(data, &envelope); err != nil {
		// 外层 JSON 非法时，后续不能把 Payload 当成可信输入。
		panic(err)
	}

	// 这里只观察外层字段，Payload 仍保持为原始 JSON 值。
	fmt.Println(envelope.ID, envelope.Kind, string(envelope.Payload))
}

外层解码成功并不代表 Payload 一定符合某个订单结构。它只是已经是合法 JSON 值；业务结构是否完整，要在知道 kind 之后单独判断。

先看 kind，再把 RawMessage 解码到具体类型

延迟解码的好处是，类型选择和字段解析在同一处完成。下面的代码只演示两个具体分支，实际项目可以把分支收敛到注册表或独立的解析函数中。

type OrderPayload struct {
	Number string `json:"number"`
	Amount int64  `json:"amount"`
}

type UserPayload struct {
	Name string `json:"name"`
}

func decodePayload(envelope Envelope) (any, error) {
	var target any
	switch envelope.Kind {
	case "order":
		target = new(OrderPayload)
	case "user":
		target = new(UserPayload)
	default:
		// 未知 kind 不应被静默当成某一种业务对象。
		return nil, fmt.Errorf("unsupported kind %q", envelope.Kind)
	}

	if err := json.Unmarshal(envelope.Payload, target); err != nil {
		// RawMessage 可能来自外部输入，类型结构仍需单独处理错误。
		return nil, fmt.Errorf("decode %s payload: %w", envelope.Kind, err)
	}
	return target, nil
}

这里没有先把 Payload 转成通用 map，而是直接进入目标结构体。这样字段类型、必需字段检查和错误归属都更清楚。若同一个字段既可能是对象也可能是数组，应该在分支中明确区分，而不是依赖反射后的类型猜测。

修改已知字段后，怎样把未知字段放回去

如果外层结构还需要修改 kind 或 id，最稳妥的做法是保留 RawMessage 字段，再对新的外层结构体调用 json.Marshal。RawMessage 会作为 JSON 值嵌入，而不是再次被编码成带转义的字符串。

func rewriteEnvelope(input []byte, newKind string) ([]byte, error) {
	var old Envelope
	if err := json.Unmarshal(input, &old); err != nil {
		// 读取阶段先拦截非法外层 JSON，避免拼接出半成品。
		return nil, fmt.Errorf("read envelope: %w", err)
	}

	updated := Envelope{
		ID:      old.ID,
		Kind:    newKind,
		Payload: old.Payload,
	}
	encoded, err := json.Marshal(updated)
	if err != nil {
		// Marshal 错误通常来自新增字段实现了失败的 Marshaler。
		return nil, fmt.Errorf("rewrite envelope: %w", err)
	}
	return encoded, nil
}

注意 Payload: old.Payload 和 Payload: string(old.Payload) 的区别：前者把它当成 JSON 值嵌入，后者会把整段内容变成字符串并增加引号与转义。二次编码时不要为了“方便”把 RawMessage 先转成 string。

缺失、null、空对象和非法 JSON 要分开处理

RawMessage 让我们保留了原始值，但不会自动替业务做完整性判断。下面几种情况的含义不同：

如果协议要求 payload 必须是对象，可以在分派前用一个很小的临时检查或直接解码到目标结构体；不要只用 len(Payload) > 0 就认为数据完整。

我的迁移清单：什么时候适合 RawMessage

对我来说，RawMessage 最适合“外层稳定、内层变化”的接口：事件总线、插件扩展字段、按类型变化的配置片段，以及需要转发但暂时不解释的 JSON。它不适合替代所有结构体建模，也不适合把校验责任无限推迟。

• 固定字段先用结构体表达，动态字段再使用 json.RawMessage。
• 先根据明确的类型字段选择目标结构，再对 RawMessage 做二次 Unmarshal。
• 二次编码时直接传递 RawMessage，避免转换为字符串。
• 对缺失、null、空对象和非法 JSON 分别定义业务结果。
• 外部输入仍要保留大小限制、字段校验和错误上下文。

一句话总结：RawMessage 解决的是“暂时不解释，但不能丢掉”的问题；真正的类型安全和业务校验，仍然应该发生在你知道 payload 类型之后。

相关问题

RawMessage 会不会把 JSON 变成字符串？不会。直接作为结构体字段参与 Marshal 时，它会作为 JSON 值嵌入；只有转成 string 后才会变成带引号的字符串。

什么时候应该用 map[string]any？当字段名和层级都完全未知、且确实需要动态遍历时可以考虑；如果只是内层类型延迟确定，RawMessage 通常更容易维持类型边界。

RawMessage 能代替 JSON Schema 校验吗？不能。它只保存原始值，具体字段、类型、范围和必填规则仍需由目标结构体或独立校验逻辑负责。