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版

アウトボックス（Outbox）教材：22章 詳細アウトライン 📦📨✨

第1章：まず“事故”を知ろう（Outboxが必要な理由）😵‍💫💥​

  • ありがち事故①：DB更新OK、イベント送信NG → 送信漏れ📭
  • ありがち事故②：送ったつもりが再送で 二重送信🔁
  • ありがち事故③：順序が崩れて 状態がねじれる🌀
  • ゴール🎯：Outboxが「何を守る技」かイメージする

第2章：Outboxを一言で（超ざっくり定義）🧠✨​

  • Outboxとは：“送る予定”をDBに安全に残す仕組み📦🧾
  • ポイント：業務更新とOutbox記録を 同じトランザクション でやる🔐
  • どんな時に使う？（通知・連携・非同期処理）📩🤝

第3章：前提① イベントってなに？（超入門）📨🙂​

  • 「イベント＝起きた事実」って感覚（過去形が多い）✅
  • Domain Event と Integration Event のざっくり違い👀
  • 「どこまでがドメイン？どこからが外部？」の境界感🧱

第4章：前提② 非同期ってなに？（なんで必要？）⏱️🧩​

  • 同期（待つ） vs 非同期（待たない）のメリデメ⚖️
  • 失敗や遅延がある世界で「壊れにくい」作り方🧯
  • リトライ前提の現実を受け入れる心構え😇

第5章：前提③ 最終的整合性（“すぐ一致しない”を怖がらない）🕰️🌈​

  • 「今は違うけど、あとで揃う」って考え方⏳
  • ユーザー体験と整合性の折り合い（どこは即時必須？）🎛️
  • Outboxは最終的整合性の“安全装置”だよ🛡️

第6章：全体アーキ図を描こう（登場人物を整理）🗺️👥​

  • 登場：業務テーブル、Outboxテーブル、Publisher（送信係）📦📤
  • 典型フロー：更新 → Outbox書く → 後で送る🔁
  • “後で送る”の意味：送信処理の失敗を業務から切り離す✂️

第7章：ミニ題材を決める（学習用の小さな世界）🧪🍀​

  • お題例：注文確定 → 通知イベントを発行🛒📩
  • 仕様を小さく固定（YAGNIでいくよ）🧊
  • ゴール🎯：「動く最小」を最速で作る

第8章：Windows＋VS Codeで開発準備（TypeScript最小構成）🪟💻​

  • プロジェクトの構成（src / tests / scripts のイメージ）📁

  • 実行・ビルド・テストの“いつもの流れ”を作る🔄

  • AI（Copilot/Codex）で雛形生成して時短する🤖✨

    • 例：型定義のたたき台、DTOの雛形、フォルダ構成案

第9章：Outboxテーブル設計（まずは最小カラム）📦🧾​

  • 最小で必要になりがち：

    • id（イベントID）🆔
    • eventType（種類）🏷️
    • payload（中身JSON）📄
    • status（未送信/送信済み/失敗など）🚦
    • createdAt（作成時刻）🕒

  • まずは“学習用に割り切る”ラインを決める🙂

第10章：payload設計のコツ（壊れにくいJSON）🧩📄​

  • 命名：イベント名・フィールド名のルールを決める📛
  • 欠損値・null・単位（円？ドル？）の扱いを揃える🧷
  • “受け側が困らない”payloadにする視点🎁

第11章：トランザクション入門（なぜOutboxとセット？）🔐🪄​

  • トランザクション＝「まとめて成功 or まとめて失敗」✅❌
  • Outboxの肝：業務更新＋Outbox追加を同時にやる
  • “ズレ”の例を図で理解（片方だけ成功が一番怖い）😱

第12章：実装① 書き込み（業務更新＋Outbox追加）🛠️✅​

  • アプリ層の責務：入力→ユースケース実行→結果返す🎯

  • ドメイン層の責務：ルールと状態を守る🧠

  • インフラ層の責務：DB保存とOutbox保存📦

  • AIに「責務分離レビュー」をさせる👀🤖

    • 例：DBアクセスがドメインに混ざってない？など

第13章：Publisher入門（まずは“疑似送信”でOK）📤🙂​

  • 未送信のOutboxを拾って処理する（ポーリング）⏱️
  • 送信先は最初ダミーでOK（コンソール出力でも学べる）📢
  • 送信成功 → status更新✅

第14章：並行実行とロック（複数ワーカー問題）👯‍♀️🔒​

  • 2つのPublisherが同じレコードを拾うと…二重送信😵

  • 対策の考え方：

    • “先に確保（lock）してから処理”のイメージ🧲
    • status遷移（processing → sent/failed）🚦

  • 学習用に「簡易ロック」→「実運用寄り」へ段階を作る階段設計🪜

第15章：リトライ基本（どこで、何回、いつ？）🔁🧠​

  • リトライ回数・間隔・例外の分類を決める🎛️

  • 失敗は3種類に分けると楽：

    • 一時的（ネットワーク）🌧️
    • 恒久的（データ不正）🧱
    • 仕様上（禁止状態）🚫

  • AIに「失敗パターンの洗い出し」を手伝わせる🤖📝

第16章：バックオフ＆スケジューリング（賢い再送）⏳📈​

  • 連打は迷惑＆コスト💸 → 間隔を伸ばす（指数バックオフ）📈
  • nextRetryAt の設計アイデア🕒
  • “再送待ち”を見える化する（運用で助かる）👀

第17章：冪等性（同じのが2回来ても壊れない）🛡️🔁​

  • Outboxでも二重送信は“起こり得る”前提😇
  • 冪等キー（idempotency key）の作り方・持たせ方🔑
  • “受け側”でも守ると最強（重複排除）💪

第18章：順序（Ordering）をどう扱う？🍱➡️🍱​

  • 順序が大事なイベント・大事じゃないイベントを分ける⚖️
  • 同じ注文IDのイベントは順序維持したい、みたいな話📦
  • “全部に順序保証”は重いので、範囲を絞るのがコツ🙂

第19章：Dead Letter（失敗を隔離して人が直せるように）📮😢➡️🙂​

  • 何回やっても無理なものは隔離（DLQ/DeadLetter）🗃️
  • “直せる情報”を残す：理由・入力・回数・最終例外など🧾
  • 運用の現場で泣かない設計🥹🫶

第20章：契約とバージョン（イベントは将来も残る）🧬🏷️​

  • payloadに schemaVersion を持たせる案📄

  • 後方互換の基本：

    • 追加は比較的安全✅
    • 削除・意味変更は危険⚠️

  • 破壊変更の“段階的廃止”の進め方🛠️

  • （ここで “契約設計” の考え方をやさしく固めるよ😊）

第21章：観測できるOutbox（ログ・メトリクス・追跡）🔍📊✨​

  • ログ：相関ID、イベントID、失敗理由、処理時間📝
  • メトリクス：未送信件数、遅延、失敗率、リトライ回数📈
  • 「困った時に原因へ辿り着ける設計」を最初から入れる🧯
  • AIに「観測項目の抜け漏れチェック」させる🤖✅

第22章：総合演習ミニプロジェクト（段階クリア方式）🎓🎉​

  • 22-A 最低限：Outboxが動く（書く→拾う→送る）✅

  • 22-B 発展：ロック・リトライ・バックオフ・DLQを追加🚀

  • 22-C 仕上げ：冪等性＆順序＆観測で“実戦っぽく”🛡️📊

  • 22-D AIレビュー会：

    • 設計の責務分離（SoC）できてる？✂️
    • 例外境界（エラーモデリング）暴れてない？🚦
    • 将来の変更に耐える？（KISS/YAGNIとのバランス）⚖️

毎章で使える「AI活用ミニ型」🤖✨（教材に組み込みやすいよ）​

  • 雛形：型定義・DTO・フォルダ構成案を出してもらう📁
  • レビュー：責務混在・依存の向き・例外の漏れを指摘してもらう👀
  • テスト案：失敗ケースを増やしてもらう（送信失敗、二重、順序崩れ）🧪
  • 命名：eventTypeやpayloadの名前を相談して揃える📛