JSON から Go Struct へ:ジェネレーターは骨組みまで、この4つは手で直す
要点:API レスポンスのサンプルを変換ツールに貼れば、json タグ付きの Go 構造体が10秒で手に入ります。しかし number は float64 になり、空の構造体は omitempty で消えず、time.Time は RFC 3339 しか受け付けません。型マッピング表、ポインタと omitzero の使い分け、生成後に必ず手で直すべき4ステップを解説します。

結論から言うと、変換ツールが10秒で出力する構造体はそのままコンパイルは通りますが、そのまま本番投入はできません。ジェネレーターが記述するのは「貼り付けた1つのサンプル」だけです。数字は float64 に落ち、オプション項目が自動でポインタになることはなく、omitempty は空の構造体を消せず、日付文字列の多くは time.Time になりません。この4つは貼り付けた後も手作業で補う必要があります。
API レスポンスを Go 構造体に書き写すのは純粋な機械作業です。しかし機械作業のコストは静かな場所に隠れています。フィールド名を一文字間違えてもコンパイルエラーは出ず、そのフィールドは永遠にゼロ値のまま。null の扱いを一つ間違えれば、本番のレスポンスに誰も予期していない
"note": nullが現れます。構造体の生成が解決するのは名前と型の整合問題であり、決して自動で揃わないのは2つだけです。サンプルの外にある変動要素と、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 の1サンプルでは型を証明できず、保守的にフォールバック |
| オブジェクト | 名前付き struct | ネストしたオブジェクトは独立した構造体に |
空オブジェクト {} |
map[string]any |
観察できる項目がなく、生成器は推測しない |
| 配列 | []要素型 |
要素型は最初のサンプルから推論 |
| 混在型 | any |
Go に Union 型はなく、複数型の項目は 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"`
}
観察点は3つ。ネストした items オブジェクトは独立した Item 構造体になり、スライスで参照されます。coupon は null しか出現したことがなく、将来何になるか証明できないため any にフォールバック。数字の qty は int または float64 になります。ツールによって方針は異なりますが、すべて「サンプル=全事実」という仮定の上に成り立っています。
json タグ:元の名前、オプション、見落としやすい3つの書き方
タグは変換ツール出力の中で情報密度が最も高く、修正漏れが起きやすい部分でもあります。規則は encoding/json の公式ドキュメントにあります。
Field int `json:"myName"` // キー myName として出現
Field int `json:"myName,omitempty"` // 空値なら項目全体を省略
Field int `json:",omitempty"` // 既定の項目名を維持し、オプションのみ
Field int `json:"-"` // 常に無視。エンコードもデコードもしない
Field int64 `json:"id,string"` // 数値を文字列に包んでエンコードし精度を保つ
見落としやすい書き方が3つあります。1つ目は json:",omitempty" の先頭カンマです。空値の省略だけをしたい時にキー名を変えたくなければカンマが必須で、カンマを落とすと項目全体が「,omitempty という名前のキー」として扱われます。2つ目はタグに元のキー名(user_id、html_url)を残し、Go 側の項目名は慣用的な大文字始まり(UserID、HTMLURL)にすることです。タグを書かないと Go は項目名でそのまま一致を試みるため、レスポンスのキーが userId なら静かにマッピング失敗します。3つ目は json:"-" のほかに json:"-," があり、後者は「キー名が本当に -」という意味です。
ポインタ:nil だけが「無い」と「ゼロ値」を区別できる
Go のゼロ値の仕組みでは、int と string は「項目が存在しない」ことを表現できません。0 と "" は実データかもしれず、単に解析できなかったのかもしれないからです。JSON の同じキーには3つの状態があります。値ありで出現、null で出現、そもそも出現しない。値型が扱えるのは最初の1つだけです。
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 を送って削除」が finally 分離されます。代償は使う前に毎回 nil チェックをすることです。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 からは2つ目のスイッチ omitzero が追加されました。Go のゼロ値で判定し、型が IsZero() bool を定義していればそれを呼びます。time.Time のゼロ値が省けるのはこのためです。encoding/json/v2(Go 1.25 で実験導入)では意味論がさらに変わり、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)。すでに精度が失われている
抜け道は3つ。構造体の項目を明示的に 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
}
生成後の4ステップ・チェックリスト
ジェネレーターの出力と本番コードの間には4つのステップがあります。事前に一度通す方が、後から障害を追うよりずっと安上がりです。
- any フォールバックを潰す:
anyを検索し、フォールバックされた各項目を3〜5件の実サンプルで裏取りし、具体的な型かポインタに落とす; - 数値の幅を再確認:ID・金額・カウンタを float64 から int64 / int32 / decimal へ。幅が不明なら int64 で書く;
- オプション性を明記:配列内オブジェクトの項目、PATCH ボディ、サードパーティ API の null 許容項目にポインタか omitempty/omitzero を付け、nil の意味論をここで確定させる;
- コンパイルと往復テスト:
go vetを通し、Marshal→Unmarshal の往復テストで wire フォーマットを固定する。encoding/json の将来のバージョンアップによる挙動のズレを CI で捕捉できます。
サンプルから契約へ:変換ツールの境界線
変換ツールが答えるのは「このサンプルはどう見えるか」であり、「このインターフェースが常にどうあるか」ではありません。競合ツールの多くは公式ドキュメントで率直に認めています。1つのサンプルでは本番の変動要素を証明できず、オプション性・時刻フォーマット・列挙値はすべて人間の確認が必要だと。だから使い方に習慣を作ります。貼り付ける前に差異を最も露呈させやすいレスポンス(空リスト、全項目あり、null を含む)を集め、生成後は出力を成果物ではなく草稿として扱います。インターフェースに契約ドキュメントがあるなら、JSON Schema で制約を明示化し、生成コードを Schema に合わせる方が、サンプルからの逆推測より一桁信頼できます。同じ問題の言語横断の話は、Java 側は Java エンティティ生成の実測記事、フロントエンド契約は TypeScript インターフェースへの変換を参照してください。数値精度の溝はすべての言語で別の顔をして現れます。詳細は JSON の大きな数の精度の落とし穴を参照。
生成後に手動で確認すべき項目は?
少なくとも4つです。any フォールバック、数値の幅(float64 → int64)、オプション項目のポインタ化、日付項目が string か time.Time か。いずれもサンプルからは見えない本番の変動要素であり、生成器は推測せず、人間が補う必要があります。
omitempty を付けたのに項目が JSON に残るのはなぜ?
omitempty が省略するのはゼロ値だけです。false、0、""、nil、空スライス。空の構造体 {} はゼロ値ではないため残り、項目をポインタ型に変えないと消えません。time.Time のゼロ値には omitempty ではなく omitzero が必要です。
大きな整数の ID がデシリアライズ後に変わるのはなぜ?
明示的な型がなければ encoding/json は数値を float64 で解析し、float64 の仮数は53ビットなので 2^53 を超える整数は精度を失います。項目を int64 にするか、UseNumber() で数値を json.Number として保持してください。
ネストしたオブジェクトの項目をポインタにすべきのはいつ?
2つのケースです。項目全体が欠落または null になりうる場合(nil が「未送信」と「ゼロ値」を区別する)、PATCH リクエストで「未提出」と「null を送って削除」を区別する必要がある場合。通常のレスポンス構造の null 非許容項目には値型の方が安全で、nil チェックのコストは本当に必要なときだけ払います。