Go の struct 定義を貼り付けると、encoding/json がマーシャリング時に適用するのと同じルールで例の JSON ドキュメントを作ります。json:"..." タグの名前、- で隠したフィールド、,string オプション、エクスポートされない小文字のフィールド、フラット化される埋め込み構造体に対応しています。
Gin、Echo、net/http のリクエスト構造体から curl のボディを作るとき、gRPC-Gateway や REST ドキュメントのサンプルを用意するとき、タグが期待どおりのキーを生まないフィールドを見つけるときに便利です。
type Xxx struct { ... } の宣言を貼り付けます。type ( ... ) でまとめたブロックや、複数の構造体を一度に貼っても構いません。decimal.Decimal など)は null になります。curl -d、Postman のボディ、httptest を使ったハンドラーテストに使います。type Base struct {
ID string `json:"id"`
CreatedAt time.Time `json:"created_at"`
}
type Job struct {
Base
Queue string `json:"queue"`
Attempts int `json:"attempts,string"`
Labels map[string]string `json:"labels,omitempty"`
TimeoutSec *int `json:"timeout_sec,omitempty"`
Token string `json:"-"`
Done bool
lastErr error
}{
"id": "",
"created_at": "0001-01-01T00:00:00Z",
"queue": "",
"attempts": "0",
"labels": {
"key": ""
},
"timeout_sec": 0,
"Done": false
}埋め込みの Base は id と created_at を Job に直接追加し、,string タグの付いた Attempts は数値ではなく文字列 "0" になります。Token(タグ -)とエクスポートされない lastErr は除外され、タグのない Done は Go のフィールド名をそのままキーにしています。time.Time には Go のゼロ値 0001-01-01T00:00:00Z が入っています。
json:"name" タグをキーとして使い、タグがなければフィールド名をそのまま使います。json:"-" のフィールドとエクスポートされない小文字のフィールドは除外します。json:"-," は文字どおり - というキーでフィールドを残します。,string があると、数値や真偽値のフィールドは "0"、"false" のように文字列で包まれます。*int、*Profile)は指す先の型で埋め、type Status string のような定義型は基底型に従います。[]byte は Base64 の(空の)文字列、map[int]T は "0" をキーにし、time.Duration はナノ秒の整数 0、interface{}/any は null になります。Children []Node のような自己参照構造体は空の配列で止まります。匿名のネストした構造体フィールドにも対応しています。c.ShouldBindJSON(&req) でバインドする構造体を貼り付けてボディを生成し、httptest.NewRequest や curl でエンドポイントを呼び出せます。キーはタグから直接作られるので、バインドの食い違いが起きにくくなります。
json:"user_id" と json:"userId" のタグが混在していたり、タグを付け忘れて大文字の UserID キーが漏れていたりすると、出力を見ればひと目でわかります。
Go のレスポンス構造体から作った JSON をフロントエンドや Python の利用者に渡せば、JSON → TypeScript や JSON → Python などのツールでモデルに戻してもらえます。
omitempty のフィールドもサンプルには常に表示されます。実際のマーシャリングでは、ゼロ値のときに省かれます。nil のポインターは null としてマーシャリングされますが、サンプルには値が入った場合を表示します。MarshalJSON() を持つ型や、json.RawMessage の実際の中身は知りようがないため反映されません。omitzero のような新しいオプションや、encoding/json/v2 の挙動には対応していません。encoding/json はエクスポートされたフィールド名をそのまま使うので、Done bool は "Done" になります。Go でのデコードは大文字・小文字を区別せずに照合しますが、他の言語のクライアントは区別するので、タグを明示しておくほうが安全です。
time.Time が 0001 年になっているのはなぜですか?Go の time.Time のゼロ値は 0001-01-01 00:00:00 UTC で、RFC 3339 では 0001-01-01T00:00:00Z としてマーシャリングされます。そのため、他の → JSON ページの 1970 年の日付とは異なります。
json:",string" はどんなときに役立ちますか?主に、JavaScript では正確に表現できない大きな int64 の ID を文字列として送るためです。サンプルには "0" と表示されるので、クライアントにも文字列で届くことがはっきり伝わります。
JSON → Go struct のページを使ってください。その出力をこのページに戻せば、往復しても元のキーが保たれるかを手早く確認できます。