APIレート制限をClaudeと設計する

APIを公開するとき、レート制限は必須の実装です。しかし「トークンバケットにするかスライディングウィンドウにするか」「Redisのデータ構造はどう設計するか」と悩み始めると、設計だけで時間を取られがちです。Claude Codeを使えば、要件を伝えるだけで実装の骨格を素早く固められます。

Claudeにアルゴリズムの選定を相談する

まずはどのアルゴリズムを使うべきか、Claudeに相談してみましょう。以下のように入力します。

ユーザーごとに「1分間に100リクエスト」を制限するAPIレート制限を実装したい。
トークンバケットとスライディングウィンドウの違いをユースケースと合わせて説明して、
どちらが適しているか推薦してください。

Claudeはバースト許容度・実装複雑度・Redisの操作コストといった観点で比較した上で推薦してくれます。今回のような「短期間の集中アクセスをある程度許容したい」ケースでは、トークンバケットが適していると判断されることが多いです。

※トークン: AIがテキストを処理する最小単位。日本語は1文字あたり約1〜2トークン。使用量に応じてAPIコストが変わる。※API: Application Programming Interface の略。外部サービスとプログラム間でデータをやりとりするための接続口。

Redisを使ったトークンバケット実装を生成する

アルゴリズムが決まったら、実装を依頼しましょう。

Redisとluaスクリプトを使ったトークンバケットのレート制限をPythonで実装してください。
条件:
- キー名は "rate_limit:{user_id}"
- 最大トークン数: 100
- 補充レート: 毎秒1.67トークン（1分で100）
- アトミックな操作のためluaスクリプトを使う

するとClaudeは以下のようなコードを生成してくれます。

import redis
import time

RATE_LIMIT_SCRIPT = """
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local refill_rate = tonumber(ARGV[2])
local now = tonumber(ARGV[3])

local bucket = redis.call("HMGET", key, "tokens", "last_refill")
local tokens = tonumber(bucket[1]) or capacity
local last_refill = tonumber(bucket[2]) or now

local elapsed = now - last_refill
tokens = math.min(capacity, tokens + elapsed * refill_rate)

if tokens >= 1 then
    tokens = tokens - 1
    redis.call("HMSET", key, "tokens", tokens, "last_refill", now)
    redis.call("EXPIRE", key, 3600)
    return 1
else
    return 0
end
"""

r = redis.Redis()
script = r.register_script(RATE_LIMIT_SCRIPT)

def is_allowed(user_id: str) -> bool:
    result = script(keys=[f"rate_limit:{user_id}"],
                    args=[100, 100/60, time.time()])
    return result == 1

Luaスクリプトを使うことでRedis上でアトミックに処理でき、競合状態を防げます。

FastAPIミドルウェアとして組み込む

実装単体では動きません。Claudeに「FastAPIのミドルウェアとして組み込んで」と追加依頼すれば、RequestオブジェクトからユーザーIDを取得して429 Too Many Requestsを返す実装も即座に出てきます。

上のis_allowed関数をFastAPIのミドルウェアに組み込んでください。
ユーザーIDはJWTのsubクレームから取得してください。

設計の相談から実装・統合まで一気通貫でClaude Codeと進めることで、レート制限の実装を大幅に短縮できます。ぜひ試してみてください。

※ミドルウェア: リクエストとレスポンスの処理の間に挟まるプログラム。認証チェックやログ記録などに使う。※JWT: JSON Web Token の略。ユーザー認証情報をJSON形式でエンコードしたトークン。ヘッダーに付けてAPIを呼び出す際に使う。