Golang JSON序列化教程：json.Marshal实用指南

本文深入剖析了 Go 语言中 json.Marshal 的核心行为与高频踩坑点，明确指出其“不处理私有字段、不支持循环引用、nil slice/map 输出 null、time.Time 默认转 RFC3339 字符串”等看似反直觉的行为实为精心设计而非 bug；同时系统性地解答了字段未序列化的根本原因（首字母导出规则与 tag 语法规范）、nil 集合的输出控制策略、time.Time 格式自定义的正确姿势（必须实现 Marshaler 接口，tag 中 format 无效），以及由 nil 指针解引用或不兼容类型引发 panic 的典型场景与防御方案——帮你避开生产环境中最隐蔽、最易复现的 JSON 序列化陷阱。

直接说结论： json.Marshal 默认不处理私有字段、不支持循环引用、对 nil slice/map 输出空结构，且时间类型会转成 RFC 3339 字符串——这些不是 bug，是设计选择，但恰恰是日常踩坑最多的地方。

为什么 struct 字段没被序列化？

Go 的 json.Marshal 只导出首字母大写的字段（即“可导出字段”），小写开头的字段（哪怕加了 json: tag）会被静默忽略。

• 检查字段名是否首字母大写：比如 type User { name string } 中的 name 不会输出，必须写成 Name string
• tag 写法要正确：`json:"name,omitempty"` 有效，但 `json:name` 或 `json:"name,"` 会失效
• 嵌套 struct 也要逐层检查导出性——哪怕外层导出，内层字段不导出照样丢

如何控制 nil slice 或 map 的输出？

默认情况下，nil slice 和 nil map 都会被序列化成 null，而不是 [] 或 {}。这在 API 前后端约定中常引发歧义。

• 想让 nil []string 输出 []：用 omitempty 不够，得初始化为空切片：Roles: []string{}
• 想统一把 nil 当空值处理：可以封装一个辅助函数，或用自定义类型实现 json.Marshaler 接口
• 注意 omitempty 对 nil 指针也生效，但对 nil interface{} 无效（它会输出 null）

time.Time 序列化出来是字符串，怎么改格式？

json.Marshal 对 time.Time 的默认行为是调用 Time.Format(time.RFC3339)，输出带时区的 ISO 时间字符串，比如 "2024-05-20T14:30:00+08:00"。

• 如果需要自定义格式（如去掉时区、用秒级精度），必须实现 json.Marshaler 接口
• 常见错误：试图用 json:"time,format=2006-01-02" —— 这个 tag 是 encoding/json 完全不识别的，纯属无效
• 性能提示：每次序列化都调用 Format 有开销，高频场景建议预计算或缓存格式化结果

遇到 invalid memory address 或 panic 怎么办？

典型错误信息：panic: runtime error: invalid memory address or nil pointer dereference，往往发生在 struct 字段是未初始化的指针类型，又没加 omitempty。

• 比如 CreatedAt *time.Time 字段为 nil，且没加 omitempty，json.Marshal 会尝试解引用导致 panic
• 解决方法：加 omitempty（推荐），或确保指针非 nil（如用 &time.Now() 初始化），或改用值类型（time.Time）
• 更隐蔽的情况：字段类型实现了 json.Marshaler，但其 MarshalJSON 方法内部 panic 了——这时要查自定义序列化逻辑

最常被忽略的一点：json.Marshal 不做深层校验，它不会告诉你某个字段类型根本不支持 JSON（比如 func()、chan、未导出的 map key 类型），而是在运行时 panic 或静默跳过。上线前务必用真实数据跑一遍序列化路径。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Golang JSON序列化教程：json.Marshal实用指南》文章吧，也可关注golang学习网公众号了解相关技术文章。