Skip to main content
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版

冪等性（Idempotency）教育コンテンツ：24章 詳細アウトライン

（TypeScript / VS Code / Windows / AI導入済み前提）✨🔁💻

対象：TypeScript初級〜中級／冪等性は初めて／設計は超入門😊🌸

第1部：冪等性の“感覚”をつかむ（1〜5章）🧠✨​

1章：冪等性ってなに？まずは超ざっくり🙂📌​

  • 🎯ゴール：冪等性を一言で言える（＆例が出せる）

  • ✅内容

    • 「同じ操作を何回しても結果が壊れない」ってどういうこと？🔁
    • “壊れる”とは？（二重作成/二重決済/二重送信）😱

  • 📝ミニ演習：身近な「連打で事故る例」を3つ書こう🖊️

  • 🤖AI活用：AIに「冪等性が必要な場面を5つ」出してもらう（自分で良し悪し判定）✅

2章：なぜ冪等性が必要？現実はリトライだらけ😇🌧️​

  • 🎯ゴール：冪等性がないと起きる事故を説明できる

  • ✅内容

    • タイムアウト→ユーザー再送→二重実行の流れ📨📨
    • 「成功したけど返事が届かなかった」問題🙃

  • 📝演習：タイムアウト時の“最悪シナリオ”を図にする🖼️

  • 🤖AI：事故パターンを図解テキストにしてもらう🧩

3章：冪等 / 重複排除 / 再実行安全…言葉の整理🧹📚​

  • 🎯ゴール：会話で用語が混ざらない

  • ✅内容

    • 冪等（Idempotent）🔁
    • 重複排除（Dedup）🧾
    • リトライ戦略（Retry）🔄

  • 📝演習：それぞれの違いを「1文ずつ」書く✍️

  • 🤖AI：自分の文章を“やさしく添削”してもらう🧑‍🏫

4章：冪等性が必要な操作ランキング🏆😆​

  • 🎯ゴール：「ここは冪等必須！」を判断できる
  • ✅内容：決済💳／注文確定🧾／通知📩／在庫📦／クーポン🎫
  • 📝演習：自分の作ったサービス（仮）で“冪等が要る場所”をチェック✅
  • 🤖AI：あなたの想定サービスに対して「冪等リスク点検」してもらう🔍

5章：最小題材を決めよう（教材のミニアプリ設計）🍰🧑‍💻​

  • 🎯ゴール：以降ずっと使う“ミニ注文API”の全体像がわかる

  • ✅内容

    • テーマ：注文作成 + 支払い確定（っぽい） をミニで
    • まずはDBなし（メモリ）→後でDB想定へ🪄

  • 📝演習：APIエンドポイント案を書いてみる（/orders など）📝

  • 🤖AI：OpenAPI風の叩き台を生成してもらう📄

第2部：HTTPとAPI設計の冪等性（6〜9章）🌐🧩​

6章：HTTP入門：安全（Safe）と冪等（Idempotent）🚦​

  • 🎯ゴール：Safe/Idempotentの感覚を掴む
  • ✅内容：GETは参照👀、副作用の有無って大事
  • 📝演習：SafeとIdempotentを例で分類🗂️
  • 🤖AI：分類クイズを作ってもらう🎮

7章：HTTPメソッド別の冪等性（GET/PUT/DELETE）🔁​

  • 🎯ゴール：PUT/DELETEを冪等にしやすい理由が言える
  • ✅内容：PUTは“置き換え”／DELETEは“消す”＝同じ結果になりやすい
  • 📝演習：PUTで「同じIDに同じ内容」を2回送る例を書く✍️
  • 🤖AI：例をTypeScriptの擬似コードにしてもらう🧠

8章：POSTが危ない理由（作成＝増える問題）😵​

  • 🎯ゴール：POSTが二重作成しやすい流れが説明できる
  • ✅内容：ユーザー連打、通信再送、クライアント再試行
  • 📝演習：二重注文が起きるタイムラインを書こう⏱️
  • 🤖AI：事故フローを“会話形式”にしてもらう（理解しやすい）💬

9章：APIで「冪等です」を約束する設計（入口の決め方）📜✨​

  • 🎯ゴール：API契約として冪等を“表に出す”感覚を持つ
  • ✅内容：ヘッダー/ボディ/設計書（約束）への載せ方
  • 📝演習：「冪等キー必須」のAPI仕様文を書く🖊️
  • 🤖AI：仕様文の言い回しを整えてもらう✍️

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

10章：冪等キー（Idempotency-Key）ってなに？🔑🔁​

  • 🎯ゴール：冪等キーの仕組み（1回目保存→2回目同じ返し）がわかる
  • ✅内容：同じキー＝同じ処理として扱う
  • 📝演習：リクエスト例（header付き）を書く🧾
  • 🤖AI：curl例を作ってもらう（WindowsでもOK）🪟

11章：冪等キーは誰が作る？（クライアント生成 vs サーバー生成）🙋‍♀️🆚🖥️​

  • 🎯ゴール：メリデメ比較ができる

  • ✅内容

    • クライアント生成：再送しやすい👍
    • サーバー生成：漏洩対策しやすい場合も🔒

  • 📝演習：自分ならどっち？理由を書く📝

  • 🤖AI：想定ケース別おすすめを提案させて、自分で選ぶ✅

12章：冪等キー設計のルール（スコープ/TTL/再利用禁止）⏳🧷​

  • 🎯ゴール：キー設計で事故らない

  • ✅内容

    • スコープ：userId単位など👤
    • TTL：無限保存しない🕒
    • 再利用禁止（別内容に同じキーを使わない）🚫

  • 📝演習：キーのDBテーブル案を紙に書く🗃️

  • 🤖AI：テーブル案のレビューをさせる🔍

13章：結果を保存して返す（レスポンスキャッシュ型冪等）📦📤​

  • 🎯ゴール：“同じキー→同じレスポンス”方式を理解
  • ✅内容：成功レスポンスを保存して返す王道
  • 📝演習：保存する項目（status/body/createdAt）を決める🧾
  • 🤖AI：保存スキーマ（型）をTypeScriptで生成🧱

14章：保存先の選択（メモリ/DB/Redis）🧰✨​

  • 🎯ゴール：要件に合わせて選べる
  • ✅内容：落ちると消える😇／永続化は強い🗄️／Redisは速い⚡
  • 📝演習：小規模/中規模/大規模で選択を書き分ける📝
  • 🤖AI：想定トラフィックを入れて相談する📈

第4部：同時実行と“二重実行防止”（15〜17章）⚔️🧵​

15章：同時実行入門：レースコンディションって何？🏁😵‍💫​

  • 🎯ゴール：「同時に来ると壊れる」が腑に落ちる
  • ✅内容：2リクエストが“同時に通る”と…？
  • 📝演習：2つの処理の“交互実行”を図にする🧩
  • 🤖AI：レース例をわかりやすい比喩で説明させる🍳

16章：止め方① ユニーク制約で“二重登録を物理的に禁止”🗄️🛡️​

  • 🎯ゴール：DBのユニーク制約が冪等の味方だと理解
  • ✅内容：(userId, idempotencyKey)をユニークにする発想
  • 📝演習：ユニーク違反時にどう返す？（409など）🧾
  • 🤖AI：例外ハンドリングの雛形を生成🧯

17章：止め方② ロック/原子的操作（Atomic）で“同時を捌く”🔒⚡​

  • 🎯ゴール：ロック/Atomicの役割がわかる
  • ✅内容：processing状態を使った“先着1名だけ実行”方式など
  • 📝演習：processing/succeeded/failed の状態遷移を書く🔁
  • 🤖AI：状態遷移表を作ってもらう📋

第5部：エラー・レスポンス・契約（18〜20章）🧯📨📜​

18章：失敗はどう扱う？（リトライOK/NGの分類）✅❌​

  • 🎯ゴール：失敗を“種類”で分けられる

  • ✅内容

    • 一時的（ネットワーク/タイムアウト）→リトライOK🔁
    • 入力不正/残高不足→リトライNG🚫

  • 📝演習：エラーを分類する表を作る📋

  • 🤖AI：分類の漏れを指摘させる🔍

19章：失敗結果も保存する？（冪等 × エラー保存戦略）🧠📦​

  • 🎯ゴール：保存する/しないの判断ができる
  • ✅内容：同じキーで“同じ失敗を返す”のが良いケースもある
  • 📝演習：保存対象（成功だけ？失敗も？）を決める📝
  • 🤖AI：ケーススタディを出してもらって判断練習🎯

20章：HTTPレスポンス設計（200/201/202/409など）📨🔁​

  • 🎯ゴール：クライアントが迷わないAPI応答が作れる
  • ✅内容：202（処理中）/409（競合）などの使い方
  • 📝演習：ミニ注文APIのレスポンス一覧を作る📑
  • 🤖AI：レスポンス表を整形してもらう🧾

第6部：非同期・イベント・Outbox（21〜22章）📮🌀📤​

21章：非同期の世界は重複配送が普通（キュー入門）😇📨📨​

  • 🎯ゴール：API以外でも冪等が必要だとわかる
  • ✅内容：少なくとも1回配送（At-least-once）→重複する
  • 📝演習：重複配送でも壊れない処理の条件を書く📝
  • 🤖AI：イベント処理の“危険ポイント”を洗い出してもらう⚠️

22章：Outboxと冪等性（取りこぼし/二重送信を減らす）🤝🗃️​

  • 🎯ゴール：堅い運用を支える仕組みを知る
  • ✅内容：DB更新とイベント発行をズラさない設計
  • 📝演習：Outboxに保存する項目を決める🧾
  • 🤖AI：Outboxレコードの型定義を生成させる🧱

第7部：テスト・観測・実務運用（23〜24章）🧪👀✅​

23章：冪等性テスト（2回/10回/同時実行）🧪🔁​

  • 🎯ゴール：“大丈夫なはず”を卒業する

  • ✅内容

    • 同じキーで2回叩く
    • 同時リクエストっぽいテスト

  • 📝演習：テスト観点チェックリスト作成✅

  • 🤖AI：テストケース案を出させて取捨選択🧠

24章：実務チェックリスト＋総まとめ＋あなたの案件に当てはめ🌸🚀​

  • 🎯ゴール：自分のプロジェクトで冪等設計を始められる

  • ✅内容（チェックリスト）

    • 冪等が必要な操作か？✅
    • キーのスコープ/TTL/保存先は？🔑⏳
    • 同時実行に勝てる？⚔️
    • ログ/相関IDで追える？👀

  • 📝演習：あなたの“想定アプリ”に冪等設計を1ページでまとめる📝

  • 🤖AI：まとめをレビューして「穴」を指摘してもらう🔍✨

追加：この教材の“AI前提”の使い方（毎章共通テンプレ）🤖🧰✨​

  • 🧩「この章のゴール」をAIに貼る → 雛形を作る
  • 🧠 生成物に「なぜこうなる？」を質問して理解する
  • ✅ 最後にチェックリストで自分で検証（AI任せにしない）🙆‍♀️