トランスポートマッピング

トランスポートマッピングの概要

GoaはHTTPとgRPCの両方をサポートしています。トランスポートマッピングDSLを使用すると、 サービスメソッドをこれらのプロトコルを介して公開する方法を定義できます。

HTTPトランスポート

HTTP DSLは、サービスメソッドを HTTPエンドポイントにマッピングする方法を定義します。これは3つのレベルで設定できます：

• APIレベル：グローバルなHTTP設定を定義
• サービスレベル：サービス全体のHTTPプロパティを設定
• メソッドレベル：メソッド固有のHTTP動作を指定

マッピングレベル

APIレベル

すべてのサービスに適用されるグローバルなHTTP設定を定義します：

API("bookstore", func() {
    HTTP(func() {
        Path("/api/v1") // すべてのエンドポイントのグローバルプレフィックス
    })
})

サービスレベル

サービス内のすべてのメソッドのHTTPプロパティを設定します：

Service("books", func() {
    HTTP(func() {
        Path("/books")     // サービス全体のパスプレフィックス
        Parent("store")    // パスのネストのための親サービス
    })
})

メソッドレベル

個々のメソッドの特定のHTTP動作を定義します：

Method("show", func() {
    HTTP(func() {
        GET("/{id}")       // HTTPメソッドとパス
        Response(StatusOK) // 成功レスポンスコード
    })
})

HTTPマッピング機能

HTTP DSLは、エンドポイントを設定するためのいくつかの機能を提供します：

1. パスパラメータ

   • ペイロードフィールドをURLパスセグメントにマッピング
   • パターンマッチングとバリデーションを使用
   • オプションパラメータをサポート

2. クエリパラメータ

   • ペイロードフィールドをクエリ文字列パラメータにマッピング
   • パラメータの型とバリデーションを定義
   • オプションパラメータを処理

3. ヘッダー

   • ペイロード/結果フィールドをHTTPヘッダーにマッピング
   • 必須およびオプションのヘッダーを設定
   • ヘッダーのフォーマットとバリデーションを定義

4. レスポンスコード

   • 結果を成功ステータスコードにマッピング
   • エラーレスポンスコードを定義
   • 異なるレスポンスシナリオを処理

gRPCトランスポート

gRPC DSLは、サービスメソッドをgRPCプロシージャにマッピングする方法を定義します。 HTTPと同様に、複数のレベルで設定できます。

gRPCの機能

1. メッセージマッピング

   • リクエスト/レスポンスメッセージ構造を定義
   • フィールドをprotobuf型にマッピング
   • フィールド番号とオプションを設定

2. ステータスコード

   • サービス結果をgRPCステータスコードにマッピング
   • エラーコードマッピングを定義
   • 標準的なgRPCステータスシナリオを処理

3. メタデータ

   • gRPCメタデータの処理を設定
   • ヘッダーをメタデータにマッピング
   • メタデータのバリデーションを定義

一般的なパターン

以下は一般的なトランスポートマッピングパターンです：

RESTfulリソースマッピング

Service("users", func() {
    HTTP(func() {
        Path("/users")
    })
    
    Method("list", func() {
        HTTP(func() {
            GET("/")              // GET /users
        })
    })
    
    Method("show", func() {
        HTTP(func() {
            GET("/{id}")          // GET /users/{id}
        })
    })
})

混合プロトコルサポート

サービスはHTTPとgRPCの両方をサポートできます：

Method("create", func() {
    // HTTPマッピング
    HTTP(func() {
        POST("/")
        Response(StatusCreated)
    })
    
    // gRPCマッピング
    GRPC(func() {
        Response(CodeOK)
    })
})

ベストプラクティス

トランスポート固有のエラー処理

各トランスポートプロトコルには、独自のエラー表現方法があります：

HTTPエラー

• 適切なステータスコードにマッピング
• レスポンスボディにエラーの詳細を含める
• 追加情報に標準ヘッダーを使用
• HTTPエラー規約に従う

gRPCエラー

• 標準的なgRPCステータスコードを使用
• 詳細なエラーメッセージを含める
• エラー詳細機能を活用
• gRPCエラーモデルに従う