DocsPricingBlog
Contact Us
Log inSign up for FREE
Back to Tech Articles

Goにおける堅牢なHTTPクライアント設計

Oct 11, 2025
# Misc

Daniel Hayes

Full-Stack Engineer · Leapcell

This post is also available in English, 한국어, and Deutsch
Cover of "Goにおける堅牢なHTTPクライアント設計"

はじめに

現代の分散システムでは、サービス間でのHTTP通信が頻繁に行われます。Goのnet/httpパッケージは、これらのリクエストを行うための堅牢で効率的なhttp.Clientを提供しますが、生のまま使用しても本番環境の要求を満たせないことがよくあります。ネットワーク呼び出しは本質的に信頼性が低く、一時的なネットワークの問題、サーバーの過負荷、予期しない遅延によって失敗する可能性があります。適切な保護策なしでは、これらの失敗はシステム全体に広がり、連鎖的な障害やユーザーエクスペリエンスの低下につながる可能性があります。この記事では、Goの標準http.Clientをラップして、リトライ、タイムアウト、サーキットブレーカーといった不可欠な耐障害性パターンを組み込む方法を掘り下げます。これらの戦略を採用することで、アプリケーションの回復力と安定性を大幅に向上させ、逆境に直面しても信頼性の高い通信を確保できます。

コアコンセプト解説

実装の詳細に入る前に、議論するコアとなる分散システムパターンを明確にしましょう。

タイムアウト: タイムアウトとは、操作が完了するまでに許容される最大時間であり、それを超えると中止されます。その主な目的は、クライアントが応答を無期限に待機し続けるのを防ぎ、リソースを解放して、停止したリクエストのバックログを防ぐことです。一般に、接続タイムアウト（接続確立のため）とリクエストタイムアウト（リクエスト-レスポンスサイクルの全体のため）の2種類があります。

リトライ: リトライメカニズムは、失敗が一時的である可能性があると仮定して、失敗した操作を自動的に再試行します。ターゲットサービスへの過負荷を避け、回復する時間を与えるために、指数関数的なバックオフ戦略と最大試行回数でリトライを実装することが重要です。すべてのエラーがリトライ可能というわけではありません。例えば、400 Bad Requestはリトライしても魔法のように200になるわけではありません。

サーキットブレーカー: 電気のサーキットブレーカーに着想を得たこのパターンは、アプリケーションが失敗することが確実な操作を繰り返し実行しようとするのを防ぎます。サーキットブレーカーは、高率の失敗を検出すると「トリップ」（オープン）し、後続の呼び出しを試みずに即座に失敗させます。定義された間隔の後、それは「半開き」状態に遷移し、限られた数のテストリクエストを通過させます。これらが成功すると、サーキットは再び「閉じ」ます。失敗した場合は、オープン状態に戻ります。このパターンは、連鎖的な障害を防ぎ、失敗しているサービスに回復する時間を与えます。

堅牢なHTTPクライアントの構築

私たちの目標は、これらの耐障害性機能をシームレスに統合するhttp.Clientのデコレーターを作成することです。カスタムHTTPClientインターフェースとその実装を設計しましょう。

初期セットアップと基本クライアント

まず、HTTPクライアントの簡単なインターフェースを定義し、モックやテストを容易にします。

package resilientclient

import (
	"net/http"
	"time"
)

// HTTPClientインターフェースは、クライアントの契約を定義します
type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

// defaultClientは標準のhttp.Clientをラップします
type defaultClient struct {
	client *http.Client
}

// NewDefaultClientは新しいデフォルトクライアントを作成します
func NewDefaultClient(timeout time.Duration) HTTPClient {
	return &defaultClient{
		client: &http.Client{
			Timeout: timeout, // 基本的なリクエストタイムアウト
			Transport: &http.Transport{
				MaxIdleConns:        100,
				IdleConnTimeout:     90 * time.Second,
				TLSHandshakeTimeout: 10 * time.Second,
				// より多くのトランスポートオプションをここに追加できます
			},
		},
	}
}

// DoはdefaultClientのHTTPClientインターフェースを実装します
func (c *defaultClient) Do(req *http.Request) (*http.Response, error) {
	return c.client.Do(req)
}

ここで、http.Client.Timeoutを通じて基本的なリクエストタイムアウトを導入しました。これは、無期限の待機を防ぐための良い出発点です。

リトライの実装

リトライはDoメソッドをラップします。他のHTTPClientを引数として取るRetryClientを導入します。

package resilientclient

import (
	"bytes"
	"fmt"
	"io"
	"io/ioutil"
	"log"
	"net/http"
	"time"
)

// RetryConfigはリトライロジックのパラメータを保持します
type RetryConfig struct {
	MaxRetries    int
	InitialDelay  time.Duration
	MaxDelay      time.Duration
	// 特定のエラーをリトライしないようにするPredicate関数を追加
	ShouldRetry func(*http.Response, error) bool
}

// RetryClientはHTTPリクエストのリトライロジックを提供します
type RetryClient struct {
	delegate HTTPClient
	config   RetryConfig
}

// NewRetryClientはリトライ機能を持つ新しいクライアントを作成します
func NewRetryClient(delegate HTTPClient, config RetryConfig) *RetryClient {
	if config.MaxRetries == 0 {
		config.MaxRetries = 3 // デフォルトリトライ数
	}
	if config.InitialDelay == 0 {
		config.InitialDelay = 100 * time.Millisecond // デフォルト初期遅延
	}
	if config.MaxDelay == 0 {
		config.MaxDelay = 5 * time.Second // デフォルト最大遅延
	}
	if config.ShouldRetry == nil {
		config.ShouldRetry = func(resp *http.Response, err error) bool {
			if err != nil {
				return true // ネットワークエラーは通常リトライ可能
			}
			// サーバー側問題を示すステータスコード（例：5xx）
			return resp.StatusCode >= 500
		}
	}
	return &RetryClient{
		delegate: delegate,
		config:   config,
	}
}

func (c *RetryClient) Do(req *http.Request) (*http.Response, error) {
	var (
		resp *http.Response
		err  error
		delay = c.config.InitialDelay
	)

	for i := 0; i < c.config.MaxRetries; i++ {
		// 重要：ボディを持つリクエストの場合、最初の試行後に元のリーダーが消費されるため、
		// 各リトライでボディリーダーをリセットする必要があります。
		if req.Body != nil {
			// ボディがリセット可能か確認（例：*http.NoBody、bytes.Buffer、またはカスタムio.Seeker）
			if seeker, ok := req.Body.(io.Seeker); ok {
				_, seekErr := seeker.Seek(0, io.SeekStart)
				if seekErr != nil {
					return nil, fmt.Errorf("failed to seek request body: %w", seekErr)
				}
			} else {
				// シーク可能でない場合、ボディ全体をメモリに読み込み、新しいNopCloserを作成します。
				// これは通常、大きなペイロードには理想的ではありません。リトライが期待される場合は、
				// 元のボディに`bytes.Buffer`または`io.ReaderAt`の使用を検討してください。
				bodyBytes, readErr := ioutil.ReadAll(req.Body)
				if readErr != nil {
					return nil, fmt.Errorf("failed to read request body for retry: %w", readErr)
				}
				req.Body = ioutil.NopCloser(bytes.NewReader(bodyBytes))
			}
		}

		resp, err = c.delegate.Do(req)

		if c.config.ShouldRetry(resp, err) {
			log.Printf("Request failed (attempt %d/%d), retrying in %v. Error: %v", i+1, c.config.MaxRetries, delay, err)
			time.Sleep(delay)
			delay = time.Duration(float64(delay) * 2) // 指数関数的バックオフ
			if delay > c.config.MaxDelay {
				delay = c.config.MaxDelay
			}
			continue
		}
		return resp, err // 成功またはリトライ不可能なエラー
	}

	return resp, err // 全てのリトライに失敗した場合、最後のレスポンス/エラーを返す
}

リクエストボディに関する重要な考慮事項: ボディ（例：POST、PUT）を送信するリクエストをリトライする場合、req.Body（io.ReadCloser）は最初のDo呼び出し後に消費されます。後続のリトライでは、ボディは空になり、不正なリクエストにつながります。提供されたコードは、ボディがio.Seekerである場合はボディをシークバックするか、ボディ全体をメモリに読み込んで新しいNopCloserを作成することで、これを処理しようとします。大きなボディの場合、メモリへの読み込みは非効率的であるため、元のhttp.Requestボディをシーク可能（例：bytes.Bufferを使用）に設計することは、リトライが期待される場合に好ましいです。

サーキットブレーカーの実装

サーキットブレーカーには、成熟したライブラリであるsony/gobreakerを活用できます。このライブラリは、サーキットブレーカーパターンの堅牢な実装を提供します。

package resilientclient

import (
	"fmt"
	"net/http"
	"time"

	"github.com/sony/gobreaker"
)

// CircuitBreakerClientはサーキットブレークロジックでHTTPClientをラップします
type CircuitBreakerClient struct {
	delegate HTTPClient
	breaker  *gobreaker.CircuitBreaker
}

// NewCircuitBreakerClientはサーキットブレーカー機能を持つ新しいクライアントを作成します
func NewCircuitBreakerClient(delegate HTTPClient, settings gobreaker.Settings) *CircuitBreakerClient {
	if settings.Name == "" {
		settings.Name = "default-circuit-breaker"
	}
	if settings.Timeout == 0 {
		settings.Timeout = 60 * time.Second // 'open'状態から「semi-open」を試みるまでの待機時間
	}
	if settings.MaxRequests == 0 {
		settings.MaxRequests = 1 // 「semi-open」状態でのリクエストを1つ許可
	}
	if settings.Interval == 0 {
		settings.Interval = 5 * time.Second // カウントリセットまでの時間
	}
	if settings.ReadyToTrip == nil {
		settings.ReadyToTrip = func(counts gobreaker.Counts) bool {
			failureRatio := float64(counts.TotalFailures) / float64(counts.Requests)
			// リクエストが3回以上で、その60%が失敗した場合にトリップ
			return counts.Requests >= 3 && failureRatio >= 0.6
		}
	}

	return &CircuitBreakerClient{
		delegate: delegate,
		breaker:  gobreaker.NewCircuitBreaker(settings),
	}
}

func (c *CircuitBreakerClient) Do(req *http.Request) (*http.Response, error) {
	// Executeメソッドは、ブレーカーが閉じているか半開きの場合、提供された関数を呼び出します。
	// ブレーカーが開いている場合、gobreaker.ErrOpenStateを即座に返します。
	result, err := c.breaker.Execute(func() (interface{}, error) {
		resp, err := c.delegate.Do(req)
		if err != nil {
			// デリゲートからのエラー（ネットワークエラー、タイムアウトなど）は、失敗としてカウントされるべきです
			return nil, err
		}
		// サーキットブレイカーの場合、サーバー側エラー（5xx）も失敗と見なします
		if resp.StatusCode >= 500 {
			// 重要：リソースリークを防ぐため、エラー時にボディを閉じてください。
			// または、理想的には*http.Responseをinterface{}として返却し、
			// エラー時に呼び出し元がボディを処理できるようにするのがクリーンです。
			// ここでは簡単のため、失敗を示すことにします。
			return resp, fmt.Errorf("server error: %d", resp.StatusCode)
		}
		return resp, nil
	})

	if err != nil {
		if err == gobreaker.ErrOpenState {
			return nil, fmt.Errorf("circuit breaker is open: %w", err)
		}
		// サーバーエラーまたはネットワークエラーの場合は、元のエラーを返します。
		// エラーがフォーマットされたサーバーエラーだった場合、インターフェースとして返したレスポンスから抽出できます。
		if resp, ok := result.(*http.Response); ok && resp != nil {
			return resp, err // サーキットトリップ検討前に受信したレスポンスを返す
		}
		return nil, err
	}

	return result.(*http.Response), nil
}

gobreakerライブラリは、状態遷移（クローズド、オープン、半開き）と失敗カウントを自動的に処理します。gobreaker.Settingsで設定し、トリップや回復のしきい値を定義します。Executeメソッドは、実際のアクションを実行する関数を受け取り、interface{}, errorを返します。gobreakerライブラリは、返されたエラーを使用して操作が失敗したかどうかを判断します。

それらをチェーンする

このデコレーターパターンの利点は、これらのクライアントをチェーンできることです。典型的なセットアップは次のようになります：DefaultClientをラップしたRetryClientをラップしたCircuitBreakerClient。これにより、次のことが保証されます。

  1. 試行する前に、サーキットブレーカーはリモートサービスがダウンしている可能性を確認します。
  2. サーキットが閉じている（または半開き）場合、リクエストはリトライロジックに進みます。
  3. リトライロジックは、バックオフを伴う一時的な障害を処理します。
  4. 基盤となるdefaultClientは、ベースタイムアウトで実際のHTTPリクエストを処理します。
package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"time"

	"github.com/sony/gobreaker"
	"your_module_path/resilientclient" // resilientclientがサブパッケージにあると仮定
)

func main() {
	// 1. デフォルトタイムアウトでベースクライアントを作成
	baseClient := resilientclient.NewDefaultClient(5 * time.Second)

	// 2. リトライロジックでラップ
	retryConfig := resilientclient.RetryConfig{
		MaxRetries:   5,
		InitialDelay: 200 * time.Millisecond,
		MaxDelay:     10 * time.Second,
		ShouldRetry: func(resp *http.Response, err error) bool {
			if err != nil {
				return true // ネットワークエラーでリトライ
			}
			// 特定のサーバーエラーまたは多すぎるリクエストでのみリトライ
			return resp.StatusCode == http.StatusTooManyRequests || resp.StatusCode >= http.StatusInternalServerError
		}}
	retryClient := resilientclient.NewRetryClient(baseClient, retryConfig)

	// 3. サーキットブレーカーでラップ
	cbSettings := gobreaker.Settings{
		Name:        "ExternalService",
		MaxRequests: 3,                 // 半開き状態で3リクエスト許可
		Interval:    5 * time.Second,   // 5秒ごとにカウントリセット
		Timeout:     30 * time.Second,  // 半開き試行前に30秒間オープン
		ReadyToTrip: func(counts gobreaker.Counts) bool {
			failureRatio := float64(counts.TotalFailures) / float64(counts.Requests)
			return counts.Requests >= 10 && failureRatio >= 0.3 // 10リクエスト中30%が失敗した場合にトリップ
		},
	}
	resilientHttClient := resilientclient.NewCircuitBreakerClient(retryClient, cbSettings)

	// 使用例
	for i := 0; i < 20; i++ {
		req, err := http.NewRequest("GET", "http://localhost:8080/api/data", nil)
		if err != nil {
			log.Fatalf("Error creating request: %v", err)
		}

		log.Printf("Making request %d...", i+1)
		resp, err := resilientHttClient.Do(req)
		if err != nil {
			log.Printf("Request %d ERROR: %v", i+1, err)
			time.Sleep(500 * time.Millisecond) // コール間の遅延をシミュレート
			continue
		}

		defer resp.Body.Close()
		body, _ := io.ReadAll(resp.Body)
		log.Printf("Request %d SUCCESS: Status %d, Body: %s", i+1, resp.StatusCode, string(body))
		time.Sleep(500 * time.Millisecond)
	}
}

このmain関数は、resilientHttClientの構築と使用方法を示しています。通常、http://localhost:8080/api/dataを実際のサービスエンドポイントに置き換えます。

アプリケーションシナリオ

このパターンは、以下に非常に役立ちます。

  • マイクロサービス通信: 一時的なネットワーク障害や依存関係の一時的な過負荷にもかかわらず、サービス間呼び出しを安定させます。
  • 外部API連携: レート制限がかかったり、時々不安定になる可能性のあるサードパーティAPIを確実に利用します。
  • データベースインタラクション（間接的）: http.Clientは直接のデータベースインタラクション用ではありませんが、データベースのフロントエンドとなるHTTP APIをサービスが公開している場合、これらのパターンはデータベース関連のサービス障害から保護します。

結論

Goの標準http.Clientをリトライ、タイムアウト、サーキットブレーカーロジックでプログラム的にラップすることで、基本的なHTTPクライアントを本番環境対応の耐障害性コンポーネントに変換しました。このデコレーターパターンを使用したレイヤードアプローチは、懸念事項を分離し、コードをより保守可能で堅牢にします。これらのパターンを実装することは、単にエラーを処理するだけでなく、適切に劣化・回復する堅牢なシステムを構築することであり、困難な分散環境でも継続的な運用を保証します。堅牢性はオプションではなく、信頼性の高い分散システムの基本です。

Share this article

HackerNews

More Posts from Leapcell

Popular Posts