字段结构经常变化的 JSON 怎么接：结构体、map 与 RawMessage 的边界对比

如果接口字段经常变化，不要一上来把整段 JSON 解成 map[string]any。更稳妥的边界是：稳定字段放进结构体，只有未知或需要按类型判断的局部字段才延迟处理。这样既保留编译期约束，也不会因为供应商增加一个字段就改动整套模型。

本文只讨论 Go 标准库 encoding/json 的解码边界，不把动态 JSON 变成“什么都能接”的无类型对象，也不展开第三方 JSON 库。

先判定你要不要立即解释字段

先把响应拆成三类：一是请求方必须依赖的稳定字段，例如 id、kind；二是可以忽略的新增字段；三是结构由 kind 或版本决定的动态字段。第一类用结构体，第二类让解码器自动忽略，第三类保留原始 JSON。

这一步的结果不是“选一种容器”，而是确定责任边界：结构体负责契约，RawMessage 负责保留证据，映射负责临时探索。若后续业务要对某字段做计算、排序或持久化，就不要让它长期停留在 any 中。

三种接法分别承担什么责任

结构体：适合稳定契约。字段有明确 Go 类型，拼写错误更早暴露，编辑器也能提供补全。未知 JSON 成员通常会被忽略，因此接口新增非关键字段时不必同步发版。缺点是面对同一位置可能出现多种形状时，需要自定义解码或拆模型。

map[string]any：适合只需要遍历键、做临时探查的场景。但标准库把 JSON 数字默认解成 float64，嵌套对象继续变成 map[string]any，数组变成 []any。一旦业务代码到处写类型断言，维护成本会迅速超过结构体。

map[string]json.RawMessage：适合键名动态、值的解释规则明确但不统一的场景。每个值仍是原始 JSON 字节，可以按键选择目标类型；它比 map[string]any 多保留一层信息，但也要求你处理二次解码错误。

用 RawMessage 把稳定外壳和动态内核分开

假设事件的 id、kind 稳定，但 payload 会随事件种类变化，可以只把 payload 留成原始值：

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

func decodePayload(e Event) (any, error) {
    switch e.Kind {
    case "user.created":
        var p UserCreated
        if err := json.Unmarshal(e.Payload, &p); err != nil {
            return nil, fmt.Errorf("decode %s payload: %w", e.Kind, err)
        }
        return p, nil
    case "quota.changed":
        var p QuotaChanged
        if err := json.Unmarshal(e.Payload, &p); err != nil {
            return nil, fmt.Errorf("decode %s payload: %w", e.Kind, err)
        }
        return p, nil
    default:
        return nil, fmt.Errorf("unsupported event kind %q", e.Kind)
    }
}

这里的关键不是把所有情况塞进 switch，而是让动态边界只有一个入口。外层解码成功并不代表 payload 合法，所以二次 Unmarshal 必须返回错误；日志中带上 kind，排障时才能区分“JSON 语法错”和“事件类型与 payload 不匹配”。

如果键名本身变化，可以先解成 map[string]json.RawMessage：

var fields map[string]json.RawMessage
if err := json.Unmarshal(data, &fields); err != nil {
    return err
}
var count int
if raw, ok := fields["count"]; ok {
    if err := json.Unmarshal(raw, &count); err != nil {
        return fmt.Errorf("count is not an integer: %w", err)
    }
}

常见问题

JSON 缺少结构体字段会报错吗？

通常不会，缺失字段会保留 Go 零值。若“缺失”和“明确为 null”含义不同，应使用指针或额外的存在性记录，不要靠零值猜测。

为什么 map[string]any 里的数字不是 int？

因为默认解码路径把 JSON 数字放入 float64。需要保留数字文本或整数语义时，可使用 json.Decoder 的 UseNumber，或直接保留为 RawMessage 后按目标类型解码。

什么时候应该回到结构体？

当动态字段已经被业务稳定使用、需要校验或写入数据库时，就应把二次解码结果提升为具名结构体，并为不支持的 kind 保留清晰的错误路径。

总结：结构体解决稳定契约，map[string]any 解决临时探索，json.RawMessage 解决“现在还不能决定类型”的局部延迟。先按字段稳定程度划边界，再决定容器，动态 JSON 才不会把类型风险扩散到整个 Go API。