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など）のときにJSONに含めない設定です。json:"nickname,omitempty"のように使います。

"-"を書くと、完全に無視する意味です。JSONにもフィールドが出ません。

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

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

type Person2 struct {
    Name     string `json:"name"`
    Nickname string `json:"nickname,omitempty"`
    Secret   string `json:"-"`
}

Nicknameが空ならJSONに出ず、Secretは常にJSONに出ません。

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や外部サービスとの通信でとても役に立ちます。