Go 解析 JSON 用 struct 还是 map[string]any：RawMessage 和严格校验怎么选

Go 里解析 JSON，不是简单地在 struct 和 map[string]any 之间二选一。接口字段稳定、后续还要做业务校验时，优先用结构体；只是临时查看未知字段，或者网关透传一段不固定内容，map[string]any 会更灵活；如果外层固定、内层要按类型再分发，json.RawMessage 用起来会顺畅很多。真正要避开的，是所有 JSON 都用同一种写法硬套。

先看 JSON 后续要承担什么任务

很多 JSON 解析出问题，根源是一开始没理清“解析完要做什么”。如果数据会进入订单创建、权限判断、库存扣减这类稳定业务流程，结构体能把字段名、类型、默认值和校验位置固定下来，代码评审也更容易发现风险点。

如果你只是临时接一个第三方回调，字段经常变动，或者只需要把原始内容打日志、透传给下游，强行定义一堆结构体反而会拖慢迭代进度。这个时候 map[string]any 或 RawMessage 就像工具箱里的临时夹具，用完就收，不要让它长期散落在核心业务逻辑里。

struct 适合稳定接口和业务校验

结构体的好处不是少写几行类型断言，而是让字段契约变得清晰。比如订单创建接口里，order_id、amount、items 都有明确含义，写成结构体后，后续校验、日志和单元测试都有明确的落点。

type CreateOrderReq struct {
    OrderID string `json:"order_id"`
    Amount  string `json:"amount"`
    Items   []Item `json:"items"`
}

var req CreateOrderReq
if err := json.Unmarshal(body, &req); err != nil {
    return err
}
if req.OrderID == "" || len(req.Items) == 0 {
    return errors.New("invalid order payload")
}

这里把 Amount 写成字符串不是偷懒，而是避免金额在 JSON number 和浮点数之间来回转换丢失精度。只要字段会影响资金、库存、权限、账号状态，就别把类型判断延后到后续很远的逻辑里。

map[string]any 适合临时排查和不固定字段

map[string]any 的优点是灵活，缺点同样是灵活。它适合两类场景：一类是临时排查第三方回调，想快速看到对方到底传了什么内容；另一类是网关、审计日志、配置预览这类不需要关心全部字段含义的场景。

var payload map[string]any
if err := json.Unmarshal(body, &payload); err != nil {
    return err
}
fmt.Println(payload["event_type"], payload["request_id"])

但它不适合长期承载核心业务。用久了你很快就会碰到类型断言、空值判断、数字精度和字段拼写错误这类问题。比如 payload["amount"].(float64) 看起来实现方便，实际很容易把整数 ID 或高精度金额的数值带偏。

RawMessage 适合外层固定、内层分流

事件回调、消息队列、插件协议里，经常有这类结构：外层字段固定，内层 data 要根据 type 再决定怎么解析。这时候用 json.RawMessage 体验很好，它能先保留原始 JSON 片段，等你确认类型标识后再做后续解析。

type EventEnvelope struct {
    Type string          `json:"type"`
    Data json.RawMessage `json:"data"`
}

var evt EventEnvelope
if err := json.Unmarshal(body, &evt); err != nil {
    return err
}

switch evt.Type {
case "order.created":
    var data OrderCreated
    return json.Unmarshal(evt.Data, &data)
case "user.locked":
    var data UserLocked
    return json.Unmarshal(evt.Data, &data)
default:
    return nil
}

这种写法比一上来把所有字段塞进 map[string]any 更容易维护。外层有明确契约，内层按类型拆开，每个业务事件都能有自己对应的结构体和测试用例。

严格校验要看接口边界

对外 API、管理后台、支付回调这类边界场景，建议校验规则更严格一点。Go 标准库的 json.Decoder 可以配合 DisallowUnknownFields 拦截掉未知字段，也可以用 UseNumber 避免默认把数字塞进 float64。

dec := json.NewDecoder(bytes.NewReader(body))
dec.DisallowUnknownFields()
dec.UseNumber()

var req CreateOrderReq
if err := dec.Decode(&req); err != nil {
    return err
}

不过严格校验不是开得越多越好。内部灰度接口、兼容老客户端的接口，如果突然拒绝未知字段，可能会影响旧版本的正常运行。比较稳妥的做法是：核心写入接口严格一些，查询和日志类接口宽松一些；要收紧规则时，先打日志观察一段时间确认没有误拦再全量上线。

一张表判断怎么选

不推荐的用法

• 核心订单、支付、权限接口长期使用 map[string]any，会让校验和测试逻辑越来越零散。
• 只因为字段多就放弃结构体定义，后续新增字段时更难发现破坏性变更。
• 所有接口都开启未知字段拒绝规则，可能误伤旧客户端或灰度发布的字段。
• 把金额直接解析成 float64 后再参与计算，很容易埋下精度问题。

常见问题

Go 解析 JSON 默认会忽略未知字段吗？

使用 json.Unmarshal 解析到结构体时，默认会忽略结构体里没有声明的字段。如果你想主动发现未知字段，可以改用 json.Decoder 并开启 DisallowUnknownFields。

map[string]any 里的数字为什么经常变成 float64？

标准库把 JSON number 解到 any 时，默认会用 float64。如果数字很长，或者需要保留原始值，可以使用 UseNumber，也可以提前把字段设计成字符串类型。

RawMessage 会不会增加性能负担？

它会让部分字段延后解析，但换来的是更清晰的分发边界。对事件类消息来说，这个开销通常比到处写零散的类型断言更可控。

接口字段还没稳定时，要不要先写 struct？

如果接口已经进入业务主链路，建议尽早定义结构体；如果只是联调观察阶段，可以先用 map[string]any 打印和对齐字段，等字段稳定后再收敛到结构体。

小结

Go JSON 解析的选择规则可以简单记下来：稳定业务用 struct，临时未知字段用 map[string]any，外层固定内层分流用 json.RawMessage。再往前延伸，就是按接口风险决定是否开启严格校验、是否保留数字原始值。选对了适用边界，代码里会少很多冗余的类型断言，也更容易在评审和测试环节发现潜在问题。