冪等性は『分散システム時代の最重要設計原則』
at-least-once 配信・リトライ・並行実行が常態化する現代では、冪等性(同じ操作を何度実行しても同じ結果)は前提です。本記事では編集部の視点で、実務での実装パターンを公開情報をもとに整理します。キューシステム設計 もご参考に。
3パターンの冪等化
(1) UPSERT：INSERT または UPDATE で同じ結果に。(2) 冪等キー：クライアントが一意ID を付与。(3) 状態機械：状態遷移を明示し再実行を吸収。(4) 条件付き書込：CAS / OCC。(5) 処理済みストア：実行履歴で重複排除。
API での冪等性
(1) GET/DELETE は本来冪等。(2) POST は非冪等：Idempotency-Key ヘッダで対応。(3) Stripe 流の実装：キーで結果をキャッシュ。(4) 24時間〜7日保管が一般的(公開情報をもとに)。(5) HTTP ステータス：再実行時も同じレスポンスを返す。REST API設計 も合わせて。
キュー処理での冪等性
(1) at-least-once 前提：必ず重複を考慮。(2) メッセージIDを主キーに。(3) 処理済みテーブル：UNIQUE 制約で弾く。(4) 副作用の集約：トランザクション境界に。(5) idempotency window：保管期間を設計。イベント駆動アーキテクチャ も合わせて。
バッチ処理での冪等性
(1) 処理範囲を明確化：時間帯/IDレンジ。(2) チェックポイント：中断点から再開。(3) マーカー：完了状態を永続化。(4) パーティション単位：失敗パーティションのみ再実行。(5) 監査可能性：いつ何件処理したか追跡。
分散DB での技法
(1) CAS (Compare-And-Swap)：楽観ロック。(2) condition expression：DynamoDB 等。(3) events と projection 分離：CQRS 文脈。(4) Outbox Pattern：DB + メッセージの整合性。(5) Saga：複数サービスをまたぐ補償。
失敗しがちなパターン
(1) at-least-once を at-most-once と勘違い。(2) 冪等キーなしの POST：二重決済。(3) 処理済みストアなし：再送で副作用倍増。(4) 状態遷移が時系列で壊れる。(5) テスト不在：再現困難な障害頻発。対策は、(1)at-least-once 前提、(2)Idempotency-Key 必須、(3)処理済みID保持、(4)状態機械の図示、(5)カオステスト、です。