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