JSON 转 Go Struct:生成器给骨架,这四件事要手补
结论:把 API 响应样本贴进转换器,十秒钟得到一套带 json tag 的 Go 结构体,但 number 落成 float64、空结构体省不掉、time.Time 只认 RFC 3339 这四件事生成器不会替你做。本文给出映射表、指针与 omitzero 的取舍,以及生成后必须人工补齐的四步清单。

结论先行:转换器十秒钟给出的结构体可以直接进编译,但不能直接进生产。生成器只描述「你贴进来的那一个样本」——数字统一 float64、可选字段不会自动变指针、omitempty 省不掉空结构体、日期字符串大多变不成 time.Time。这四件事,粘贴之后仍要手工补齐。
把一份接口响应抄成 Go 结构体是纯机械劳动,但机械劳动的代价藏在静默处:字段名拼错一个字母不报编译错,只会让字段永远是零值;null 处理错一个开关,生产日志里就会出现不该出现的
"note": null。生成结构体解决的是名字与类型的对齐问题,对不齐的从来只有两处——样本之外的变体,和 Go 类型系统与 JSON 类型系统之间的缝。
先看生成器读出什么:一张类型映射表
任何 JSON → Go 转换器的核心都是同一张映射表。拿一份典型的订单响应到本站 /convert/go 页面实测,贴入样本、勾选「生成 json 标签」,输出如下结构:
| JSON 值 | 生成的 Go 类型 | 说明 |
|---|---|---|
| 字符串 | string |
时间字符串多数仍是 string,见下文 time.Time |
| 整数 | float64 |
encoding/json 内部按 double 解析数字,见精度一节 |
| 小数 | float64 |
金额字段要换成 decimal 库或 int64 分单位 |
| true / false | bool |
无坑 |
| null | any |
单个 null 样本证明不了类型,保守回退 |
| 对象 | 命名 struct | 嵌套对象生成独立结构体 |
空对象 {} |
map[string]any |
无字段可观察,生成器不猜 |
| 数组 | []元素类型 |
元素按首个样本推断 |
| 混合类型 | any |
Go 没有联合类型,多类型字段回退 any |
// 输入样本
// {"id":"A-1029","items":[{"sku":"J-01","qty":2}],"coupon":null}
type Root struct {
ID string `json:"id"`
Items []Item `json:"items"`
Coupon any `json:"coupon"`
}
type Item struct {
Sku string `json:"sku"`
Qty int `json:"qty"`
}
三个观察点:嵌套对象 items 生成了独立的 Item 结构体并用切片引用;coupon 只出现过 null,生成器无法证明它以后是什么,回退 any;数字 qty 落成 int 或 float64——不同工具的策略不同,但都建立在「样本 = 全部事实」这个假设上。
json tag:原名、选项与三个易漏写法
tag 是转换器输出里信息密度最高的部分,也是最容易漏改的部分。规则来自 encoding/json 包文档:
Field int `json:"myName"` // 出现为键 myName
Field int `json:"myName,omitempty"` // 空值时整个字段省略
Field int `json:",omitempty"` // 保留默认字段名,只加选项
Field int `json:"-"` // 恒忽略,不编码不解码
Field int64 `json:"id,string"` // 数字编码进字符串,保精度
三个容易漏的写法:一是 json:",omitempty" 的前导逗号——只想省略空值、不想改键名时必须保留逗号,漏了逗号整个字段会被当成名为 ,omitempty 的键;二是 tag 里保留原始键名(user_id、html_url)而字段名用 Go 风格(UserID、HTMLURL),不写 tag 时 Go 直接按字段名匹配,接口返回 userId 就对不上;三是 json:"-" 之外还有 json:"-,",后者表示键名真的就叫 -。
指针:nil 才能区分「没有」和「零值」
Go 的零值机制让 int 和 string 无法表达「字段没出现」——0 和 "" 既可能是真实数据,也可能是没解析到。JSON 里同一个键有三种状态:出现且有值、出现且为 null、压根没出现。值类型只能覆盖第一种。
type Config struct {
Note string `json:"note,omitempty"` // 省略条件:恰好是 ""
Alias *string `json:"alias,omitempty"` // 省略条件:nil
Details *Meta `json:"details,omitempty"`
}
指针字段的零值是 nil,json.Unmarshal 遇到缺失键或 null 时保持 nil,omitempty 看到 nil 才省略。这就是为什么多数转换器都提供「嵌套对象用指针」开关:勾上之后嵌套结构体变 *Item,PATCH 请求里「字段没传」和「传了 null 想删掉」这两种语义才分得开。代价是每次使用前要判空——p.Address.Street 在 Address 为 nil 时直接 panic,这是 Go JSON 代码里最常见的运行时崩溃之一。
omitempty 省不掉的空结构体,omitzero 补的洞
omitempty 的官方定义是按值判定:false、0、nil 指针、nil 接口、长度为 0 的数组/切片/map/字符串。注意这份清单里没有「空结构体」。
type Order struct {
Meta Meta `json:"meta,omitempty"`
}
type Meta struct {
Version string
Build int
}
// Meta{Version: "1.0"} → "meta":{"version":"1.0","build":0}
// Meta{} → "meta":{} ← omitempty 没生效
结构体字段永远不会被 omitempty 省略——它在内存里是一个固定大小的容器,容器存在就不算「空」。修复方式是把字段改成 *Meta,nil 指针才会被省略。Go 1.24 起补了第二个开关 omitzero:按 Go 零值判定,类型有 IsZero() bool 方法时调用它,time.Time 的零值就是靠它才省得掉。Go 1.25 引入 encoding/json/v2 后语义进一步变化——v2 的 omitempty 按编码后的 JSON 判定(只有 null、""、{}、[] 算空),count: 0 会保留下来,迁移老代码时 bool 和数字字段上的 omitempty 要换回 omitzero 才是原来的意思。
数字都变 float64:大整数与精度的坑
encoding/json 的解码器在遇到没指定类型的数字时按 float64 处理,而 float64 只有 53 位有效尾数。JavaScript 里 9007199254740993 变成 9007199254740992 的经典案例,在 Go 里同样存在——只要目标字段是 float64 或者 any。
var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] 是 float64(9007199254740992),精度已经丢了
三条路:结构体字段明确写 int64,解码器会精确解析到 int64;必须走 any 时用 decoder.UseNumber(),让数字落成 json.Number 字符串类型再做转换;金额字段不要用任何浮点,改 int64 存分单位或 decimal 库。API 返回雪花 ID、订单号这类 64 位整数时,这一节是必查项。
time.Time 只认 RFC 3339
生成器看到 "2024-01-15T10:30:00Z" 会映射 time.Time,看到 "2024-01-15 10:30:00" 会留作 string——这不是偷懒,是 encoding/json 的硬约束:time.Time 实现了 UnmarshalJSON,内部固定按 RFC 3339 布局 2006-01-02T15:04:05Z07:00 解析,缺 T、缺时区、Z 后又带偏移量的写法全部报错:
parsing time "\"2022-07-27T14:16:00Z04:00\"" as
"\"2006-01-02T15:04:05Z07:00\"": cannot parse "04:00\"" as "\""
上游格式改不动时,标准修法是自定义类型包一层 time.Time,实现 UnmarshalJSON 尝试多种布局:
type CustomDate struct{ time.Time }
func (c *CustomDate) UnmarshalJSON(b []byte) error {
s := strings.Trim(string(b), `"`)
t, err := time.Parse("2006-01-02 15:04:05", s)
if err != nil {
t, err = time.Parse(time.RFC3339, s)
if err != nil {
return fmt.Errorf("invalid date format: %w", err)
}
}
c.Time = t
return nil
}
生成后的四步检查清单(怎么改)
生成器输出到生产代码之间隔着四步,逐条过一遍比事后排查便宜得多:
- 换掉 any 回退:搜一遍
any,每个回退字段回看三到五份真实样本,确认真实类型后落到具体类型或指针; - 数字宽度复核:ID、金额、计数器字段从 float64 改成 int64 / int32 / decimal,不确定宽度的按 int64 写;
- 可选性标注:数组内对象字段、PATCH 请求体、三方 API 的可空字段加指针或 omitempty/omitzero,nil 语义在这里定死;
- 编译与往返测试:
go vet过一遍,再写一个 Marshal→Unmarshal 往返用例锁住 wire 格式——这步能在 CI 里拦住未来 encoding/json 版本升级带来的行为漂移。
从样本到契约:转换器的边界(怎么避)
转换器回答的问题是「这个样本长什么样」,不是「这个接口永远长什么样」。多份竞品工具在文档里写得很坦白:一个样本证明不了生产变体,可选性、时间格式、枚举取值全部要人工复核。所以用法上要形成习惯——贴样本前先凑齐最能暴露差异的那几份响应(空列表、全字段、带 null 的),生成后把输出当草稿而不是成品。如果接口有自己的契约文档,用 JSON Schema 把约束显式化,再让生成代码对齐 Schema,比从样本反推可靠一个量级。跨语言的类型对齐问题,Java 侧的思路可以参考 JSON 转 Java 实体类的生成器实测,前端契约参考 JSON 转 TypeScript 接口;数字精度这条缝在每个语言里都换了个姿势出现,细节见 JSON 大数精度陷阱。
生成后还需要手工检查哪些字段?
至少四处:any 回退、数字宽度(float64 → int64)、可选字段的指针化、日期字段是 string 还是 time.Time。这四处都是「样本里看不出来」的生产变体,生成器不猜,人工必须补。
omitempty 加了为什么字段还在 JSON 里?
omitempty 只省略零值:false、0、""、nil、空切片。空结构体 {} 不是零值,所以不会被省略,把字段改成指针类型才能省掉;time.Time 零值要用 omitzero 而不是 omitempty。
大整数 ID 反序列化后为什么变了?
encoding/json 在没有明确类型时按 float64 解析,float64 只有 53 位尾数,超过 2^53 的整数会丢精度。字段写 int64,或用 UseNumber() 让数字保持 json.Number。
嵌套对象字段什么时候该用指针?
两种场景:字段可能整体缺失或为 null(nil 区分「没传」和「零值」),以及 PATCH 请求要区分「未提交」和「提交 null 删除」。普通响应结构里非可空字段用值类型更安全,指针带来的判空成本只在真正需要时付。