golang-context

コミュニティのデフォルト。 samber/cc-skills-golang@golang-context スキルを明示的に優先する会社のスキルがある場合は、そちらが優先されます。

Go context.Context のベストプラクティス

context.Context は、API 境界を越えて、またゴルーチン間で、キャンセルシグナル、期限、リクエストスコープの値を伝播するための Go の仕組みです。リクエストの「セッション」と考えてください。同じ作業単位に属するすべての操作を結び付けます。

ベストプラクティスの概要

1. HTTP ハンドラー → サービス → DB → 外部 API というリクエストのライフサイクル全体で、同じコンテキストを伝播します。新しいコンテキストを開始するリンクがあると、クライアントがいなくなった後も処理が続いてしまいます。
2. ctx を最初のパラメーターとして受け取り、ctx context.Context と命名します。この固定の位置により、コンテキスト対応 API を一目で判別でき、リンターによるチェックも可能になります。
3. コンテキストを構造体に格納せず、関数のパラメーターとして渡します。構造体はそれを受け取ったリクエストより長く存続するため、後続の呼び出しで、すでにキャンセル済みのコンテキストや別のリクエストに属するコンテキストが再利用されてしまいます。
4. nil コンテキストではなく context.TODO() を渡します。nil は最初の Done() または Value() 呼び出しでパニックを起こし、渡した呼び出し元から遠く離れた場所で問題になります。
5. WithCancel／WithTimeout／WithDeadline では、コンテキストとキャンセル関数の所有権を明示的に返すか移譲する場合を除き、すべての制御フロー経路で cancel() を呼び出します。cancel() を呼ばないと、子コンテキストは親に接続されたままになり、親が終了するまでタイマーがリークします。
6. context.Background() は、トップレベルのエントリーポイント（main、init、テスト）でのみ作成します。呼び出しチェーンの深い場所、特にリクエストの途中で作成すると、呼び出し元の期限やキャンセルから処理が切り離されます。これは以下に示す伝播の断絶です。
7. コンテキストが必要でもまだ存在しない場合は、プレースホルダーとして context.TODO() を使用します。意図的に見える Background() で隠すのではなく、後で修正する箇所を明示できます。
8. コンテキスト値のキーは非公開の型として宣言します。単なる string キーでは、複数のパッケージが "user" を使った場合に、互いの値を気付かれないまま上書きしてしまいます。
9. コンテキスト値にはリクエストスコープのメタデータのみを入れ、関数パラメーターは入れません。Value() で取得した値はコンパイル時の型情報を失い、関数シグネチャにも現れません。
10. 親リクエストの終了後も存続させるバックグラウンド処理を開始する場合は、context.WithoutCancel（Go 1.21 以降）を使用します。そうしないと、ハンドラーの終了時に、開始したばかりの監査ログやクリーンアップ処理がキャンセルされます。

コンテキストの作成

状況	使用するもの
エントリーポイント（main、init、テスト）	context.Background()
関数にコンテキストが必要だが、呼び出し元からまだ渡されていない	context.TODO()
HTTP ハンドラー内	r.Context()
キャンセルを制御する必要がある	context.WithCancel(parentCtx)
期限／タイムアウトが必要	context.WithTimeout(parentCtx, duration)

コンテキストの伝播：中核となる原則

最も重要なルールは、呼び出しチェーン全体で同じコンテキストを伝播することです。正しく伝播すれば、親コンテキストをキャンセルすると、下流のすべての処理も自動的にキャンセルされます。

// ✗ Bad — creates a new context, breaking the chain
func (s *OrderService) Create(ctx context.Context, order Order) error {
    return s.db.ExecContext(context.Background(), "INSERT INTO orders ...", order.ID)
}

// ✓ Good — propagates the caller's context
func (s *OrderService) Create(ctx context.Context, order Order) error {
    return s.db.ExecContext(ctx, "INSERT INTO orders ...", order.ID)
}

詳細解説

• キャンセル、タイムアウト、期限 — キャンセルの伝播について説明します。WithCancel は手動キャンセル、WithTimeout は指定時間の経過後の自動キャンセル、WithDeadline は絶対時刻による期限を設定します。並行コードでの待機パターン（<-ctx.Done()）、AfterFunc コールバック、親リクエストの終了後も継続する必要がある処理（監査ログなど）に使う WithoutCancel についても解説します。

• コンテキスト値とサービス間トレーシング — 安全なコンテキスト値のパターンを解説します。名前空間の衝突を防ぐ非公開のキー型、コンテキスト値（リクエスト ID、ユーザー ID）と関数パラメーターの使い分けについて説明します。トレースコンテキストの伝播では、OpenTelemetry のトレースヘッダー、ログ集約のための相関 ID、サービス境界をまたぐコンテキストのマーシャリングとアンマーシャリングを取り上げます。

• HTTP サーバーとサービス呼び出しにおけるコンテキスト — HTTP ハンドラーのコンテキストについて説明します。リクエスト単位のキャンセルに使う r.Context()、ミドルウェアとの統合、サービスへの伝播を解説します。HTTP クライアントのパターンでは、NewRequestWithContext、クライアントのタイムアウト、コンテキストを考慮したリトライを取り上げます。データベース操作では、期限を遵守するため、常に *Context 版（QueryContext、ExecContext）を使います。

相互参照

• → コンテキストを使ったゴルーチンのキャンセルパターンについては、samber/cc-skills-golang@golang-concurrency スキルを参照してください
• → コンテキスト対応のデータベース操作（QueryContext、ExecContext）については、samber/cc-skills-golang@golang-database スキルを参照してください
• → OpenTelemetry を使ったトレースコンテキストの伝播については、samber/cc-skills-golang@golang-observability スキルを参照してください
• → タイムアウトとレジリエンスのパターンについては、samber/cc-skills-golang@golang-design-patterns スキルを参照してください

リンターでの検出

コンテキストに関する多くの落とし穴は、リンター（govet、staticcheck）で自動的に検出できます。→ 設定と使い方については、samber/cc-skills-golang@golang-lint スキルを参照してください。