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"`
}⚠️ 错误写法（全部小写 → 全部被忽略）：
立即学习“go语言免费学习笔记（深入）”；
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陷阱。
