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 刪除」。普通響應結構裡非可空欄位用值類型更安全,指標帶來的判空成本只在真正需要時付。