idempotency とは何で、idempotency key はどうやって retry を安全にしますか?

Question

IT Interview Practice · Accepted Answer

**Idempotency** とは、操作を **複数回実行しても 1 回実行するのと同じ効果を持つ** ことを意味します。ネットワークが信頼できないため重要です: client がリクエストを送ってレスポンスが決して届かないとき、server が処理したかどうか判別できません。retry すれば、非 idempotent な操作は 2 回走るかもしれません。

## 問題

```text
Client ──POST /payments {$100}──▶ Server   ($100 を課金 ✓)
Client ◀────────X (timeout)────── Server   (response が失われる)
Client ──POST /payments {$100}──▶ Server   ($100 を再び課金 ✗ → $200!)
```

`GET`、`PUT`、`DELETE` は自然に idempotent なので、retry しても安全です。`POST` は **そうではない** — まさにここから重複課金や重複 order が生まれます。

## 解決策: idempotency key

client はその論理操作に対して **一意の key** (通常 UUID) を生成し、ヘッダで送ります。server は key を結果とともに保存します。同じ key が再び届いたら、再実行せずに **保存された** 結果を返します。

```http
POST /payments HTTP/1.1
Idempotency-Key: 5f2b8c1e-3a4d-4e6f-9c0b-1a2b3c4d5e6f
Content-Type: application/json

{ "amount": 100, "currency": "usd" }
```

```text
Idempotency-Key 付きリクエストを受け取ったときのサーバーのロジック:
  1. store (例: Redis/DB) で key を検索する。
  2. 見つかった → 保存済みの response を返す (再課金しない)。       ← retry のケース
  3. なければ → 処理し、(key → response) を保存してから返す。
  (並行 retry が二重実行しないよう、3 を transaction / lock で包む。)
```

retry 時の **同じ key** は同じ `200` と同じ payment を生みます — 顧客は 1 回だけ課金されます。これはまさに Stripe の API の動作です。

## なぜ重要なのか

この質問は、ハッピーパス向けに設計するエンジニアと、**失敗** 向けに設計する人 — production の信頼性の本質 — を分けます。分散システムはタイムアウトと部分的失敗が *必ず* 起こることを保証するので、副作用のあるエンドポイント — 支払い、order、送金 — には retry の物語が必要で、`POST` に「とにかく retry」は危険です。面接官は 2 部構成の洞察を聞きたいのです: 第一に、idempotency は *設計で組み込める* 性質であること (`PUT`/`DELETE` を自然に安全にし、できないときは `POST` に **idempotency key** を与える)。第二に、微妙な並行性の詳細 — 同時に届く 2 つの retry は両方実行してはならず、key チェックと書き込みに lock または unique 制約が必要 — です。これを正しくすることが、顧客に 1 回課金するか 2 回課金するかの違いであり、だからあらゆる本格的な支払い・商取引 API がこれを実装します。

問題

解決策: idempotency key

なぜ重要なのか

関連する質問