Golang JSON 解析：结构体字段导出与数组解析完全指南

本文详解 Go 语言中 encoding/json 包解析 JSON 数据的核心要点，包括结构体字段必须首字母大写（导出）、JSON 数组逐项反序列化方法，以及常见错误“unable to unmarshal” 的根本原因与修复方案。

用 Go 解析 JSON 的时候，有一个很容易被新手忽略的关键约束：只有导出字段才能被 encoding/json 包访问和赋值。所谓导出字段，就是结构体里那些首字母大写的成员，比如 Offset、FcnAddr。Go 的反射机制只允许对这些字段进行读写。如果字段名是小写字母开头，比如 offset，那就属于非导出字段——json 包根本“看不见”它，反序列化的时候也会直接跳过。结果就是，结构体里的某个字段始终是零值，更严格的情况下（比如嵌套结构或类型不匹配），还会直接抛出一个 json: cannot unmarshal ... 错误。

那怎么办？很简单，定义结构体时，必须把所有字段名都写成大写开头，同时用 json 标签显式地把它们映射到 JSON 里的键名。这种方法可维护性强，也清晰得多：

type DisassembleOutput struct {
    Offset   int      `json:"offset"`
    FcnAddr  int      `json:"fcn_addr"`
    FcnLast  int      `json:"fcn_last"`
    Size     int      `json:"size"`
    Opcode   string   `json:"opcode"`
    Bytes    string   `json:"bytes"`
    Type     string   `json:"type,omitempty"`      // 可选字段，JSON 中缺失时忽略
    TypeNum  int      `json:"type_num,omitempty"`
    Flags    []string `json:"flags,omitempty"`
    Comment  string   `json:"comment,omitempty"`
}

这里有个小细节：Fcn_addr 在 Go 里最好写成 FcnAddr（驼峰命名），再配合 json:"fcn_addr" 标签，既能遵守 Go 的惯用风格，又能在 JSON 侧保持下划线命名——语义和协议两头都兼顾了。

接下来，很多人容易踩第二个坑。你提供的 JSON 片段其实是一个JSON 数组（以 [ 开头），所以完整数据大概长这样：

[
  { "offset": 4224368, "fcn_addr": 4224368, ... },
  { "offset": 4224370, "fcn_addr": 4224368, ... }
]

如果你拿单个结构体变量去接，那就不只是“静默失败”的问题了——编译可能通过，但解析结果根本不对。正确的做法是声明一个结构体切片：

var outputs []DisassembleOutput
err := json.Unmarshal([]byte(jsonData), &outputs)
if err != nil {
    log.Fatal("JSON 解析失败:", err)
}
fmt.Printf("成功解析 %d 条指令\n", len(outputs))
for i, out := range outputs {
    fmt.Printf("第%d条: offset=%d, opcode=%s\n", i+1, out.Offset, out.Opcode)
}

如果数据特别大，不想一次性全都加载到内存里，可以用 json.Decoder 来实现流式解析，逐项处理：

decoder := json.NewDecoder(strings.NewReader(jsonData))
// 先读取 '['
_, err := decoder.Token()
if err != nil {
    log.Fatal(err)
}
// 循环读取每个对象
for decoder.More() {
    var item DisassembleOutput
    if err := decoder.Decode(&item); err != nil {
        log.Fatal("解析单项失败:", err)
    }
    fmt.Printf("解析单项: %+v\n", item)
}
// 读取 ']'
_, err = decoder.Token()

⚠️ 重要注意事项：

• 字段必须导出：这是 90%“unmarshal 失败”问题的根源，和字段类型或 JSON 格式没有关系；
• JSON 键名区分大小写：标签里的字符串必须和实际 JSON 键名完全一致，比如 "offset" 不等于 "Offset"；
• 用 omitempty 可以避免零值字段参与序列化，同时在反序列化时跳过缺失字段；
• 如果 JSON 里出现了结构体没定义的字段，json 包默认会忽略掉；万一需要捕获那些未知字段，可以考虑嵌入 map[string]interface{}，或者自定义 UnmarshalJSON 方法。

到这大家都清楚了吧？Go 的 JSON 解析强调的是一套显式且安全的规则。记住“大写字母导出 + 标签映射 + 切片接收数组”这三条原则，绝大多数 JSON 场景都可以平稳拿捏。