JSON→Go構造体変換

JSONオブジェクト(またはJSON配列)を貼り付けると、対応するGoのstruct定義とjsonタグを自動生成します。

JSONからGoのstructを起こす

APIのレスポンスをGoで受け取るには、そのJSONに対応するstructとjsonタグを書く必要があります。フィールドが数個なら手で書けますが、入れ子が深くなると、型名を考えながら階層をたどる作業がそのまま手間になります。 このツールはJSONを貼り付けるだけで、ネストした構造も含めてstruct定義一式を生成します。

ただし生成結果は「その1件のサンプルから推測した型」であることを意識してください。 サンプルに現れなかったキーは当然出てきませんし、値が null だったフィールドはGoに対応するプリミティブが無いため interface{} になります。配列の要素がすべてオブジェクトの場合は各要素のキーを統合し、一部にしか無いキーには omitempty を付けます。実運用のstructに仕上げる際は、この推測の跡を実際のAPI仕様と突き合わせて直すのが前提です。

変換の手順

  1. JSONを貼り付ける オブジェクトでも配列でもかまいません。APIレスポンスをそのまま貼れます。
  2. ルート型の名前を決める 初期値は Root です。ネストした型の名前はプロパティ名をパスカルケースにして自動で付きます。
  3. 生成されたstructを確認する jsonタグ付きの定義が階層順に並びます。
  4. コピーして整える gofmt を通し、interface{} になった箇所やポインタにすべき箇所を実際の仕様に合わせて直します。

使いこなすためのヒント

  • 配列の要素がすべてオブジェクトの場合、各要素のキーをマージして1つのstructを生成します。一部の要素にしか存在しないキーには自動的に omitempty を付与します。
  • ルート型の名前は初期値「Root」からお好みの名前に変更できます。ネストしたstructの型名は、そのプロパティ名をPascalCase化して自動生成されます。
  • JSONのnullはGoにネイティブなnull許容プリミティブが無いため interface{} として出力されます。厳密に扱いたい場合はポインタ型への置き換えを検討してください。
  • 生成結果はインデントを揃えた簡易フォーマットで出力されますが、貼り付け後に gofmt を通すとプロジェクトの標準スタイルに揃えられます。
  • API レスポンスのサンプルJSONをそのまま貼り付ければ、Goのレスポンス用struct定義のたたき台を素早く用意できます。

活用シーン

APIクライアントを書き始めるとき

ドキュメントのサンプルレスポンスを貼れば、受け口のstructのたたき台がすぐ手に入ります。

設定ファイルを読み込むとき

JSON形式の設定を扱う際、その構造をそのまま型に写せます。

外部サービスの仕様を読み解くとき

入れ子の深いJSONは、structの形にすると階層が把握しやすくなります。

テストのフィクスチャを用意するとき

実レスポンスから型を起こしておくと、モックを書くときの取り違えが減ります。

Goの型変換の用語

struct
Goで複数のフィールドをまとめる型です。JSONのオブジェクトに対応します。
jsonタグ
フィールドの後ろに書く json:"user_id" の形の注釈で、Goのフィールド名とJSONのキー名の対応を指示します。
omitempty
jsonタグに付ける指定で、値が空(false・0・空文字列・nil・長さ0のスライスやマップ)のときに出力から省きます。 構造体型のフィールドはゼロ値でも省かれない点と、null許容を意味するわけではない点に注意が必要です。
interface{}
任意の型を受ける型です。JSONの null や型が揺れる値はここへ落ちるため、生成後に見直すべき箇所の目印になります。
パスカルケース
UserId のように各単語の頭を大文字にする記法です。Goではこの大文字始まりが、パッケージ外へ公開するという意味も持ちます。
ポインタ型
*string のように書く型です。値が無い状態と空文字を区別したい場合に使います。

よくある質問

手作業でstructを書き起こすと、フィールド名の変換ミスやjsonタグの記入漏れが起きやすく、ネストしたオブジェクトが深い場合は特に時間がかかります。自動生成することでこれらのミスを防ぎ、実装にかかる時間を大幅に短縮できます。

JSONのキー(snake_caseやcamelCase)を先頭大文字のPascalCaseに変換し、Goでエクスポート可能なフィールド名にします。元のJSONキーはjsonタグ(json:"元のキー")としてそのまま保持されるため、エンコード・デコードは問題なく行えます。日本語など大文字にできない文字で始まるキーにはFieldを前置し(例: 名前 → Field名前)、変換後に同じ名前になるキー(user_idとuserIdなど)には末尾に連番を付けて、Goでコンパイルできる重複しない名前にします。

null値はinterface{}型として出力されます。また配列内の一部要素にしか存在しないキーは自動的にomitempty付きのjsonタグになりますが、Go自体の型はゼロ値を取るだけなので、必要に応じてポインタ型への置き換えも検討してください。

JSON上の数値に小数点か指数(1.0や1e3)が含まれていればfloat64、どちらも無ければintと判定します。Goのencoding/jsonは小数点や指数を含む数値を整数型へ読み込めないため、このように書き分けています。また64bit環境のintの範囲(約±9.2×10の18乗)を超える整数は、読み込みが失敗しないようfloat64にします。ただしfloat64では桁が丸まるため、大きなIDなどを正確に扱う必要がある場合はjson.Numberやstringへの置き換えを検討してください。

Goにはユニオン型が無いため、同じキーでも要素によって型が食い違う場合はinterface{}にフォールバックします。実際の型はランタイムで型アサーションを使って判定する必要があります。
ツールくん

余談ですが ― Goのstructとjsonタグという設計

Go言語は静的型付け言語であり、JSONを扱う際は標準ライブラリのencoding/jsonパッケージがstructのフィールドとjsonタグの対応関係を見てエンコード・デコードを行います。外部APIのレスポンス構造をstructとして手作業で書き起こすのは、フィールドが増えるたびに手間が増える定型作業であり、多くのGoプロジェクトで繰り返されてきました。

このツールはサンプルJSONの構造を解析し、対応するstruct定義とjsonタグを自動生成することで、この定型作業を省力化します。同種のツールとしては複数言語への型変換に対応したquicktypeが知られていますが、手元のAPIレスポンスをそのまま貼り付けて素早くGoのstructを得たいだけの場面では、単機能ツールの手軽さにも利点があります。

Goには構造体のフィールドをオプショナルにする言語機能が無いため、JSON側で欠落し得るフィールドはjsonタグにomitemptyを付けるか、ポインタ型(*string等)にしてゼロ値と「値が存在しない」状態を区別する設計が一般的です。生成されたstructはあくまで構造からの機械的な推論であり、nullable判定やAPIの将来的な変更を見越した設計は、実際の仕様書と照らし合わせて手動で調整するのが実務上の定石とされています。