Golang结构体转JSON方法详解

本文深入剖析了Go语言中结构体转JSON字符串的常见陷阱与最佳实践，重点揭示了json.Marshal仅序列化导出字段（首字母大写）这一极易被忽视的核心规则，并系统讲解了如何通过struct标签（如`json:"name"`、`,omitempty`）、时间类型处理、nil指针行为、HTML转义控制及中文显示等关键细节精准掌控序列化结果——帮你避开静默丢字段、意外null、时间格式错乱、乱码和前端解析失败等高频坑点，真正写出健壮、可预期、符合API规范的JSON输出。

json.Marshal 会忽略未导出字段，这是最常踩的坑

Go 的 json.Marshal 只能序列化首字母大写的导出字段。小写开头的字段（比如 name string）在结果里直接消失，连 null 都不会出现——不是报错，是静默丢弃。

• 检查结构体字段是否都以大写字母开头；如果必须用小写字段，加 json: 标签并确保字段可导出（即首字母大写 + 标签控制名称）
• 标签写法示例：Name string `json:"name"`，注意引号是反引号
• 空值字段默认被省略？那是 omitempty 的行为，不是默认逻辑；不加它就会输出 "field": null

时间字段序列化成字符串还是数字，取决于 Time 类型和 MarshalJSON 实现

Go 的 time.Time 默认被 json.Marshal 转成 RFC3339 字符串（如 "2024-05-20T14:23:18+08:00"），但如果你自定义了 MarshalJSON() 方法，或者用了第三方时间类型（比如 github.com/jinzhu/now 或某些 ORM 的时间包装），就可能输出时间戳数字或 panic。

• 确认你用的是标准 time.Time；如果不是，查它的文档看 MarshalJSON 返回什么
• 想统一成时间戳？得自己实现 MarshalJSON 方法，返回 json.Number(strconv.FormatInt(t.Unix(), 10))
• 别依赖 json:",string" 标签去“强制转字符串”——它只对数字/布尔字段有效，对 time.Time 无效

嵌套 struct 和 nil 指针字段的 JSON 表现很关键

json.Marshal 对 *T 类型字段的处理是：nil 指针 → 输出 null；非 nil → 序列化所指内容。但很多人误以为它会跳过 nil 指针，结果 API 返回了意外的 null，前端报错。

• 如果字段允许为空且不想暴露 null，用 omitempty 标签（前提是该字段本身是零值或 nil）
• 切片为 nil 和空切片 []int{} 在 JSON 中都变成 []；但 map 为 nil 时会输出 null，这点容易混淆
• 避免在 struct 里混用 *string 和 string 表达“可选”，统一用指针 + omitempty 更可控

中文乱码、HTML 转义、缩进这些细节其实都有开关

默认 json.Marshal 会把中文转成 Unicode 编码（"\u4f60\u597d"），还会对 、>、& 做 HTML 转义——这在 API 返回中通常不需要，反而增加体积和阅读难度。

• 用 json.MarshalIndent 加缩进适合调试，但生产环境别用；它不改变语义，只影响格式
• 禁用 HTML 转义：先 json.NewEncoder(w).SetEscapeHTML(false)，再调 Encode；Marshal 函数本身不提供这个开关
• 保留原始中文：不用额外操作，只要没设 SetEscapeHTML(true)（默认就是 false）且没手动替换，中文就原样输出

实际写的时候，最麻烦的往往不是怎么调 json.Marshal，而是结构体字段的可见性、零值语义、以及嵌套层级里某一层悄悄用了自定义序列化——这些地方一错，JSON 看似正常，字段却莫名消失或类型错位。

本篇关于《Golang结构体转JSON方法详解》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于Golang的相关知识，请关注golang学习网公众号！