[Goのはじめ方] Part25: JSONの扱い（encoding/json）

はじめに
Goのデータ構造からJSONへのエンコード (Marshal)
- フィールドタグでJSON出力をカスタマイズ
JSONからGoのデータ構造へのデコード (Unmarshal)
ストリーム処理 (Encoder/Decoder)
よくあるパターンと注意点
まとめ

はじめに

JSON (JavaScript Object Notation) は、Web APIや設定ファイルなど、様々な場面でデータを交換するために広く使われている軽量なデータ形式です。 Go言語には、このJSONデータを簡単に扱うための強力な標準パッケージ encoding/json が用意されています。

このパッケージを使えば、Goのデータ構造（構造体やマップなど）とJSON文字列を相互に変換することができます。このブログ記事では、encoding/json パッケージの基本的な使い方を学んでいきましょう！

Goのデータ構造からJSONへのエンコード (Marshal)

Goのデータ構造（例えば、構造体やマップ）をJSON形式のバイト列（[]byte）に変換することを「マーシャリング (Marshalling)」または「エンコード (Encoding)」と呼びます。これには json.Marshal 関数を使用します。

構造体をJSONに変換する例を見てみましょう。

package main
import (	"encoding/json"	"fmt"	"log"
)
type User struct {	ID int	Name string	Age int
}
func main() {	user := User{ID: 1, Name: "Gopher", Age: 10}	// 構造体をJSONバイト列にマーシャリング	jsonData, err := json.Marshal(user)	if err != nil {	log.Fatalf("JSONマーシャリングエラー: %s", err)	}	// バイト列を文字列として出力	fmt.Println(string(jsonData)) // 出力: {"ID":1,"Name":"Gopher","Age":10}
}

json.Marshal は、Goのデータ構造を受け取り、JSON形式のバイト列とエラーを返します。 Goの構造体のフィールド名は、デフォルトではそのままJSONのキー名になります。ただし、JSONとしてエンコードされるのはエクスポートされたフィールド（大文字で始まるフィールド）のみです。

フィールドタグでJSON出力をカスタマイズ

JSONのキー名をGoのフィールド名と違う名前にしたい場合や、特定の条件下でフィールドを省略したい場合があります。このような場合、構造体のフィールドに「タグ (Tag)」を付与することで、エンコード時の挙動をカスタマイズできます。

タグはバッククォート（`）で囲み、json:"..." の形式で指定します。

package main
import (	"encoding/json"	"fmt"	"log"
)
type Product struct {	ProductID int `json:"product_id"` // JSONキー名を "product_id" にする	Name string `json:"name"` // JSONキー名を "name" にする	Description string `json:"description,omitempty"` // 値が空ならJSONに含めない	Stock int `json:"-"` // このフィールドはJSONに含めない
}
func main() {	product1 := Product{ProductID: 101, Name: "Go T-Shirt", Description: "Official Go Gopher T-shirt", Stock: 50}	jsonData1, _ := json.Marshal(product1)	fmt.Println(string(jsonData1)) // 出力: {"product_id":101,"name":"Go T-Shirt","description":"Official Go Gopher T-shirt"}	product2 := Product{ProductID: 102, Name: "Go Sticker", Stock: 100} // Descriptionは空	jsonData2, _ := json.Marshal(product2)	fmt.Println(string(jsonData2)) // 出力: {"product_id":102,"name":"Go Sticker"} (descriptionはomitemptyにより省略)
}

よく使われるタグオプション:

json:"キー名": JSONでのキー名を指定します。
json:",omitempty": フィールドの値がGoのゼロ値（数値なら0, 文字列なら””, ポインタならnilなど）の場合、そのフィールドをJSON出力に含めません。
json:"-": このフィールドをJSONのエンコード・デコード対象から完全に除外します。
json:"キー名,omitempty": キー名を指定し、かつ値がゼロ値なら省略します。

マップやスライスも同様に json.Marshal でJSONに変換できます。

package main
import (	"encoding/json"	"fmt"
)
func main() {	// スライスのマーシャリング	langs := []string{"Go", "Python", "JavaScript"}	langsJson, _ := json.Marshal(langs)	fmt.Println(string(langsJson)) // 出力: ["Go","Python","JavaScript"]	// マップのマーシャリング	counts := map[string]int{"apple": 5, "banana": 10}	countsJson, _ := json.Marshal(counts)	fmt.Println(string(countsJson)) // 出力: {"apple":5,"banana":10}
}

JSONからGoのデータ構造へのデコード (Unmarshal)

JSON形式のバイト列をGoのデータ構造（構造体やマップなど）に変換することを「アンマーシャリング (Unmarshalling)」または「デコード (Decoding)」と呼びます。これには json.Unmarshal 関数を使用します。

package main
import (	"encoding/json"	"fmt"	"log"
)
type Point struct {	X int `json:"x"`	Y int `json:"y"`
}
func main() {	jsonInput := []byte(`{"x":10, "y":20}`)	var p Point	// JSONバイト列をPoint構造体にアンマーシャリング	// 第2引数には、変換結果を格納する変数へのポインタを渡す	err := json.Unmarshal(jsonInput, &p)	if err != nil {	log.Fatalf("JSONアンマーシャリングエラー: %s", err)	}	fmt.Printf("Point: X=%d, Y=%d\n", p.X, p.Y) // 出力: Point: X=10, Y=20
}

json.Unmarshal は、JSONバイト列と、変換結果を格納する変数へのポインタを受け取ります。 JSONのキーとGoの構造体フィールドのマッピングは、Marshal と同様にタグを考慮して行われます。大文字・小文字の違いは基本的に無視されますが、明確にするためにタグを使うことが推奨されます。

JSONの構造が事前にわからない場合や、柔軟に扱いたい場合は、map[string]interface{} を使うこともできます。 interface{} (またはエイリアスの any) は、任意の型の値を保持できます。

package main
import (	"encoding/json"	"fmt"	"log"
)
func main() {	jsonInput := []byte(`{"name": "Gopher", "active": true, "details": {"age": 10, "projects": ["Go", "Web"]}}`)	var data map[string]interface{} // any でも可	err := json.Unmarshal(jsonInput, &data)	if err != nil {	log.Fatalf("JSONアンマーシャリングエラー: %s", err)	}	// 値にアクセスするには型アサーションが必要	name := data["name"].(string)	active := data["active"].(bool)	details := data["details"].(map[string]interface{})	age := details["age"].(float64) // JSONの数値はデフォルトで float64 になることに注意	fmt.Printf("Name: %s, Active: %t, Age: %f\n", name, active, age)	// 出力: Name: Gopher, Active: true, Age: 10.000000
}

interface{} を使うと柔軟ですが、値を利用する際に型アサーションが必要になり、型安全性が低下する点に注意が必要です。 JSONの数値は、Goではデフォルトで float64 としてデコードされます。

ストリーム処理 (Encoder/Decoder)

ファイルやネットワーク接続など、データをストリームとして扱う場合は、json.Encoder と json.Decoder を使うのが便利です。これらは io.Writer や io.Reader インターフェースと連携します。

Encoder は、GoのデータをJSON形式で io.Writer（ファイル、HTTPレスポンスなど）に書き込みます。

package main
import (	"encoding/json"	"os"
)
type Config struct {	Server string `json:"server"`	Port int `json:"port"`
}
func main() {	cfg := Config{Server: "localhost", Port: 8080}	// 標準出力 (os.Stdout) に書き込むEncoderを作成	encoder := json.NewEncoder(os.Stdout)	encoder.SetIndent("", " ") // 人が読みやすいようにインデントを設定	// 構造体をJSONとしてエンコードして書き込む	err := encoder.Encode(cfg)	if err != nil {	log.Println("エンコードエラー:", err)	}	// 出力:	// {	// "server": "localhost",	// "port": 8080	// }
}

Decoder は、io.Reader（ファイル、HTTPリクエストボディなど）からJSONデータを読み取り、Goのデータ構造にデコードします。大きなJSONデータや、連続するJSONオブジェクトを効率的に処理するのに役立ちます。

package main
import (	"encoding/json"	"fmt"	"log"	"strings"
)
type Message struct {	User string `json:"user"`	Text string `json:"text"`
}
func main() {	// 連続するJSONオブジェクトを含む文字列	jsonStream := `	{"user": "Alice", "text": "Hello!"}	{"user": "Bob", "text": "Hi Alice!"}	`	reader := strings.NewReader(jsonStream)	// readerから読み取るDecoderを作成	decoder := json.NewDecoder(reader)	// ストリームが終わるまでJSONオブジェクトをデコード	for decoder.More() {	var msg Message	err := decoder.Decode(&msg)	if err != nil {	log.Fatal("デコードエラー:", err)	}	fmt.Printf("User: %s, Text: %s\n", msg.User, msg.Text)	}	// 出力:	// User: Alice, Text: Hello!	// User: Bob, Text: Hi Alice!
}

Marshal/Unmarshal はデータ全体をメモリに読み込むため、非常に大きなJSONデータを扱う場合は Encoder/Decoder を使う方がメモリ効率が良い場合があります。

よくあるパターンと注意点

キー名とフィールド名のマッピング: JSONでよく使われる snake_case や camelCase のキー名を、Goの PascalCase (or CamelCase) のフィールド名に対応させるには、構造体タグ json:"..." を使いましょう。

数値型: JSONの数値は、Goではデフォルトで float64 にデコードされます。整数として扱いたい場合は、デコード先の構造体のフィールドを int などにしておくか、json.Number 型を使って後で変換します。

package main
import (	"encoding/json"	"fmt"	"log"
)
func main() {	jsonInput := []byte(`{"value": 123}`)	var data map[string]json.Number // json.Numberを使う	err := json.Unmarshal(jsonInput, &data)	if err != nil { log.Fatal(err) }	// json.Numberからint64に変換	intValue, err := data["value"].Int64()	if err != nil { log.Fatal(err) }	fmt.Println("Int value:", intValue) // 出力: Int value: 123	// json.Numberからfloat64に変換	floatValue, err := data["value"].Float64()	if err != nil { log.Fatal(err) }	fmt.Println("Float value:", floatValue) // 出力: Float value: 123
}

Null値: JSONの null は、Goのポインタ型 (*string, *int など) や interface{}, map, slice の nil に対応します。値型（string, int など）のフィールドに null をデコードしようとするとエラーになることがあります。ポインタ型を使うか、omitempty タグを検討しましょう。
エラーハンドリング:Marshal や Unmarshal, Encode, Decode はエラーを返す可能性があります。不正なJSONデータや型変換のエラーなど、必ずエラーチェックを行いましょう。

未知のキー: デフォルトでは、Unmarshal は構造体に定義されていないJSONキーを無視します。未知のキーが存在する場合にエラーとしたい場合は、Decoder の DisallowUnknownFields() メソッドを使用します。

package main
import (	"encoding/json"	"fmt"	"log"	"strings"
)
type Simple struct {	Key string `json:"key"`
}
func main() {	jsonInput := `{"key": "value", "unknown_key": "ignored?"}`	reader := strings.NewReader(jsonInput)	decoder := json.NewDecoder(reader)	decoder.DisallowUnknownFields() // 未知のフィールドをエラーにする設定	var s Simple	err := decoder.Decode(&s)	if err != nil {	// ここでエラーが発生する	log.Printf("デコードエラー (未知のフィールドあり): %v", err)	} else {	fmt.Printf("Decoded: %+v\n", s)	}
}

まとめ

Goの encoding/json パッケージを使うことで、JSONデータのエンコード（マーシャリング）とデコード（アンマーシャリング）を簡単に行うことができます。

json.Marshal: Goのデータ構造をJSONバイト列に変換
json.Unmarshal: JSONバイト列をGoのデータ構造に変換
構造体タグ: JSONキー名のカスタマイズ、フィールドの省略、除外などに使用
json.Encoder / json.Decoder: ファイルやネットワークなどのストリーム処理に便利

Web APIとの連携や設定ファイルの読み書きなど、JSONは多くの場面で活用されます。このパッケージの使い方をマスターして、Goでの開発をさらに効率的に進めましょう！

次は、テンプレート処理（html/template）に進んで、動的なHTML生成について学びましょう！