Go言語の構造体タグ（jsonタグなど）の使い方と活用例を初心者向けにやさしく解説

1. 構造体タグとは？初心者向けの基本説明

1. 構造体タグとは？初心者向けの基本説明

構造体タグとは、構造体のフィールドに「このデータをどう扱うか」を伝えるためのメモのような役割を持つ仕組みです。バッククオート（`）で囲んで書くのが特徴で、特にjsonタグは、構造体とJSONを変換するときに使う「キー名（項目名）」を指定できます。難しそうに感じますが、タグがあることでデータの受け渡しがとてもスムーズになります。

たとえば、次のようにタグを書きます。

type Person struct {
    Name string `json:"name"`
}

この場合、「Nameというフィールドは、JSONに変換するときはnameというキー名を使ってください」という指定になります。タグがないと大文字のNameとして出力されるため、一般的なJSONと形式が合わず不便になることがあります。タグがあるだけで、他のサービスやAPIとも正しくデータをやり取りできるようになります。

2. jsonタグを使った構造体定義の基本例

2. jsonタグを使った構造体定義の基本例

まずは最小の例から確認しましょう。jsonタグは「JSONにするときのキー名」を明示するラベルです。タグを付けると、一般的な小文字のキーで出力でき、他のサービスやフロントエンドと噛み合いやすくなります。

type Person struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

上の定義を使ってJSONに変換すると、次のイメージになります。

{"name":"太郎","age":20}

もしタグを書かずに次のように定義した場合は、Goのフィールド名そのまま（先頭が大文字）のキーで出力されます。一般的なAPIの慣習（小文字スネークや小文字キャメル）とズレることがあるため、タグで合わせるのが無難です。

type PersonNoTag struct {
    Name string
    Age  int
}

この場合の出力イメージは次のとおりです。

{"Name":"太郎","Age":20}

3. json.Unmarshalとjson.Marshalの使い方

3. json.Unmarshalとjson.Marshalの使い方

ここでは「Goの構造体 ⇄ JSON文字列」の基本的な往復だけに絞って、最短のサンプルで流れをつかみます。json.Marshalは構造体からJSONを作る関数、json.UnmarshalはJSONから構造体へ入れ直す関数です。どちらも結果はバイト列とエラーで返ってくるので、はじめはエラーを画面に出して確認できる形で書いておくと安心です。タグ（例：json:"name"）は、JSON側のキー名を合わせる「橋渡し」の役目をします。

package main

import (
    "encoding/json"
    "fmt"
)

type Person struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func main() {
    // 1) 構造体 → JSON（json.Marshal）
    p := Person{Name: "花子", Age: 30}
    b, err := json.Marshal(p)
    if err != nil {
        fmt.Println("変換エラー:", err)
        return
    }
    fmt.Println(string(b)) // {"name":"花子","age":30}

    // 2) JSON → 構造体（json.Unmarshal）
    var p2 Person
    src := []byte(`{"name":"次郎","age":25}`)
    if err := json.Unmarshal(src, &p2); err != nil {
        fmt.Println("読み取りエラー:", err)
        return
    }
    fmt.Println("名前:", p2.Name, "年齢:", p2.Age)
}

実行イメージ：

{"name":"花子","age":30}
名前: 次郎 年齢: 25

4. omitempty や "-" を使った細かい制御

4. omitempty や "-" を使った細かい制御

タグには動きを調整するオプションを足せます。omitemptyは、そのフィールドが“ゼロ値”（空文字、0、false、nil など）のときに、JSONへ出力しない設定です。もう一つの"-"は「常に無視して出力しない」を意味します。不要な空項目を減らしたい、内部用の値を外へ出したくない、といったときに役立ちます。

type Profile struct {
    Name     string `json:"name"`
    Nickname string `json:"nickname,omitempty"` // 空なら出力しない
    Age      int    `json:"age,omitempty"`      // 0なら出力しない
    Secret   string `json:"-"`                  // 常に出力しない
}

たとえば、次の値をJSONにするとどうなるかを比べてみましょう。

入力値: Name="太郎", Nickname="たろ", Age=20, Secret="token"
出力:   {"name":"太郎","nickname":"たろ","age":20}

入力値: Name="太郎", Nickname="", Age=0, Secret="token"
出力:   {"name":"太郎"}

ポイントは「ゼロ値かどうか」を基準に含めるかを自動で切り替えられることです。空の項目が並ぶJSONは読み手にも機械にも扱いづらくなりがちです。omitemptyで必要な情報だけを出すようにしておくと、API連携やログの見通しが良くなります。内部用の値は"-"で確実に隠す、と覚えておくと安全です。

5. タグのオプション例：omitempty と "-" の実例

5. タグのオプション例：omitempty と "-" の実例

omitemptyは「値がゼロ値（空文字、0、false、nil など）のときはJSONへ出さない」ためのスイッチ、"-"は「常に無視して出力しない」ためのスイッチです。不要な空項目を減らしたり、外へ見せたくない内部情報を確実に隠したいときに使います。次のように最小構成で覚えるのがおすすめです。

type Person2 struct {
    Name     string `json:"name"`
    Nickname string `json:"nickname,omitempty"` // 空なら出さない
    Secret   string `json:"-"`                  // 常に出さない
}

入力: Name="太郎", Nickname="たろ", Secret="token"
出力: {"name":"太郎","nickname":"たろ"}

入力: Name="太郎", Nickname="", Secret="token"
出力: {"name":"太郎"}

ポイントは、表示したくない値は"-"で完全に除外し、あれば出す／なければ出さないという可変の項目はomitemptyで整えることです。これだけでJSONがすっきりし、読み手にも機械にも優しいデータになります。まずは「公開したい最低限の項目だけをタグで明示する」という使い方から始めると、実務のAPI連携でも迷いにくくなります。

6. 実利用例：APIで構造体タグを活用する

6. 実利用例：APIで構造体タグを活用する

Web APIのレスポンスやリクエストで、JSON形式のデータを送るとき、構造体タグが大活躍します。タグでキー名を合わせておけば、データが正しくマッチします。

7. 構造体タグの注意点とおすすめ設定

7. 構造体タグの注意点とおすすめ設定

• 大文字・小文字の一致：Goでは構造体のフィールド名は大文字から始めないと外部パッケージから見えません。
• タグの書き方：`json:"name,omitempty"`のように、タグはスペースで区切り可能です。
• 他のタグも使える：DB操作系ではdb:"id"など、他の仕組みでも使えます。

8. タグでコードが見やすくなる理由

8. タグでコードが見やすくなる理由

タグを使うと、構造体に「このフィールドはJSONでこう使ってね」という情報が明確に残るので、あとからコードを読む人にもわかりやすくなります。画像やテキストのラベルを貼るようなイメージです。

まとめ

まとめ

これまでの内容を振り返ると、構造体タグはとても便利な道具だと感じられたはずです。とくにGo言語の学習を始めたばかりの人は、構造体のフィールドにバッククオートで指定するという表記が少し不思議に見えたかもしれません。だけれども、実際には難しい魔法のような仕組みではなく、ひとつのフィールドに対して「このデータはこう扱ってね」と教えるちいさなメモのような役割を持っています。

さらに、実際の開発ではWebAPIなどの外部データとやり取りする場面がたくさんあります。外の世界では、データはほとんどの場合にJSONやXMLのような分かりやすい形式に変換されます。そんなとき、構造体タグを正しく扱うことで、送りたいデータを誤解なく受け取ってもらえるし、受け取ったデータをきれいな形で自分の構造体に流し込めます。人と人が会話するときに、言葉の意味を整理して伝えるようなものです。

そしてもうひとつ大切なのは、タグのオプションを覚えることです。とくに「omitempty」と「-」は、初心者ほど早い段階で身につけておきたい考え方です。値が空のときには無理に出力せずに見た目をすっきりまとめたり、まったく公開したくない情報を隠したりできます。

現場の開発では、構造体タグが設定されていないコードは読み手を不安にさせます。何が出てくるのか、どこが公開されるのか、どのキー名で外部とやり取りするのか分かりづらいからです。だけれども、タグがあるだけで、コードはすっきり整理され、チーム全体にとって読みやすい資料になります。見た目が整ったプログラムは、初心者の目にもやさしく映ります。

また、構造体タグはjson以外にも自由に使えます。データベース操作でつかう「db」タグ、画面表示を整えるためのカスタムタグなど、アイデア次第で使い道はたくさんあります。「Go言語はシンプルで読みやすい」という声が多い理由のひとつが、このタグの存在です。複雑な命令を増やすのではなく、フィールドにそっと情報を添えるという穏やかなアプローチは、プログラム全体の読み心地をやわらかくしてくれます。

それでも、慣れてしまえばタグは頼もしい味方になります。最初は小さな構造体からはじめ、次にAPIの受け渡しで使ってみて、最後に大きなプロジェクトでも自然に使えるようになると、Go言語の世界が一気に広がります。

JSONが苦手だと感じていた人でも、構造体タグを理解することで「なるほど、こうやって形が揃うんだ」と、すっきり納得できる場面が増えます。さらに、テストやバグ調査のときも、タグがあると原因を追いやすくなります。構造体タグを怖がらずに触ってみることで、プログラミングの世界が少しずつ心地よくなっていくでしょう。

サンプルプログラムで振り返ろう

package main

import (
    "encoding/json"
    "fmt"
)

type Product struct {
    Title  string `json:"title"`
    Price  int    `json:"price"`
    Secret string `json:"-"`
}

func main() {
    p := Product{Title: "りんご", Price: 120, Secret: "ひみつのなまえ"}
    b, _ := json.Marshal(p)
    fmt.Println(string(b))
}

この例では、Secretは出力されません。見せなくてよい値を隠すことで、余計な情報を外に出さずにすみます。たくさんの商品を扱うサービスでも役立ちますし、プライバシーを守る仕組みにもつながります。

この記事を読んだ人からの質問

この記事を読んだ人からの質問

プログラミング初心者からのよくある疑問／質問を解決します

Go言語の構造体タグとは何ですか？JSONタグとの違いはありますか？

Go言語の構造体タグとは、構造体のフィールドに追加情報を付けるための仕組みです。タグを書くことで、フィールドをJSON形式に変換するときのキー名を指定したり、外部システムとのデータ交換を正しく行うための設定を追加できます。特にJSONタグは、JSON形式への変換やJSONからの読み取りの際に、フィールド名とJSONキー名を合わせるために使われます。プログラミング初心者でも、構造体タグを使うとデータのやり取りがスムーズになり、Web APIや外部サービスとの通信でとても役に立ちます。

バッククオート記号で囲むと説明されていますが、なぜGo言語では構造体タグにバッククオートを使うのですか？

Go言語では、構造体タグをバッククオートで囲んで記述します。バッククオートを使う理由は、タグ全体を文字列として扱うためです。ダブルクオートではなくバッククオートを使うことで、タグの中にスペースやコロンを含めても問題なく扱える仕組みになっています。JSONタグだけでなく、DBタグやXMLタグなど複数のタグを同時に書きたい場合でも、バッククオートで囲むことで整った形のタグを記述できるため、プログラミングに慣れていない初心者でも安心して使うことができます。

JSONに変換したときに、構造体のフィールド名とJSONのキー名が違うのはなぜですか？

Go言語の構造体のフィールド名は大文字で始まる必要がありますが、JSONのキー名は小文字で書かれることが多いです。そのため、構造体そのままだと「Name」や「Age」といった大文字のままJSONに出力されます。そこで、JSONタグを付けることで「name」「age」のように小文字で出力でき、外部サービスとの連携やAPIの通信がスムーズになります。初心者はこの大小の違いで戸惑いやすいですが、JSONタグを正しく使えば統一感のあるデータ形式を実現できます。