【実務・中級編】 APIゲートウェイにおけるサーキットブレーカーパターン – Web APIアーキテクチャ・データ連携実践ガイド

ネットワークの生存戦略：APIゲートウェイにおける「サーキットブレーカー」の真髄

インフラエンジニアとして現場に立っていると、深夜の呼び出しの多くが「特定のマイクロサービスが死んだせいで、後続のサービスが芋づる式に全滅した」という悲劇であることが多い。いわゆる「カスケード障害（連鎖障害）」だ。

この悪夢を止めるための最終防衛ライン、それがサーキットブレーカーパターンである。今日は、APIゲートウェイという「関所」で、どうやってパケットの氾濫を制御し、システム全体の崩壊を防ぐのか。その深淵に迫っていこう。

—

1. なぜ「ブレーカー」が必要なのか？

REST APIの設計において、各エンドポイントは独立しているべきだが、インフラ層ではリクエストが数珠つなぎになっている。もしバックエンドのサービスAが応答不能になったとき、ゲートウェイが律儀にタイムアウトまでリクエストを送り続けたらどうなるか。

1. ゲートウェイのコネクションプールが枯渇する。
2. 接続待ちのキューが溢れる。
3. ゲートウェイ自体のメモリが圧迫され、他の健全なサービスへの通信も道連れになる。

これを物理的な「ブレーカー」のように物理的に遮断するのがこのパターンの役割だ。

—

2. 状態遷移の美学：Closed, Open, Half-Open

サーキットブレーカーは、以下の3つの状態でパケットの運命を決定する。

Closed（正常）: 通常モード。リクエストは通過する。失敗率が閾値を超えると、ブレーカーが飛ぶ。
Open（遮断）: サービスは「死んでいる」と判定。リクエストをバックエンドに送らず、即座にエラー（またはフォールバック）を返す。
Half-Open（試行）: 一定時間後、サービスが回復したか確認するため、限定的にリクエストを通す。成功すれば Closed へ戻り、失敗すれば再び Open に戻る。

—

3. 実装の勘所：設定パラメータのチューニング

現場で最も重要なのは「どのタイミングで遮断するか」というパラメータ設計だ。

failureThreshold: 何回（または何%）失敗したら遮断するか。
slowCallDurationThreshold: 「遅い」とみなす閾値。遅延も立派な障害である。
waitDurationInOpenState: Open から Half-Open に移行するまでの待機時間。ここが短すぎると、サービスが完全に復旧する前に再び過負荷になり、障害が再発する。

設定例：Kong API Gateway (YAML形式)

多くのインフラエンジニアが愛用する Kong での設定例を見てみよう。

# Kongのプラグイン設定例
name: circuit-breaker
config:
  # 失敗率が50%を超えたら遮断
  error_threshold: 50
  # 遮断状態を30秒間維持
  break_duration: 30
  # 接続タイムアウト（5秒以上は遅いとみなす）
  connection_timeout: 5

—

4. フォールバック処理の設計

遮断されている間、クライアントには何を返すか？単に 503 Service Unavailable を返すのは最低限のマナーだ。さらに一歩進んで、可用性を維持するための「フォールバック」を実装すべきだ。

Python (FastAPI/requests) でのフォールバックイメージ

import requests
from requests.exceptions import RequestException

def call_backend_service(url):
    try:
        # 実際のリクエスト
        response = requests.get(url, timeout=2)
        response.raise_for_status()
        return response.json()
    except RequestException:
        # サービスが死んでいる時の「退避行動」
        return {
            "status": "fallback",
            "data": "キャッシュデータ、またはデフォルト値を返却"
        }

—

5. 現場のシニアからのTips：デバッグと運用

最後に、このパターンを運用する上での「泥臭い」注意点を伝授する。

1. タイムアウトの連鎖を断て: ゲートウェイのタイムアウト設定が、バックエンドのタイムアウトより「短く」なるように設計すること。ゲートウェイが待たされている間にバックエンドが応答を返せなくなっては本末転倒だ。
2. ログの相関性: Open 状態になった際、どのバックエンドが原因で遮断されたのかを X-Request-ID 等のトレーシングヘッダーで確実に追跡できるようにしておくこと。
3. モニタリング: circuit_breaker_state というメトリクスをPrometheusで監視せよ。Open になった瞬間、即座にアラートを飛ばす体制が必要だ。

curl での疎通確認

Half-Open 状態の挙動を確認したい時は、以下のようにループを回してステータスコードを監視する。

# 100回リクエストを送って、遮断されているか確認する
for i in {1..100}; do
  curl -o /dev/null -s -w "%{http_code}\n" http://api-gateway.internal/service-a/data
  sleep 0.1
done

—

まとめ

サーキットブレーカーは、単なるエラーハンドリングではない。「システム全体の生存率を最大化するためのインフラ戦略」だ。

完璧なサービスなど存在しない。だからこそ、失敗したときに「どう美しく転ぶか」を設計しておくことが、シニアエンジニアとしての腕の見せ所だ。APIゲートウェイの関所を堅牢にし、今日も明日の夜も安心して眠れるネットワークを構築してほしい。

何か疑問があれば、いつでも聞いてくれ。現場で培った「泥臭い知見」をまた共有しよう。