문서가격블로그
문의하기
로그인무료로 가입하기
Back to Tech Articles

Goにおけるjson.RawMessageとカスタムUnmarshalJSONによる複雑なJSONのデコード

10월 26, 2025
# Misc

Takashi Yamamoto

Infrastructure Engineer · Leapcell

이 게시물은 English, 한국어 및 Deutsch에서도 볼 수 있습니다.
Cover of "Goにおけるjson.RawMessageとカスタムUnmarshalJSONによる複雑なJSONのデコード"

Goにおける複雑なJSON構造の解明

現代のソフトウェア開発の世界はJSONと深く結びついています。Web APIから設定ファイルまで、さまざまなシステム間でのデータ交換の共通言語となっています。Goのencoding/jsonパッケージは、JSONのマーシャリングとアンマーシャリングのための強力で便利なツールを提供しますが、開発者は、着信JSONの構造が動的、多態的、または単に標準的な自動デコードには複雑すぎるシナリオにしばしば遭遇します。そこで、JSON処理をマスターすることを目指すすべてのGo開発者にとって、json.RawMessageとカスタムUnmarshalJSON実装が不可欠なツールとなります。これらは、解析を延期し、生のデータを検査し、調整されたロジックを適用するための柔軟性を提供し、予期しないJSONに直面しても堅牢で回復力のあるデータ処理を保証します。

高度な解析のためのGo-JSONツールキット

高度なテクニックを掘り下げる前に、GoのJSON処理の基礎となるコアコンセプトを簡単に触れておきましょう。

JSON（JavaScript Object Notation）: 人間が読みやすく、機械が解析しやすいように設計された軽量のデータ交換フォーマットです。主な2つの構造、つまり名前/値のペアのコレクション（オブジェクト）と値の順序付きリスト（配列）に基づいています。

encoding/jsonパッケージ: Goの標準ライブラリパッケージで、JSONのエンコードとデコードを行います。json.Marshalやjson.Unmarshalなどの関数を提供し、Goの構造体をJSONに、またはその逆に変換します。

json.Unmarshal: JSONデータをGoの値にデコードする責任のある関数です。デフォルトでは、リフレクションを使用して、構造体のタグ（またはjson構造体タグ）に基づいてJSONフィールドを構造体フィールドに一致させます。

json.RawMessage: これが主役です。json.RawMessageはtype RawMessage []byteとして定義されています。これは、生の、解析されていないJSONデータを保持するバイトスライスです。Unmarshalがjson.RawMessageフィールドに遭遇すると、対応するJSON値を、さらにデコードしようとせずにバイトスライスとして扱います。これは、JSONオブジェクト、配列、文字列、数値、ブール値、またはnull全体を、構造体内の生バイトスライスとして保存できることを意味します。

json.Unmarshalerインターフェース: このインターフェースは単一のメソッド：UnmarshalJSON([]byte) errorを定義します。json.Unmarshalがこのインターフェースを実装する型に値をデコードすると、その特定のフィールド（または構造体レベルで実装されている場合はオブジェクト全体）の生のJSONデータでUnmarshalJSONメソッドが呼び出されます。これにより、開発者はデコードプロセスを完全に制御できます。

json.RawMessageの力

APIからイベントのリストが返されるシナリオを想像してみましょう。各イベントには、idやtimestampのような共通のフィールドがありますが、detailsフィールドはイベントのtypeに基づいて大きく異なります。

json.RawMessageなしでは、多くのオプションフィールドを持つ非常に大きな構造体を定義したり、型アサーションを使用して複数回Unmarshalを呼び出したりする必要があるかもしれませんが、これは面倒でエラーが発生しやすい可能性があります。

json.RawMessageがこれをどのように簡素化するかを以下に示します。

package main

import (
	"encoding/json"
	"fmt"
)

// Eventは一般的なイベント構造を表します。
type Event struct {
	ID        string          `json:"id"`
	Timestamp int64           `json:"timestamp"`
	Type      string          `json:"type"`
	Details   json.RawMessage `json:"details"` // 可変の詳細構造を保持するためのRawMessage
}

// LoginDetailsは「login」イベントの詳細を表します。
type LoginDetails struct {
	Username string `json:"username"`
	IPAddress string `json:"ip_address"`
}

// PurchaseDetailsは「purchase」イベントの詳細を表します。
type PurchaseDetails struct {
	ProductID string  `json:"product_id"`
	Amount    float64 `json:"amount"`
	Currency  string  `json:"currency"`
}

func main() {
	jsonBlob := `
	[
		{
			"id": "evt-123",
			"timestamp": 1678886400,
			"type": "login",
			"details": {
				"username": "alice",
				"ip_address": "192.168.1.100"
			}
		},
		{
			"id": "evt-456",
			"timestamp": 1678886500,
			"type": "purchase",
			"details": {
				"product_id": "prod-A",
				"amount": 99.99,
				"currency": "USD"
			}
		},
		{
			"id": "evt-789",
			"timestamp": 1678886600,
			"type": "logout",
			"details": "user logged out successfully" 
		}
	]
	`

	var events []Event
	err := json.Unmarshal([]byte(jsonBlob), &events)
	if err != nil {
		fmt.Println("Error unmarshaling events:", err)
		return
	}

	for _, event := range events {
		fmt.Printf("Event ID: %s, Type: %s\n", event.ID, event.Type)
		switch event.Type {
		case "login":
			var loginDetails LoginDetails
			if err := json.Unmarshal(event.Details, &loginDetails); err != nil {
				fmt.Println("  Error unmarshaling login details:", err)
				continue
			}
			fmt.Printf("  Login Details: Username=%s, IP=%s\n", loginDetails.Username, loginDetails.IPAddress)
		case "purchase":
			var purchaseDetails PurchaseDetails
			if err := json.Unmarshal(event.Details, &purchaseDetails); err != nil {
				fmt.Println("  Error unmarshaling purchase details:", err)
				continue
			}
			fmt.Printf("  Purchase Details: ProductID=%s, Amount=%.2f %s\n", purchaseDetails.ProductID, purchaseDetails.Amount, purchaseDetails.Currency)
		case "logout":
			var message string
			if err := json.Unmarshal(event.Details, &message); err != nil {
				fmt.Println("  Error unmarshaling logout message:", err)
				continue
			}
			fmt.Printf("  Logout Message: %s\n", message)
		default:
			fmt.Printf("  Unhandled event type, raw details: %s\n", string(event.Details))
		}
		fmt.Println("---")
	}
}

この例では、Event.Detailsはjson.RawMessageです。最初のjson.Unmarshalは共通フィールド（ID、Timestamp、Type）を解析し、detailsフィールドを生バイトスライスとしてそのまま残します。後でTypeフィールドを検査し、event.Detailsを正しい具体的な型に選択的にアンマーシャリングできます。このアプローチは非常に柔軟で、動的なJSON構造を扱う際のデータ損失やエラーを防ぎます。

カスタムUnmarshalJSONの実装

json.RawMessageは解析を延期するのに優れていますが、カスタムUnmarshalJSON実装はさらにきめ細やかな制御を提供し、デコード前、デコード中、またはデコード後JSONデータを操作したり、特定の条件に基づいて異なる型にデコードしたりできます。

UserのAgeが整数または文字列（例：「unknown」）として表現される場合を考えてみましょう。intを期待しているのにstringを受け取った場合、標準のUnmarshalは失敗します。

package main

import (
	"encoding/json"
	"fmt"
	"strconv"
)

type User struct {
	Name string
	Age  int // Ageは文字列「unknown」として来ても常にintにしたい
}

// CustomUnmarshalerUserはカスタムUnmarshalJSONを実装する構造体です。
type CustomUnmarshalerUser User // 無限再帰を避けるためのエイリアス

func (u *CustomUnmarshalerUser) UnmarshalJSON(data []byte) error {
	// Ageを生のメッセージとして含め、生のデータを保持するためのテンポラリ構造体を定義します。
	// これにより、`CustomUnmarshalerUser`に直接アンマーシャリングする場合の無限再帰を回避できます。
	// ケアを怠らなければ。json.RawMessageをAgeに使用すると、その型を検査できます。
	type TempUser struct {
		Name string          `json:"name"`
		Age  json.RawMessage `json:"age"` // ageを生のバイトとして保持
	}

	var temp TempUser
	if err := json.Unmarshal(data, &temp); err != nil {
		return err
	}

	u.Name = temp.Name

	// ここで、Ageフィールドをインテリジェントに解析します。
	if temp.Age == nil { // "age": null または欠落している場合
		u.Age = 0 // または何らかのデフォルト値
		return nil
	}

	// intとしてアンマーシャルを試みます。
	var ageInt int
	if err := json.Unmarshal(temp.Age, &ageInt); err == nil {
		u.Age = ageInt
		return nil
	}

	// intでの解析に失敗した場合、stringとしてアンマーシャルを試みます。
	var ageStr string
	if err := json.Unmarshal(temp.Age, &ageStr); err == nil {
		if ageStr == "unknown" || ageStr == "" {
			u.Age = 0 // "unknown"または空文字列を0として表します。
		} else {
			// 文字列形式の数値である場合は、文字列をintとして解析しようとします。
			parsedAge, err := strconv.Atoi(ageStr)
			if err == nil {
				u.Age = parsedAge
			} else {
				// 他の予期しない文字列値を処理するか、エラーを返します。
				return fmt.Errorf("could not parse age string '%s'", ageStr)
			}
		}
		return nil
	}

	return fmt.Errorf("age field is neither a number nor a recognized string: %s", string(temp.Age))
}

func main() {
	jsonUsers := []string{
		`{"name": "Alice", "age": 30}`,
		`{"name": "Bob", "age": "unknown"}`,
		`{"name": "Charlie", "age": "25"}`,
		`{"name": "David", "age": null}`,
		`{"name": "Eve"}`,
		`{"name": "Frank", "age": "thirty"}`,
	}

	for i, j := range jsonUsers {
		var user CustomUnmarshalerUser
		err := json.Unmarshal([]byte(j), &user)
		if err != nil {
			fmt.Printf("User %d: Error unmarshaling: %v\n", i+1, err)
			continue
		}
		fmt.Printf("User %d: Name: %s, Age: %d\n", i+1, user.Name, user.Age)
	}
}

この拡張例では、CustomUnmarshalerUserのUnmarshalJSONは、まずAgeがjson.RawMessageであるテンポラリ構造体を使用してトップレベルフィールドをアンマーシャルします。これにより、encoding/jsonがAgeの即時かつ潜在的に失敗する型アサーションを試みるのを防ぎます。その後、temp.Ageの生バイトを検査し、int、次にstringとしてアンマーシャルを試み、null、「unknown」、および文字列エンコードされた数値を適切に処理できます。これは強力なエラー回復とデータ標準化を示しています。

デフォルトのアンマーシャリング動作も望む、構造体のUnmarshalJSONを実装する際の一般的なパターンは、エイリアス型を定義することです。

type MyConfig struct {
    ... usual fields ...
    SpecialField string
}

type AliasMyConfig MyConfig // 無限再帰を避けるためのエイリアスを使用

func (mc *MyConfig) UnmarshalJSON(data []byte) error {
    var alias AliasMyConfig
    if err := json.Unmarshal(data, &alias); err != nil {
        return err
    }
    *mc = MyConfig(alias) // エイリアスから元の構造体へデータをコピー

    // デフォルトのアンマーシャリングの後、mc.SpecialFieldまたは他のフィールドにカスタムロジックを適用します。
    // 例：検証、変換。
    // E.g., validation, transformation.
    if mc.SpecialField == "oldvalue" {
        mc.SpecialField = "newvalue"
    }
    return nil
}

このエイリアスパターンにより、json.UnmarshalはAliasMyConfigのデフォルトのリフレクションベースのアンマーシャリングを使用でき、その後、カスタムロジックをその上に重ねることができます。

いつどちらを使用するか

  • json.RawMessage: 特定のフィールド（または複数のフィールド）の内部構造が変化し、コンテキストがそれを必要とするまで解析を延期したい場合に最適です。完全なカスタムUnmarshalJSONを全体の構造体に対して書くことなく、動的および多態的なJSONペイロードを優雅に処理するのに優れています。
  • カスタムUnmarshalJSON: 究極の制御を提供します。以下の場合に使用してください。
    • 単一フィールドに対して複数の形式でデータを受け取ることができる場合（例：Ageをintまたはstringとして）。
    • アンマーシャリング中にフィールドを検証する必要がある場合。
    • アンマーシャリング中に変換やデータのエンリッチメントを実行する必要がある場合。
    • 全体的な解析ロジックが、同じオブジェクト内の他のフィールドの値に依存する場合（例：Typeフィールドが別のDataフィールドの解析方法を決定する場合）。
    • 不明なフィールドを無視したり、高度なエラー回復を実行したりする必要がある場合。

結論

json.RawMessageとカスタムUnmarshalJSONは、Goのencoding/jsonパッケージにおける強力な機能であり、基本的なJSON解析を超えたものを提供します。json.RawMessageをマスターすることで、コンテキストがそれを要求するまで特定のフィールドの解析を延期し、動的で多態的なJSONペイロードを優雅に処理できるようになります。型変換、検証、または複雑な条件付きロジックのデコードプロセスを完全に制御する必要がある場合は、カスタムUnmarshalJSONメソッドを実装したjson.Unmarshalerインターフェースを実装することで、究極の柔軟性が得られます。これらのツールは、現実世界の、しばしば煩雑な、JSON APIと対話する堅牢なGoアプリケーションを構築するために不可欠です。これらは、スキーマのバリエーションに対して回復力があり、データ解釈において正確なコードを書くことを可能にし、アプリケーションがどのようなJSONデータにも自信を持って処理できるようになります。

Share this article

HackerNews

More Posts from Leapcell

Popular Posts