冪等性 — 同じリクエストが2回届く前提で設計する

What — 何が冪等で、何がそうでないか

冪等（idempotent） とは、同じ操作を何回実行しても、結果の状態が同じであることです。

PUT /users/123
{ "name": "山田", "email": "y@example.com" }
→ 1回目も5回目も、同じ状態になる

DELETE /users/123
→ 1回目: 削除される
→ 2回目: すでに無い（404 だが、状態は同じ）

UPDATE orders SET status = 'paid' WHERE id = 1
→ 何回やっても paid

冪等キーによる重複排除

作成系（POST）は本質的に冪等にできません。同じ注文を2回作ることは、意味のある操作でもあるからです。

そこで、クライアントが「同じ要求である」ことを示すキーを送る仕組みを使います。

CREATE TABLE idempotency_records (
  key           VARCHAR(64) PRIMARY KEY,   -- ← UNIQUE 制約が排他制御になる
  request_hash  VARCHAR(64),               -- 同じキーで違う内容が来たら弾く
  status        ENUM('processing', 'completed'),
  response_body JSON,
  created_at    DATETIME,
  expires_at    DATETIME
);

UNIQUE 制約そのものが排他制御として機能します。 アプリ側でロックを取る必要がなく、複数サーバー構成でも正しく動きます。

Why — なぜリトライは避けられないのか

分散システムには「2つの将軍問題」と呼ばれる原理的な限界があります。ネットワークで隔てられた2者が、確実に合意したことを確認する方法は存在しません。

• A が B にメッセージを送る
• B は受け取ったが、確認の返事が届いたか分からない
• A は返事が来ないが、B が受け取ったのか、そもそも届かなかったのか分からない
• 確認の確認を送っても、同じ問題が再帰する

したがって、送信側は「届いたか分からない」状態を必ず経験します。そのときに取れる選択は2つ。

1. 送らない（At most once） — 重複はしないが、失われる可能性がある
2. 再送する（At least once） — 失われないが、重複する可能性がある

「ちょうど1回（Exactly once）」は、ネットワーク層では実現できません。 実現できるように見えるものは、すべて「At least once + 受信側の重複排除」で作られています。

重複が発生する経路

冪等性が必要になるのは、明示的なリトライだけではありません。

このうち、フロントエンドで防げるのはボタン連打だけです。 他はすべてサーバー側で対処するしかありません。

演習 — まず自分で判断する

解説を読む前に、まず自分で判断してみてください。ここで一度詰まっておくと、 次の節の判断軸が「なるほど」ではなく「そう来たか」に変わります。