gin.Context の解説: 単なる Context 以上のもの

まず、gin.Context (または echo.Context) の設計目的を理解する必要があります。これは、単一のHTTPリクエストを処理するために使用される、Webフレームワークに固有のコンテキストオブジェクトです。その責任範囲は非常に広いです。

リクエストの解析: パスパラメータ (c.Param())、クエリパラメータ (c.Query())、リクエストヘッダー (c.Header())、リクエストボディ (c.BindJSON())を取得します。
レスポンスの書き込み: JSON (c.JSON())、HTML (c.HTML())を返し、ステータスコード (c.Status())を設定し、レスポンスヘッダーを書き込みます。
ミドルウェア間のデータ渡し: ミドルウェアチェーン間でデータを渡します (c.Set(), c.Get())。
フロー制御: ミドルウェアチェーンを中断します (c.Abort())。

これらの機能はすべて、HTTPプロトコルに密接に結びついていることがわかるでしょう。

では、context.Context はどこから来るのでしょうか？

重要な点: gin.Context は内部に標準の context.Context を含んでいます。

Ginでは、c.Request.Context() を介してそれを取得できます。この埋め込まれた context.Context は、前の記事で議論したすべてのコア機能、つまり キャンセル、タイムアウト、およびメタデータの伝播 を運びます。

func MyGinHandler(c *gin.Context) {
    // gin.Context から標準の context.Context を取得します
    ctx := c.Request.Context()

    // これで、この ctx を使用して、標準の context が意図するすべてのことを実行できます
    // ...
}

なぜこの分離が必要なのか？レイヤリングとデカップリング

これはまさに優れたソフトウェア設計の具現化です。それは 関心の分離 です。

HTTPレイヤー (コントローラー/ハンドラー): その責任は、HTTPの世界と対話することです。gin.Context を使用してリクエストを解析し、レスポンスをフォーマットする必要があります。
ビジネスロジックレイヤー (サービス): その責任は、コアビジネスロジック（計算、データベース操作、他のサービスの呼び出し）を実行することです。HTTPやJSONが何であるかを知るべきではありません。タスクの ライフサイクル (キャンセルされたかどうか) と、実行に必要なメタデータ (TraceIDなど) のみを気にします。したがって、ビジネスロジックレイヤーのすべての関数は、context.Context のみを受け入れる必要があります。

UserService が gin.Context に依存するとどうなりますか？

// 悪い設計: 密結合
type UserService struct { ... }
func (s *UserService) GetUserDetails(c *gin.Context, userID string) (*User, error) {
    // ...
}

この設計には、いくつかの致命的な欠陥があります。

再利用できない: いつか、gRPCサービス、バックグラウンドジョブ、またはメッセージキューコンシューマーで GetUserDetails を呼び出す必要がある場合、どうしますか？渡すための *gin.Context がなく、この関数を再利用できません。
テストが難しい: GetUserDetails をテストするには、苦労して *gin.Context オブジェクトをモックする必要があります。これは面倒で直感的ではありません。
不明確な責任: UserService はHTTPレイヤーの詳細を知っており、単一責任の原則 に違反しています。

ベストプラクティス: 明確な境界線と「引き渡し」

正しいアプローチは、HTTPハンドラーレイヤーで gin.Context から context.Context への「引き渡し」を完了することです。

ハンドラーを アダプター と考えてください。外部の世界 (HTTPリクエスト) の言語を内部の世界 (ビジネスロジック) の言語に翻訳します。

以下は、ベストプラクティスに従う完全なプロセスです。

1. 純粋なビジネスロジックレイヤー (サービスレイヤー) を定義する

その関数シグネチャは context.Context のみを受け入れ、Ginの存在を認識していません。

// service/user_service.go
package service

import "context"

type UserService struct {
    // 依存関係、例：データベース接続プール
}

func (s *UserService) GetUser(ctx context.Context, userID string) (*User, error) {
    // context を通して渡された TraceID を出力します
    if traceID, ok := ctx.Value("traceID").(string); ok {
        log.Printf("Service layer processing GetUser for %s with TraceID: %s", userID, traceID)
    }

    // 時間のかかるデータベースクエリをシミュレートし、キャンセル信号をリッスンします
    select {
    case <-ctx.Done():
        log.Println("Database query canceled:", ctx.Err())
        return nil, ctx.Err() // キャンセルエラーを上に伝播します
    case <-time.After(100 * time.Millisecond): // クエリ遅延をシミュレートします
        // ... 実際のデータベースクエリ: db.QueryRowContext(ctx, ...)
        log.Printf("User %s found in database", userID)
        return &User{ID: userID, Name: "Alice"}, nil
    }
}

2. HTTP処理レイヤー (ハンドラー/コントローラーレイヤー) を記述する

ハンドラーの責任は次のとおりです。

gin.Context を使用してHTTPリクエストパラメータを解析します。
gin.Context から標準の context.Context を取得します。
ビジネスロジックレイヤーで対応する方法を呼び出し、context.Context と解析されたパラメーターを渡します。
gin.Context を使用して、ビジネスロジックレイヤーからの結果をHTTPレスポンスにフォーマットします。

// handler/user_handler.go
package handler

import (
    "net/http"
    "my-app/service" // サービスパッケージをインポートします
    "github.com/gin-gonic/gin"
)

type UserHandler struct {
    userService *service.UserService
}

func NewUserHandler(us *service.UserService) *UserHandler {
    return &UserHandler{userService: us}
}

func (h *UserHandler) GetUser(c *gin.Context) {
    // 1. gin.Context を使用してパラメーターを解析します
    userID := c.Param("id")

    // 2. gin.Context から標準の context.Context を取得します
    ctx := c.Request.Context()

    // 3. ビジネスロジックレイヤーを呼び出し、「引き渡し」を完了します
    user, err := h.userService.GetUser(ctx, userID)
    if err != nil {
        // エラーがコンテキストのキャンセルによって引き起こされたかどうかを確認します
        if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
             c.JSON(http.StatusRequestTimeout, gin.H{"error": "request canceled or timed out"})
             return
        }
        c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
        return
    }

    // 4. gin.Context を使用してレスポンスをフォーマットします
    c.JSON(http.StatusOK, user)
}

3. `main.go` (または定義されたルーターレイヤー) ですべてを組み立てる

プログラムのエントリーポイントで、すべての依存関係を初期化し、必要に応じて「注入」します。

// main.go
package main

import (
    "my-app/handler"
    "my-app/service"
    "github.com/gin-gonic/gin"
)

// TraceID を追加する簡単なミドルウェア
func TraceMiddleware() gin.HandlerFunc {
   return func(c *gin.Context) {
      traceID := uuid.New().String()

        // context.WithValue を使用して、TraceID を持つ新しいコンテキストを作成します
        // 注: これは標準のコンテキストを変更する正しい方法です
      ctx := context.WithValue(c.Request.Context(), "traceID", traceID)

        // 元のリクエストコンテキストを新しいコンテキストに置き換えます
      c.Request = c.Request.WithContext(ctx)

        // オプションで、ハンドラーが直接使用するために gin.Context にコピーを保存します (必須ではありません)
        c.Set("traceID", traceID)

      c.Next()
   }
}

func main() {
    // ビジネスロジックレイヤーを初期化します
    userService := &service.UserService{}

    // HTTP 処理レイヤーを初期化し、依存関係を注入します
    userHandler := handler.NewUserHandler(userService)

    router := gin.Default()
    router.Use(TraceMiddleware()) // トレースミドルウェアを使用します

    router.GET("/users/:id", userHandler.GetUser)

    router.Run(":8080")
}

まとめ: このパターンを覚えておいてください

HTTPハンドラー (例: Gin)

使用されるコンテキストタイプ: *gin.Context
主な責任: HTTPリクエストを解析し、ビジネスロジックを呼び出し、HTTPレスポンスをフォーマットします。これは、gin.Context と context.Context の間の 引き渡しポイント です。

ビジネスロジックレイヤー (サービス)

使用されるコンテキストタイプ: context.Context
主な責任: コアビジネスロジックを実行し、データベース、キャッシュ、およびその他のマイクロサービスと対話します。Webフレームワークから完全に分離されています。

データアクセスレイヤー (リポジトリ)

使用されるコンテキストタイプ: context.Context
主な責任: db.QueryRowContext(ctx, ...)などの具体的なデータベース/キャッシュ操作を実行します。

このレイヤリングとデカップリングのパターンにより、非常に高い柔軟性が得られます。

移植性: service パッケージをそのまま使用して、他のGoプログラムで使用できます。
テスト可能性: UserService のテストは非常に簡単になります。複雑なHTTP環境をモックすることなく、context.Background() と文字列IDのみが必要です。
明確なアーキテクチャ: 各コンポーネントの責任は明確であり、コードの理解とメンテナンスが容易になります。