JSON 转 Go 结构体 — 类型化字段、json tag、指针、零上传

真实使用场景

• 接第三方 API 时不再手写结构体

  你在接 GitHub API, user 对象有 30 多个字段。curl 一次拿到响应, 粘进来, 根名设为 `GitHubUser`, 复制输出到 `internal/github/types.go`。嵌套的 `plan` 对象自动抽成 `GitHubUserPlan`, `html_url` 变成 `HTMLURL` 并带正确的 tag。 现在 `json.Unmarshal(body, &u)` 填进一个完全类型化的 struct, 而不是一个到处要做类型断言的 `map[string]interface{}`。

• 给新 endpoint 生成请求 / 响应 DTO

  同事发来他在做的 `/orders` POST 的一个 JSON body 样例。粘进来, 根名 `CreateOrderRequest`, 打开 `,omitempty` 让可选字段不撑大 marshal 出的 payload。响应样例也粘进来命名 `CreateOrderResponse`。 两个结构体, tag 齐全, 在你们任何一方写 handler 之前就提交进 `api/dto.go`。

• 给可空的 webhook payload 决定用指针还是值

  某第三方的 webhook 有时带 `cancelled_at`, 有时不带。把前几次 payload 记下来, 作为 JSON 数组粘进来, 可选字段识别会标出 `cancelled_at`。打开"指针"它变成 `*string`, 这样在 handler 里 `if e.CancelledAt != nil` 就能干净地区分"已取消"和"仍有效": 不用再猜一个空字符串到底是不是"没发"。

• 把 map[string]interface{} 迁移成真正的类型

  老代码是 `var data map[string]interface{}`, 然后用 `data["user"].(map[string]interface{})["id"].(float64)` 一层层 挖。抓一个有代表性的响应粘进来, 生成结构体, 替换掉 map。 那些坑过你的 `.(float64)` 断言 (JSON 数字解进 `interface{}` 会变 float64) 消失了: `int` 和 `float64` 现在在字段层面就 推断好了。

• 给 Go 服务做 fixture 和配置类型

  你的服务读一个 `config.json`。粘进来, 根名 `Config`, 拿到 `Config`、`ConfigServer`、`ConfigServerTLS` 嵌套结构体, 端口是 `int`, 开关是 `bool`。放进 `config.go`, 写 `json.NewDecoder(f).Decode(&cfg)`, 配置在编译期就被类型检查, 而不是运行时因为一个拼错的 key 才挂。

常见踩坑

• 粘一个对象进来然后期待某些字段是可选的。单个对象没有"key 缺失"信号, 所以所有字段都是必需。可选 / 指针推断只在"多个对象组成的数组"里生效 (有的元素带某个 key、有的不带)。想从一个样本探索可选性, 把它包成 `[{...}]`。

• 给一个 0 / false / 空值有真实含义的字段开 ,omitempty。开了 omitempty, 一个你设成 0 的 `Count int` 在 marshal 出的 JSON 里直接不出现: 接收方分不清"count 是 0"还是"压根没发 count"。真需要这个区分时, 用指针 (`*int`) 加 omitempty。

• 以为 ID 一定该用 int64。如果你的 ID 是 JSON *字符串* (Stripe 的 `cus_123`、很多 UUID API), 它们会被推断成 `string` 而不是 int64, 这是对的。int64 只适用于数字型 JSON 值。别手动把一个字符串 ID 改成 int64, 会让 unmarshal 崩。

• 把一个只出现过 null 的字段当成有类型的字段。`{"meta": null}` 出来是 `Meta interface{}`, 因为 null 不带类型信息。如果你知道真实形状, 喂一个非 null 样本 (`{"meta": {"k": 1}}`), 工具才能推出像样的 struct。

• 粘 JSON5 / 带注释的 JSON / 末尾逗号。我们用严格的 `JSON.parse`, 注释、不带引号的 key、末尾逗号都会报错。先剥掉, 或者先过一道 JSON 格式化工具。

隐私说明