【実務・中級編】 APIゲートウェイにおけるレートリミット(Token Bucket/Leaky Bucket) – Web APIアーキテクチャ・データ連携実践ガイド

こんにちは。APIの設計図を見つめながら「いかに美しく、いかにタフなエンドポイントを作るか」を考えるのが何よりの好物であるシニアインフラアーキテクトだ。

これまでに幾度となく、世の中のバズや突然のトラフィック急増（いわゆる「サンダリングハードherd問題」やクローラーの暴走）によって、バックエンドのデータベースが悲鳴を上げ、APIサーバーが沈没していく現場に立ち会ってきた。そのたびに我々インフラ・バックエンドエンジニアが盾となり、APIの入口を守ってきたわけだが、その最前線に君臨するのが「APIゲートウェイにおけるレートリミット（流量制限）」である。

今回は、REST APIの美しさを守りつつ、インフラの命綱となるレートリミットの核心、特にToken Bucket（トークンバケット）とLeaky Bucket（リーキーバケット）のアルゴリズムの違い、そして現場で即座に使える実践的な実装・設定パターンを、ネットワークのパケットが駆け巡るリアルな挙動とともに紐解いていこう。

—

1. なぜAPIゲートウェイでトラフィックを制御すべきなのか

「レートリミットなんて、アプリケーションコードのミドルウェア層やフレームワーク側で書けばいいじゃないか」——そう考えるエンジニアは多い。しかし、大規模な分散システムやマイクロサービスアーキテクチャの現場において、各アプリケーションコンテナに制限ロジックを分散させるのは悪手だ。

認証の検証、ペイロードのパース、ビジネスロジックの実行、データベースへのコネクション確立。これらはすべてサーバーのリソースを消費する。悪意あるリクエストやバグったクライアントからの秒間数千件ものリクエストが、そのままアプリケーション層まで到達してしまっては、データベースプールの枯渇やOOM（Out of Memory）によるプロセス強制終了を引き起こす。

だからこそ、最前線に位置するAPIゲートウェイ（Nginx, Envoy, Kong, あるいはクラウドネイティブなAPI Gatewayなど）で、パケットの洪水を受け止める初期段階（L7のヘッダー検査とIP/トークン検証の直後）で門前払いする必要があるのだ。ここで弾かれたリクエストは、バックエンドのリソースを1バイトたりとも消費しない。これがインフラアーキテクトとしての鉄則である。

—

2. トラフィック制御の2大巨頭：Token Bucket vs Leaky Bucket

レートリミットのアルゴリズムにはいくつかの流儀があるが、実務で採用されるのは主にToken Bucket（トークンバケット）とLeaky Bucket（リーキーバケット）の2つだ。この違いを曖昧に理解していると、バーストトラフィックを許容したいのか、完全に平準化したいのかを見誤り、クライアント側に無用なエラー（429 Too Many Requests）を返すことになる。

Token Bucket アルゴリズム：バーストを許容する「賢いバケツ」

Token Bucketは、文字通り「トークンを溜めるバケツ」をイメージしてほしい。

1. バケツには最大容量（Capacity）が定められており、一定のレート（例：毎秒10個）で新しいトークンが補充される。
2. クライアントからリクエストが1件届くごとに、バケツからトークンを1つ消費（Consumption）する。
3. バケツにトークンが残っていれば、リクエストは即座に通過し、バックエンドへルーティングされる。
4. バケツが空の状態でリクエストが来ると、そのリクエストは即座に拒否される（またはキューイングされる）。

実務的なメリット：
Token Bucketの最大の強みは、「バースト（突発的なトラフィック）を許容できる点」にある。ユーザーが短時間に連打した数件のリクエストは、バケツに貯まっていたトークンを使って一気に処理できる。人間の操作するWebアプリやモバイルアプリでは、画面遷移時に複数リクエストが並列発行されるため、この「バースト耐性」がないと正常な操作ですら429エラーを踏むことになる。

Leaky Bucket アルゴリズム：トラフィックを完全に平準化する「穴あきバケツ」

一方のLeaky Bucketは、バケツの底に小さな穴が空いており、水（リクエスト）が一定の速度でポタポタと流れ落ちる構造をしている。

1. リクエストが来ると、いったんバケツに注がれる。
2. バケツから溢れ出た（Capacityを超えた）リクエストは破棄される。
3. バケツの底の穴から、完全に一定の速度でリクエストがバックエンドへ送り出される。

実務的なメリット：
バックエンドのシステムが非常に脆弱であり、秒間あたりの処理能力の限界が厳密に決まっている場合（例えば、秒間50件を超える処理を絶対に受け付けないレガシーなDBなど）に有効だ。トラフィックの波を綺麗にならし、一定の流速（Rate）で流し込むことができる。

—

3. 実践：Nginxを用いたToken Bucketの実装例

理論はこの辺りにして、現場のインフラストラクチャでどう設定するのかを見ていこう。今回は世界中のWebインフラで使われているNginxの ngx_http_limit_req_module を用いた、実用的なToken Bucket設定のサンプルコードを提示する。

以下の設定は、IPアドレス単位で秒間5リクエストを許可しつつ、最大10リクエストまでのバーストを許容（burst=10）、さらにクライアントを待たずに即座にエラーを返したい場合の nodelay オプションを付与したモダンな構成だ。

# /etc/nginx/nginx.conf の http コンテキストに定義
http {
    # 共有メモリゾーン（limit_zone）の定義
    # $binary_remote_addr をキーとして使用し、1MBの領域を確保（約16,000IP分）
    # rate=5r/s は「1秒あたり5個のトークンが補充される」ことを意味する
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=5r/s;

    server {
        listen 80;
        server_name api.example.com;

        location /v1/resources {
            # 定義した zone を適用
            # burst=10: 制限値を超えたリクエストを最大10個まで一時的に保持（バースト許容）
            # nodelay: バースト分のリクエストを遅延させず、即座に処理（またはエラー返却）する
            limit_req zone=api_limit burst=10 nodelay;

            # 制限超過時に返すHTTPステータスコードをカスタム（デフォルトは503）
            limit_req_status 429;

            # バックエンドのアプリケーションサーバーへプロキシ
            proxy_pass http://backend_cluster;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}

この設定のミソは、rate=5r/s と burst=10 の組み合わせだ。Nginxの内部実装では、トークンの補充間隔はミリ秒単位で計算されている。クライアントが突発的に15リクエストを同時に投げた場合、最初の5リクエストは即座に通過し、次の10リクエストはバースト枠で処理される。16番目以降のリクエストは容赦なく 429 Too Many Requests が返されることになる。

—

4. APIキー単位・ユーザー単位の制御とRedisの活用

単一のNginxサーバーであれば上記のメモリゾーンで足りるが、現代のWebサービスは複数のAPIゲートウェイ（ロードバランサー配下の複数台のNginxやEnvoy）で水平スケーリング（スケールアウト）しているのが普通だ。

ここで問題になるのが、「分散環境におけるレートリミットの状態共有」である。
サーバーAで3回、サーバーBで3回リクエストを受けた場合、合計6回になるが、各サーバーが自分のメモリだけでカウントしていると制限値（例：5回）をすり抜けてしまう。

これを解決するのが、高速なインメモリデータストアであるRedisを用いた分散レートリミットだ。

Python（FastAPI / Redis）による実装アプローチ

APIゲートウェイのカスタムプラグインや、軽量なミドルウェア層としてPython（FastAPIやStarlette）でRedisを用いたToken Bucket（あるいはFixed/Sliding Window）を実装する場合のロジックを見てみよう。

import time
from fastapi import FastAPI, HTTPException, Request, Response
import redis

app = FastAPI()
# Redis クライアントの初期化（本番ではコネクションプール等を適切に設定）
redis_client = redis.Redis(host='redis-cluster.internal', port=6379, db=0)

# レートリミット設定
LIMIT_REQUESTS = 10  # 許容リクエスト数
WINDOW_SECONDS = 60  # ウィンドウサイズ（秒）

@app.middleware("http")
async def rate_limit_middleware(request: Request, call_next):
    # APIキーまたはIPアドレスを識別子（Key）として取得
    # 実務では Authorization ヘッダーのBearerトークンやX-API-Keyをパースする
    api_key = request.headers.get("X-API-Key")
    if not api_key:
        # APIキーがない場合はIPアドレスフォールバック
        api_key = request.client.host

    redis_key = f"rate_limit:{api_key}"
    current_time = int(time.time())
    window_key = current_time // WINDOW_SECONDS
    
    # Redis のハッシュ構造またはZSET（Sorted Set）を使ったスライディングウィンドウ実装の簡略版
    # ここではシンプルなインクリメントと有効期限設定の例を示す
    pipe = redis_client.pipeline()
    bucket_key = f"{redis_key}:{window_key}"
    
    pipe.incr(bucket_key, 1)
    pipe.expire(bucket_key, WINDOW_SECONDS + 5)
    result = pipe.execute()
    
    request_count = result[0]

    if request_count > LIMIT_REQUESTS:
        # 制限超過時のハンドリング
        raise HTTPException(
            status_code=429,
            detail="Rate limit exceeded. Please try again later."
        )

    response: Response = await call_next(request)
    
    # レスポンスヘッダーに現在のレートリミット残量を付与（RFC 7231 / 標準プラクティス）
    response.headers["X-RateLimit-Limit"] = str(LIMIT_REQUESTS)
    response.headers["X-RateLimit-Remaining"] = str(max(0, LIMIT_REQUESTS - request_count))
    response.headers["X-RateLimit-Reset"] = str((window_key + 1) * WINDOW_SECONDS)

    return response

このコードでは、レスポンスヘッダーに X-RateLimit-Limit や X-RateLimit-Remaining を付与している点に注目してほしい。優れたAPIは、クライアントに対して「今自分があと何回リクエストを送れるのか」を常に透明性高く伝える義務がある。これがクライアント側の親切なリトライ制御（Exponential Backoffなど）を促し、結果的にサーバー側の負荷軽減に繋がるのだ。

—

5. 現場でハマる「落とし穴」とトラブルシューティングの極意

最後に、幾多の障害現場を潜り抜けてきたシニアエンジニアとして、レートリミット運用における「罠」をいくつか共有しておこう。

1. リバースプロキシ環境下でのIP偽装（X-Forwarded-Forの誤設定）
CloudflareなどのCDNやAWSのALB配下にAPIゲートウェイがある場合、クライアントのIPは X-Forwarded-For ヘッダーの先頭に含まれる。もしNginxなどの設定で $remote_addr をそのままレートリミットのキーにしてしまうと、「CDNのロードバランサーのIPアドレス」単位で全ユーザーの制限が共有されてしまい、数秒でサービス全体がロックアウトするという大惨事（自爆テロ）が起きる。必ず信頼できるプロキシからのヘッダーを正しくパースする設定（set_real_ip_from など）を先に行うこと。
2. 時刻同期（NTP）のズレ
Redis等の分散ストアで有効期限（TTL）やウィンドウ制御を行う場合、クラスタを構成する複数サーバー間のクロック（NTP）がズレていると、カウントの期限切れ計算が狂い、意図しないタイミングで制限がリセットされたりロックされたりする。インフラの基本だが、Chrony等による厳密な時刻同期は絶対条件だ。
3. 過剰なエラーログによるディスクフル
レートリミットに引っかかった秒間数万件のリクエストに対して、アクセスログやエラーログに詳細なスタックトレースを吐き出す設定にしていると、瞬く間にディスクが枯渇し、システム全体が共倒れになる。429 エラーのログはサンプリング（間引き）するか、ログレベルを適切に制御する配慮が必要だ。

—

まとめ

APIゲートウェイにおけるレートリミットは、単なる「アクセス制限の機能」ではない。それは、予測不可能なインターネットの荒波から、背後にある大切なインフラストラクチャとビジネスを守る「防波堤」である。

Token Bucketのバースト許容の美しさと、Leaky Bucketの平準化の堅実さ。そして分散環境を見据えたRedisやゲートウェイ層での適切なキー設計。これらを正しく理解し、コードと設定に落とし込むことで、はじめて「美しく、かつ強靭なREST API」が完成する。

さあ、次のデプロイでは、エンドポイントの美しさだけでなく、その門を叩くトラフィックの流量にも少しだけ思いを馳せてみてほしい。ネットワークのパケットの向こう側には、いつもユーザーと、そして君の守るべきシステムがあるのだから。

スポンサーリンク

コメント

タイトルとURLをコピーしました