应优先使用 json.RawMessage 延迟解析以避免过早类型绑定，它零拷贝保留原始字节，适用于字段结构不确定或仅需读取部分子字段的场景；配合首字符判断和分路径解析可处理混合类型字段。
用 json.RawMessage 延迟解析，避免过早类型绑定
Go 的 json.Unmarshal 对未知结构最头疼的不是解析失败，而是提前声明 struct 导致后续字段增减必须同步改代码。真正灵活的做法是先用 json.RawMessage 把整段 JSON 当作字节流暂存，等真正需要某字段时再单独解码。
常见错误是直接上 map[string]interface{} ——它看似通用，但嵌套深了会变成 map[string]interface{} 套 map[string]interface{}，类型断言写起来像俄罗斯套娃，且丢失原始 JSON 的数字精度（float64 会吞掉整数尾部的 .0）。
-
json.RawMessage本质是[]byte别名，零拷贝保留原始字节，不触发解析 - 适合字段结构不确定、或仅需读取其中一两个子字段的场景（比如只取
"data"或"meta.version"） - 注意：不能直接打印或序列化
json.RawMessage，否则输出的是 base64 编码后的字符串
用 interface{} + 类型断言处理动态字段，但得小心浮点数陷阱
当必须走 interface{} 路线时（比如对接第三方 API 返回结构不可控），关键不是怎么解，而是怎么安全取值。Go 解析 JSON 到 interface{} 时，所有数字默认转成 float64，哪怕原始是 123 或 "123"。
典型错误是写 v := data["id"].(int) 直接 panic —— 实际类型是 float64，得先转再转：
立即学习“go语言免费学习笔记（深入）”；
if id, ok := data["id"].(float64); ok {
userID := int64(id) // 注意：float64 可能有精度误差，整数 ID 建议用 int64
}
- 字符串、布尔、nil 值可直接断言，但数字一律按
float64处理 - 如果原始 JSON 里数字可能超
float64精度（如 19 位以上整数），必须用json.RawMessage配合strconv.ParseInt手动解析 - 嵌套 map 或 slice 需逐层断言，建议封装工具函数做安全取值，比如
GetFloat64(data, "user", "score")
自定义 UnmarshalJSON 方法适配混合类型字段
某些 API 字段可能是 string 或 object（比如 "status" 有时返回 "active"，有时返回 {"code":200,"msg":"ok"}）。标准库无法自动识别这种 union 类型，必须手动实现 UnmarshalJSON。
核心思路：先用 json.RawMessage 接收原始字节，再根据首字符判断结构，分路径解析：
func (s *StatusField) UnmarshalJSON(data []byte) error {
if len(data) == 0 || bytes.Equal(data, []byte("null")) {
return nil
}
if data[0] == '"' {
return json.Unmarshal(data, &s.StringValue)
}
return json.Unmarshal(data, &s.ObjectValue)
}
- 必须检查空值和
null，否则json.RawMessage会把null当作字面量解析失败 - 首字符判断比
json.Unmarshal后再反射判断类型快得多，也避免重复解析 - 不要在
UnmarshalJSON里调用本类型的其他方法，容易循环引用
性能与可维护性平衡：什么时候该放弃“任意类型”，回归强类型
“任意解析”本质是把类型校验从编译期推到运行期，换来灵活性，代价是 panic 风险、调试困难、IDE 无提示。实际项目中，80% 的所谓“动态 JSON”其实有隐含契约——比如 webhook payload 总是包含 "event_type" 和 "payload"，只是 payload 结构随 event_type 变。
- 优先用 discriminated union 模式：先解析顶层固定字段，再根据
event_type分发到对应 struct - 用
go:generate工具从 OpenAPI 或 JSON Schema 自动生成 struct，比手写interface{}更可靠 - 如果真要支持完全开放 schema，至少加一层 wrapper，把 raw bytes + schema hash 存起来，便于后续审计和回溯
最常被忽略的是错误上下文——用 fmt.Errorf("parse user.id: %w", err) 包裹原始错误，比裸抛 json: cannot unmarshal string into Go value of type int 有用得多。
