Go语言结构体转JSON失败的根源与完整解决方案

Go结构体字段必须首字母大写（导出）且正确标注json标签，否则json.Marshal将忽略私有字段，导致输出空对象{}。本文详解导出规则、标签用法、错误处理及最佳实践。

Go结构体字段必须首字母大写（导出）且正确标注`json`标签，否则`json.Marshal`将忽略私有字段，导致输出空对象`{}`。本文详解导出规则、标签用法、错误处理及最佳实践。

在Go语言中，将结构体序列化为JSON是Web API开发的高频操作，但初学者常遇到“结构体有值，JSON却是{}”的困惑——根本原因在于Go的导出（exported）机制与encoding/json包的设计约定。

? 核心前提：字段必须可导出

Go规定：只有首字母大写的字段（即导出字段）才能被外部包（包括encoding/json）访问。若字段名以小写字母开头（如 yr, withdrawal），json.Marshal 无法读取其值，直接跳过，最终生成空JSON对象 {}。

✅ 正确写法（首字母大写 + 显式JSON键名）：

type Sim struct {
    Yr         []int  `json:"yr"`         // 导出字段，映射为小写"yr"
    Ag         []int  `json:"ag"`
    Av         []int  `json:"av"`
    Db         []int  `json:"db"`
    Wd         []int  `json:"wd"`
    St         []int  `json:"st"`
    Withdrawal []string `json:"withdrawal"`
}

⚠️ 错误写法（全部小写 → 全部被忽略）：

type Sim struct {
    yr, ag, av, db, wd, st []int     // 私有字段 → Marshal时不可见
    withdrawal []string             // 同样私有 → 不参与序列化
}

✅ 完整可运行示例

package main

import (
    "encoding/json"
    "fmt"
)

type Sim struct {
    Yr         []int  `json:"yr"`
    Ag         []int  `json:"ag"`
    Av         []int  `json:"av"`
    Db         []int  `json:"db"`
    Wd         []int  `json:"wd"`
    St         []int  `json:"st"`
    Withdrawal []string `json:"withdrawal"`
}

func main() {
    s := Sim{
        Yr:         []int{2020, 2021, 2022},
        Ag:         []int{60, 61, 62},
        Withdrawal: []string{"$140000", "$145000"},
    }

    data, err := json.Marshal(s)
    if err != nil {
        fmt.Printf("JSON marshaling failed: %v\n", err)
        return
    }

    fmt.Printf("Struct value: %+v\n", s)
    fmt.Printf("JSON output: %s\n", string(data))
    // 输出: {"yr":[2020,2021,2022],"ag":[60,61,62],"withdrawal":["$140000","$145000"]}
}

⚠️ 关键注意事项

• 标签非必需但强烈推荐：若省略 `json:"xxx"`，字段将按原名（大写首字母）出现在JSON中（如 Yr → "Yr"），不符合RESTful命名惯例（通常用snake_case或kebab-case）。
• 嵌套结构体同样需导出：子结构体字段也必须首字母大写，否则整个嵌套对象可能为空。
• 务必检查错误：json.Marshal 在输入含不可序列化类型（如func、chan）时返回错误，忽略err将导致静默失败。
• 零值字段处理：空切片 []int(nil) 序列化为 null；空切片 []int{} 序列化为 []。如需统一为[]，初始化时用 make([]int, 0)。

? 进阶建议

• 使用 json:",omitempty" 标签自动省略零值字段（如空字符串、0、nil切片）：

  Name string `json:"name,omitempty"`

• 对敏感字段（如密码）添加 json:"-" 完全屏蔽：

  Password string `json:"-"`

• 生产环境启用 json.Decoder.DisallowUnknownFields() 防止前端传入非法字段导致静默丢弃。

掌握导出规则与标签规范，是Go JSON序列化的第一道门槛。记住口诀：“大写导出，小写标签，必查错误” —— 即可避开90%的结构体转JSON陷阱。