Go 中嵌套 JSON 解析方法详解

本文详解 Go 语言中使用 encoding/json 解析含多层嵌套结构（如嵌套对象映射）的 JSON 数据，重点解决字段标签误用、匿名结构体嵌套声明不当导致的反序列化失败问题，并提供可直接运行的结构体定义与最佳实践。

在 Go 中解析嵌套 JSON 时，常见错误是将 JSON 对象（如 "ports": { "tcp": [...], "udp": [...] }）错误地映射为字符串字段或未正确绑定 JSON 标签，从而触发 json: cannot unmarshal object into Go value of type string 等 panic。根本原因在于：Go 的 json.Unmarshal 要求结构体字段类型必须与 JSON 值类型严格匹配，且嵌套对象需通过嵌套结构体 + 正确 json tag 显式声明。

以下是一个修复后的完整示例，清晰展示了如何定义结构体以准确映射嵌套 JSON：

package main

import (
    "fmt"
    "encoding/json"
)

type Data struct {
    Ports struct {
        Tcp []int `json:"tcp"`
        Udp []int `json:"udp"`
    } `json:"ports"` // ⚠️ 关键：外层匿名结构体整体绑定 "ports" 字段
    Protocols []string `json:"protocols"`
}

func main() {
    jsonStr := `{
        "ports": {
            "udp": [1, 30],
            "tcp": [100, 1023]
        },
        "protocols": ["tcp", "udp"]
    }`

    var data Data
    if err := json.Unmarshal([]byte(jsonStr), &data); err != nil {
        fmt.Printf("解析失败: %v\n", err)
        return
    }

    fmt.Printf("TCP 端口: %v\n", data.Ports.Tcp)   // 输出: [100 1023]
    fmt.Printf("UDP 端口: %v\n", data.Ports.Udp)   // 输出: [1 30]
    fmt.Printf("协议列表: %v\n", data.Protocols)   // 输出: [tcp udp]
}

✅ 关键要点说明：

• Ports 字段必须是结构体类型（不能是 string 或其他基础类型），因为其对应 JSON 中的 object；
• 匿名结构体内部字段（Tcp/Udp）需显式添加 json:"tcp" / json:"udp" 标签，确保与 JSON 键名精确匹配（大小写敏感）；
• 外层 Ports 字段自身也需带 json:"ports" 标签——这是最容易被忽略的一点：它告诉解码器将 JSON 中的 "ports" 键值对整体映射到该匿名结构体；
• 数值数组建议使用 []int（而非 []float64），除非 JSON 明确包含浮点数；Go 的 JSON 解码器能自动将整数字面量转为 int（只要不溢出）。

⚠️ 常见陷阱提醒：

• 若将 Ports 定义为 P string \json:"ports"`（如原问题代码），解码器会尝试把整个{ "tcp": [...], "udp": [...] }` 对象赋给字符串，必然失败；
• 忘记为嵌套结构体加外层 json tag，会导致该字段被忽略（零值）；
• 字段名首字母小写（如 tcp []int）会使字段不可导出，json 包无法访问，导致解码静默失败（字段保持零值）。

总结：处理嵌套 JSON 的核心原则是——“JSON 对象 → Go 结构体”，逐层对齐层级与类型，并为每一级字段正确配置 json tag。合理利用匿名结构体可避免过度定义冗余类型，提升代码简洁性与可维护性。