Go 结构体 JSON 序列化的坑与 tag 巧用

在社区里经常看到有人发帖：“我明明给结构体字段赋值了，序列化出来怎么不见了？”或者“这时间字段怎么变成字符串了？”这类问题十有八九都出在 Go 结构体 JSON 序列化的细节上。Go 的 `encoding/json` 是出了名的“约定大于配置”，你要是没搞懂它的脾气，光是字段大小写这一条就能让你折腾半天。

先说最大的一个坑：字段名大小写直接决定序列化结果。

Go 语言里，结构体字段只有首字母大写（即导出字段）才会被 `json.Marshal` 捕获。你辛辛苦苦写了个 `type User struct { name string }`，序列化出来只会是一个空对象 `{}`。这还不是最坑的，最坑的是当你用 `json.Unmarshal` 去反序列化时，它同样忽略小写字段，你收到的数据全部静默丢失，不会报错，程序继续跑，结果全错。排查这种问题比看报错日志难十倍。

第二大坑是零值字段被莫名吞掉。 你以为你定义了 `Age int \`json:"age"\``，序列化出来必然有 `age` 字段？天真了。如果 `Age` 是 0，`json.Marshal` 默认还是会输出的，但你要是手贱加了 `omitempty`，那 0 就消失了。有人就会问了：“用户没填年龄，我要么传 `null` 要么不传，这有什么问题？”问题大了——如果下游是 PHP 或老系统，它用 `isset($age)` 判断，结果字段不存在，直接走默认分支，数据对不上。更隐蔽的是 `bool` 的 `false` 被吞，很多新人在用 `done bool \`json:"done,omitempty"\`` 时吃了大亏，明明事件已处理完，字段却不见了。

tag 能解决这些问题，但也得会用。

`json:"-"` 就不用多说了，忽略字段。但真正巧妙的是 `json:",omitempty"` 配合指针类型。很多资深 Gopher 在区分“字段未提供”和“字段提供但为零值”时，故意把字段声明成 `*int` 或 `*string`。如果 JSON 里没这个 key，指针就是 `nil`，序列化后就不输出，如果客户端传了 `0` 或空字符串，指针指向对应变量，就能如实传输。这是社区公认的“有状态”序列化手法。

再比如 `json:",string"` 这个 tag 选项，真乃神器。有些老接口规定所有数字都得是字符串格式，比如订单金额、用户 ID。在结构体里写 `ID uint64 \`json:"id,string"\``，序列化输出就是 `"id": "123456"`，反序列化时也能把 `"123456"` 转回 `uint64`。但注意，这招只对基本数值类型有效，对自定义类型就失灵了，这时候你得实现 `Marshaler` 接口。

然后得提两个非常憋屈的坑，社区里吐槽过无数回。

第一个是 HTML 字符转义。默认 `json.Marshal` 会把 `<`、`>`、`&` 转义成 `\u003c` 之类。你存了一份包含 HTML 片段的数据，序列化完了发现全被转成 Unicode 了。开眼界吧？解决办法是 `json.Encoder` 配合 `SetEscapeHTML(false)`，而不是改 `Marshal` 本身。

第二个坑是 时间字段默认格式。`time.Time` 实现的是 `MarshalJSON`，默认输出 RFC3339 格式，像 `2024-06-01T15:04:05Z`。但 MySQL 驱动、前端日历控件通常需要 `2006-01-02 15:04:05`。你不能直接改 tag，要自己定义时间类型，在 `MarshalJSON` 你重写格式，或者用 `json.RawMessage` 先解包再处理。

再说说嵌套结构体和 map 的序列化混乱场景。有人图省事，接口直接返回 `map[string]interface{}`，这本身没错，但 map 的 key 无论你定义成 `string` 还是别的接口类型，JSON 序列化后 key 永远是字符串。更麻烦的是 `map[string]interface{}` 套 `interface{}` 后，解码时数字变成 `float64`。你前端拿个大整数 ID 过来，比如 `18350948234233233`，你反序列化到 `interface{}` 里，`float64` 直接丢精度。你从接口下一层一层取数据时已经晚了。这种场景最好在结构体里定义清楚类型，手动转成 `json.Number` 再用。

最后一个 tag 巧用，是字段名前缀加 `omitempty` 的反向应用：字段融合。 如果你希望同一个结构体根据环境序列化成不同字段名，什么技巧都不如把 tag 写成多个名字，比如 `Auth \`json:"auth,omitempty"\`` 你要是嫌弃这个名字，可以用 `json:"token"` 输出到客户端，内部字段叫 `Token`，各端解耦。

说到底，tag 的功底考验的是你对数据契约的理解。在写结构体之前，先想一想：这个字段是必填还是可选？默认零值有业务含义吗？下游是强类型还是弱类型？如果这些没想清楚，再花哨的 tag 也只是给自己挖坑。

我建议的实践是：团队内定一套 JSON 字段规范，蛇形还是驼峰必须统一，用 `snake_case` 配 `json` tag 是主流。然后所有 DTO 与内层模型分离，DTO 专门控制输出格式，不要直接拿数据库模型上 API，你无法保证字段的序列化语义不被其他调用方不小心 break 掉。