JSON 工具箱

JSON 转 Go Struct:生成器给骨架,这四件事要手补

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

进階约 6 分钟发布于 2026-11-22更新于 2026-11-22
把 JSON 样本生成 Go 结构体代码的转换工具封面

结论先行:转换器十秒钟给出的结构体可以直接进编译,但不能直接进生产。生成器只描述「你贴进来的那一个样本」——数字统一 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
}

生成后的四步检查清单(怎么改)

生成器输出到生产代码之间隔着四步,逐条过一遍比事后排查便宜得多:

  1. 换掉 any 回退:搜一遍 any,每个回退字段回看三到五份真实样本,确认真实类型后落到具体类型或指针;
  2. 数字宽度复核:ID、金额、计数器字段从 float64 改成 int64 / int32 / decimal,不确定宽度的按 int64 写;
  3. 可选性标注:数组内对象字段、PATCH 请求体、三方 API 的可空字段加指针或 omitempty/omitzero,nil 语义在这里定死;
  4. 编译与往返测试: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 删除」。普通响应结构里非可空字段用值类型更安全,指针带来的判空成本只在真正需要时付。

参考资料

相关文章

JSON 转 Java 类:生成器只给骨架,生产还要补的五件事

用生成器实测 JSON → Java 的默认输出——number 映射成 Double、嵌套对象变 static 内部类、不生成任何注解。对照三路英文圈的实战经验,给出金额精度、字段改名、泛型擦除、未知字段、日期与无参构造五个必须手工补齐的位置与可复制代码。

进阶约 10 分钟更新于 2026-11-04

JSON 转 TypeScript:接口、类型守卫与生成边界

从样例 JSON 生成 interface 只完成了一半:可选字段、null、联合类型、日期与大整数都要人工确认,生成结果本身也不做运行时校验。这篇给出生成、收敛与守卫的完整流程。

进阶约 9 分钟更新于 2026-11-04

大整数为什么变成 9007199254740992

超过 2^53-1 的整数在 IEEE 754 双精度里无法精确表示,JSON.parse 会静默把末位改掉。订单号、雪花 ID、金额分单位都踩过这个坑,正确解法是全程当字符串传。

进阶约 4 分钟更新于 2026-11-04