Go 解析 JSON 怎么选：struct、map、RawMessage 还是 Decoder

Go 解析 JSON 时，最稳的选择通常是结构体：字段稳定、接口契约明确、后续业务也需要类型约束，就让数据直接落到 struct。map[string]any 适合临时排查或少量未知字段；json.RawMessage 适合先保留某段原始 JSON，等知道类型后再解析；json.Decoder 更适合请求体、大文件或流式数据。真正的判断不是哪种写法更短，而是字段是否稳定、数据量是否可控、是否需要保留原始片段，以及数字精度和未知字段要不要严格处理。

先看字段稳定性，而不是先选写法

很多 Go 项目一开始会用 map[string]any 解析 JSON，因为它看起来最快：不用定义结构体，字段想取哪个就取哪个。问题也常从这里开始。字段名写错时编译器发现不了，数字默认可能变成 float64，业务层到处都是类型断言，一旦接口字段变多，排查成本会越来越高。

更实用的判断方式，是先把数据分成三类：接口契约稳定的数据、只用于临时查看的数据、结构会随类型变化的数据。契约稳定的数据要尽早变成结构体；临时数据可以保持灵活；结构变化的数据需要把变化点隔离出来，不要让整个请求都变成一张大 map。

四种解析方式各自解决什么问题

json.Unmarshal 把一段完整的字节数据解析到目标变量里，适合已经拿到完整 JSON 的场景。目标变量可以是结构体，也可以是 map、切片或其他组合类型。结构体强调契约，map 强调灵活，二者解决的是不同问题。

json.RawMessage 本质上是保留一段原始 JSON。它不是为了让代码少写几行，而是为了把“现在还不知道具体结构”的字段留到后面再处理。比如事件通知里有 type 和 data，只有读到 type 后才知道 data 应该映射成订单事件、用户事件还是支付事件。

json.Decoder 则更像一个读取器。它从 io.Reader 里逐步读取 JSON，常见于 http.Request.Body、文件和流式数据。它还提供 UseNumber 和 DisallowUnknownFields 这样的开关，方便在接口入口处把数字精度和字段契约管住。

字段稳定时优先结构体

用户注册、订单创建、配置读取、后台表单提交这类场景，字段通常是稳定的。此时用结构体最合适：字段名、类型、是否可选都写在同一个地方，后续维护的人能一眼看出接口需要什么数据。

type CreateUserRequest struct {
    ID    int64  `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

func parseUser(body []byte) (CreateUserRequest, error) {
    var req CreateUserRequest
    if err := json.Unmarshal(body, &req); err != nil {
        return CreateUserRequest{}, err
    }
    return req, nil
}

结构体还有一个很重要的好处：业务代码不用到处做类型判断。解析通过后，req.ID 就是 int64，req.Email 就是字符串。只要校验逻辑补齐，后续代码会比 map 更稳定。

需要注意的是，结构体字段不是完整校验器。JSON 缺字段时，Go 会留下零值；字段多出来时，直接使用 Unmarshal 默认不会报错。如果接口必须严格拒绝未知字段，应该在请求入口改用 Decoder 并打开未知字段检查。

临时查看数据可以用 map

map[string]any 不是不能用，而是要控制范围。它适合临时排查第三方接口、查看不稳定字段、打印调试信息，或者只做一层很薄的透传。如果它一路传到服务层、数据库层和模板层，后面很容易变成“谁也不知道里面到底有什么”。

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

name, _ := payload["name"].(string)
idValue, ok := payload["id"].(float64)
if !ok {
    return errors.New("id must be a number")
}

上面这段代码能跑，但它暴露了 map 的典型问题：每次取值都要断言类型，字段名写错也不会在编译时暴露。更麻烦的是数字。JSON 里没有 int、int64、float64 这些 Go 类型边界，默认解析进 interface 时，数字容易按 float64 处理。订单号、雪花 ID、金额分单位这类字段，不应该用这种方式长期承接。

所以 map 更适合放在“观察层”，不要放在“业务契约层”。当字段稳定下来，就应该把它迁回结构体。

字段随类型变化时使用 RawMessage

有些 JSON 的外层字段固定，内层字段会随类型变化。事件通知、消息队列、前端埋点、规则配置都可能这样设计。此时把整包数据解析成 map 会让代码变散；把所有可能字段都塞进一个超大结构体，又会让字段含义变得混乱。更稳的做法是用 json.RawMessage 保留变化部分。

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

type UserCreated struct {
    UserID int64  `json:"user_id"`
    Name   string `json:"name"`
}

func parseEvent(body []byte) error {
    var event Event
    if err := json.Unmarshal(body, &event); err != nil {
        return err
    }

    switch event.Type {
    case "user.created":
        var data UserCreated
        if err := json.Unmarshal(event.Data, &data); err != nil {
            return err
        }
        return handleUserCreated(data)
    default:
        return errors.New("unknown event type")
    }
}

这种写法的关键不是“延迟”本身，而是把不稳定的部分圈在 Data 里。外层的 Type、时间、来源、签名字段仍然可以保持结构体约束；只有真正会变化的字段交给二次解析。

HTTP 请求体和大数据更适合 Decoder

HTTP 接口里经常直接从 r.Body 读 JSON。此时用 json.NewDecoder 更自然，因为请求体本身就是一个流。对接口来说，还可以顺手补上两个常见保护：数字用 UseNumber 保留精度判断空间，未知字段用 DisallowUnknownFields 尽早拦住。

func decodeCreateUser(r *http.Request) (CreateUserRequest, error) {
    dec := json.NewDecoder(r.Body)
    dec.UseNumber()
    dec.DisallowUnknownFields()

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

    var extra struct{}
    if err := dec.Decode(&extra); err != io.EOF {
        return CreateUserRequest{}, errors.New("request body must contain one JSON object")
    }
    return req, nil
}

最后那次 Decode 是为了避免请求体里拼了多个 JSON 对象。很多接口只期望一个对象，解析完第一个就结束，容易让尾部脏数据被忽略。再读一次并期待 io.EOF，能让入口更严格。

处理大文件或连续数据时，也可以用 Decoder 按顺序读取。这样不必一次把所有内容读进内存。对日志导入、批量任务、JSONL 转换这类场景，流式读取通常比整包读取更稳。

决策表：按场景选择解析方式

落地时可以把问题拆成几个判断点：字段是否稳定、是否需要类型约束、数据是否很大、是否要严格拒绝未知字段、是否有多态字段。下面这张表可以作为日常评审时的选择依据。

一个简单规则是：进入业务层之前，尽量把 JSON 变成类型明确的数据；只有变化点才保持灵活。这样既不会过早把所有字段写死，也不会让业务代码长期面对不透明的 map。

相关问题

Go 解析 JSON 为什么不建议长期用 map[string]any？

因为它把字段名、字段类型和业务约束都推迟到了运行时。小脚本或临时排查没问题，长期业务代码里会出现大量类型断言，字段改动也更难追踪。

json.Decoder 一定比 json.Unmarshal 更好吗？

不是。已经拿到完整字节数据时，json.Unmarshal 很直接；从请求体、文件或流里读时，json.Decoder 更合适。两者不是高低关系，而是输入来源不同。

DisallowUnknownFields 会检查所有嵌套字段吗？

它会让目标结构体里不存在的字段报错，适合严格接口入口。但它不能替代业务校验，例如必填字段、字符串长度、枚举值范围仍然要自己检查。

RawMessage 会不会让代码更复杂？

如果所有字段都稳定，确实没必要用它。只有某个字段需要按类型二次解析时，RawMessage 才能把复杂度限制在变化点上，避免整包数据都退化成 map。

总结

Go 解析 JSON 的选择可以按一句话收口：稳定字段进结构体，临时未知用 map，局部多态用 RawMessage，请求体和大数据用 Decoder。真正影响质量的不是 API 名字，而是边界是否清楚：数字精度怎么处理，未知字段是否允许，缺字段如何校验，变化字段放在哪里。把这些问题在入口处想清楚，后面的业务代码会干净很多。