メインコンテンツまでスキップ
KISS TS版YAGNI TS版SoC TS版ADR TS版HC/LC TS版DRY TS版リファクタリング TS版テスタブル TS版TDD TS版エラーモデリング TS版レイヤー TS版MVC TS版依存関係ルール TS版DIP TS版DI TS版Is-a/Has-a TS版SOLID TS版GoFデザインパターン TS版Observer TS版CQS TS版状態機械 TS版不変条件 TS版Entity/VO TS版DDD TS版集約/境界 TS版ドメインイベント TS版モジュラーモノリス TS版ヘキサゴナル TS版クリーンアーキ TS版ACL TS版API Contract TS版SemVer TS版DbC TS版冪等性 TS版CAP定理 TS版Outbox TS版Saga TS版CQRS TS版イベントソーシング TS版BC TS版

第03章：部：冪等キー方式（10〜14章）🔑📦

この章のゴール🎯✨​

  • 「冪等（Idempotent）🔁」「重複排除（Dedup）🧾」「リトライ（Retry）🔄」がごちゃ混ぜにならないようにする
  • 会話で使うときに、1文で説明できるようになる✍️
  • 「だから“何を実装するべきか”」が自然に見えてくる👀✨

Concept

まずは超ざっくり3行まとめ📌😊​

  • 冪等🔁：同じ操作を何回やっても、（意図した）結果が同じになる性質
  • 重複排除🧾：同じものが2回来ても、2回目を“重複”として捨てる/無視する仕組み
  • リトライ🔄：失敗しそう・返事が来ないときに、もう一回やり直す行動（戦略）

この3つは、性質（冪等）・仕組み（重複排除）・**行動（リトライ）**で役割が違うよ〜☺️✨

1) 冪等（Idempotent）ってなに？🔁🧠​

✅ いちばん大事な定義（やさしめ）​

同じリクエストを何回送っても、サーバー上の“意図した効果”が1回と同じなら冪等だよ〜🔁✨ HTTPの世界でも「同じリクエストを複数回しても、意図した効果が同じ」って説明されることが多いです。(MDN Web Docs)

🧩 “意図した効果”ってどこまで？​

ここが混乱ポイント！😵‍💫 HTTPの仕様では、冪等は「ユーザーが要求した意味」に関するもので、たとえばログ記録みたいな“裏側の副作用”は毎回起きてもいい（＝それでも冪等と呼ぶ）という考え方が書かれています。(RFCエディタ)

つまり… 「DBの注文が2回増えない」は超重要だけど、 「アクセスログが2回増える」は気にしすぎなくてOKなことが多いよ🙆‍♀️📝

🌐 HTTPだとどれが冪等？​

HTTPメソッドには「だいたい冪等になりやすい子」がいるよ〜✨

  • GET/HEAD/OPTIONS：安全（read-only）で、冪等でもある👀
  • PUT/DELETE：安全ではない（状態は変える）けど、冪等になりやすい🗑️🔁
  • POST/PATCH：冪等が保証されないことが多い⚠️ こういう整理はMDNにもまとまってるよ。(MDN Web Docs)

2) 重複排除（Dedup）ってなに？🧾🧹​

✅ ひとことで​

**「同じものが来たら、2回目以降は“重複”として処理しない」**っていう仕組みだよ〜🧾✨

🎁 どこでよく出る？​

  • メッセージキュー📨（イベントが“最低1回配送”で重複しがち）
  • 決済💳（二重請求は絶対イヤ😱）
  • 通知📩（同じ通知が2回飛ぶのも困る）

🧠 例：SQS FIFOの「重複排除ID」​

AWSのSQS FIFOでは、同じ重複排除IDのメッセージは一定時間（例：5分）重複として扱われ、2回目は配送されない、みたいな仕組みがあるよ。(AWS ドキュメント) → これがまさに「Dedup（重複排除）」の代表例✨

⚠️ 注意：Dedupは「冪等」と同じじゃない！​

  • Dedup：“重複だと判断できたもの”を落とす仕組み
  • 冪等：落とさなくても、何回やっても結果が同じになる性質

Dedupは便利だけど、「どれが同じなの？」を判定するキーが超大事🔑✨ （この教材だと後半で出てくる “Idempotency-Key” とつながっていくよ〜🔁）(Stripe ドキュメント)

3) リトライ（Retry）ってなに？🔄⏱️​

✅ ひとことで​

**「うまくいかなかったっぽいから、もう1回やる」**がリトライ🔄 ネットワークやタイムアウトの世界では、リトライは日常茶飯事だよ〜😇🌧️

🎯 リトライが必要になる典型パターン​

  • 送った✅ → でも返事が来ない（通信切れ）🙃
  • サーバが混んでる（503とか）😵
  • 一時的な失敗（瞬間的なネット不調）📶

🌪️ リトライは“強くやる”と事故る​

みんなが同時にリトライすると、サーバがさらに混んで**リトライ嵐（retry storm）**になりがち😱🌪️ だから「待ってからリトライ」が基本で、AWSも バックオフ（待ち時間）＋ジッター（ランダム） を推してるよ。(Amazon Web Services, Inc.) Googleのドキュメントでも、（条件を満たすなら）指数バックオフ＋ジッターで再試行する方針が説明されてるよ。(Google Cloud Documentation)

4) 「再実行安全」って結局なに？🛡️🔁​

✅ ひとことで（超使える）​

再実行安全 = リトライしても壊れない状態だよ〜🛡️✨

再実行安全にする方法は、だいたい2系統👇

  1. 操作自体を冪等に設計する（何回やっても同じ結果）🔁
  2. 重複排除で2回目を落とす（同じものは処理しない）🧾

そしてここが重要⚡ 👉 リトライ（行動）をしてもいいのは、冪等 or Dedupがあるとき （ないと「二重作成」「二重決済」って事故る😱）

5) 3用語を一発で見分ける表🗂️✨​

用語何の話？主役うれしいことよくある誤解😵
冪等🔁性質操作の意味何回やっても結果が同じ「副作用が1ミリも起きない」ではない
重複排除🧾仕組み判定キー🔑2回目を弾ける「キーが雑でもOK」ではない
リトライ🔄行動/戦略クライアント一時失敗に強くなる「とりあえず連打」しがち

6) ミニケースで腹落ち🍰🧾💳​

ケース：注文作成API（ありがち😇）​

  • ユーザーが「注文する」ボタンを押す
  • でも通信が遅くて、画面が固まった…🥶
  • ユーザーがもう一回押す（or アプリが自動再送）🔄

A) 何も対策なし（危険⚠️）​

  • 注文が2つ作られる😱😱

B) Dedup（重複排除）あり🧾​

  • 「この操作のキー（例：idempotencyKey）が同じなら2回目は無視」
  • → 注文は1つのまま✅

C) 操作を冪等にする🔁​

  • たとえば「IDを決めて“同じIDの注文は上書き”」みたいに設計できると 「同じリクエストを2回送っても結果が同じ」になりやすいよ〜✨ HTTPでもPUT/DELETEは冪等になりやすい整理があるよ。(MDN Web Docs)

7) ミニ演習📝🌸（この章の必修！）​

演習①：1文ずつで説明しよう✍️​

次の3つを「中学生にも伝わる1文」で書いてみてね😊

  • 冪等🔁
  • 重複排除🧾
  • リトライ🔄

👉 目安：20〜35文字くらい（短いほど強い💪）

演習②：これはどれ？クイズ🎮✨​

次の文章は「冪等 / Dedup / Retry / 再実行安全」のどれ？（複数OK）

  1. 「同じ注文リクエストが2回来たら、2回目は処理しない」
  2. 「タイムアウトしたら、2秒→4秒→8秒…って待って再送する」
  3. 「同じDELETEを2回叩いても、最終的に消えてればOK」
  4. 「もう一回やっても二重決済にならない状態を保証したい」

8) AI活用（Copilot / Codex向け）🤖✨​

🧩 使えるお願いテンプレ（コピペOK）​

  • 「冪等 / Dedup / Retry の違いを、身近な例で3つずつ出して。各例に“どれに該当するか”も書いて」
  • 「“再実行安全”を満たすための設計パターンを、APIとキュー（イベント）で1つずつ説明して」
  • 「私が書いた1文定義を、もっとやさしい言葉に添削して：〔ここに自分の文〕」

✅ AIの答えをチェックするコツ🔍​

  • 「それって性質？ 仕組み？ 行動？」って分類し直す
  • 「2回実行したとき、DBの中身はどうなる？」って想像する🗃️👀
  • 「キーが違ったらどうなる？」を必ず聞く🔑❓

9) この章の理解チェック✅🔔​

✅ 合格ライン（これ言えたらOK！）​

  • 「冪等は性質、Dedupは仕組み、Retryは行動」って言える😊
  • 「Retryは“冪等 or Dedup”がないと事故る」って言える😱→🛡️
  • 「冪等でもログは増えうる」みたいな“意図した効果”の考え方がわかる🔁📝(RFCエディタ)

おまけ：決済の世界で超有名な話💳✨​

決済系APIでは 同じキーなら同じ結果を返す（同じ失敗も返すことがある）という設計が現実に使われてるよ。(Stripe ドキュメント) → 「冪等キー」と「結果保存（キャッシュ）」の発想につながるので、次の章以降でどんどん強くなる💪🔑