ddd-cqrs-architecture

DDD CQRS アーキテクチャ

CQRS（Command Query Responsibility Segregation）— L1/L2/L3 の段階的な導入、イベントソーシング、冪等性、5 種類の DDD アーキテクチャとの統合。

このスキルを使用するタイミング

トリガーキーワード：CQRS、読み書き分離、イベントソーシング、イベントソーシング、Command Bus、Query Model、ドメインイベント、ドメインイベント、冪等性、冪等性、結果整合性、プロジェクション、マテリアライズドビュー

ワークフロー

Step 1: 判断是否需要 CQRS → 确认读写模式是否显著分化
Step 2: 选择 CQRS 级别 → L1/L2/L3
Step 3: 设计命令模型 → Command → Handler → 领域事件
Step 4: 设计查询模型 → Query → Handler → DTO
Step 5: 实现事件同步（L2/L3）→ Outbox → 发布器 → 投影
Step 6: 按架构集成 → 根据 Layered/Onion/Hexagonal/Clean/COLA

CQRS を使用するタイミング

適用シナリオ

• 読み書きのパターンが大きく異なる：書き込み操作と読み取り操作で、異なるデータ構造や最適化戦略を使用する
• 高並行の書き込み：書き込みには ACID 保証が必要で、読み取りでは結果整合性を許容できる
• 複数のビューが必要：同じデータを複数の形式（一覧／詳細／統計／検索）で表示する
• 監査証跡が必要：すべての状態変更履歴を完全に記録する
• チームがイベント駆動に対応できる：結果整合性とイベントソーシングの概念を理解している

段階的な導入

CRUD 够用（读=写）         → 单模型，无需 CQRS
  ↓
L1 模型分离                → CommandService / QueryService 分离，共享 DB
  ↓
L2 数据库分离               → Command DB + Query DB，事件同步
  ↓
L3 Event Sourcing          → EventStore + Projection

適用しないシナリオ

シナリオ	代替案
単純な CRUD、読み取り＝書き込み	単一モデルを使用し、CQRS は導入しない
プロトタイプ／一度限りのプロジェクト	CQRS を使用しない
チームがイベント駆動に不慣れ	まず ddd-event-storming を使用してイベント駆動の考え方を身につける
強い整合性が極めて重要	分散トランザクションのコストを評価する

CQRS の基本原則

観点	コマンド側（Write）	クエリ側（Read）
責務	状態変更を処理し、ビジネスルールを実行する	データビューを返す。ビジネスロジックは持たない
モデル	Command Model（コマンドオブジェクト＋集約ルート）	Query Model（DTO＋マテリアライズドビュー）
ストレージ	Write DB（3NF、ACID）	Read DB（非正規化、クエリ最適化）
整合性	強い整合性（集約内）	結果整合性（集約間／サービス間）
出力	ドメインイベント	DTO／View Model

L1/L2/L3 の導入戦略

L1 — モデル分離

最も低コストです。コード層で Command／Query Service を分離し、データベースは共有します。読み書きのデータ構造は同じでも、ロジックを分離するシナリオに適しています。 参考例：examples/06-order-l1-model-separation.md

L2 — データベース分離

中程度のコストです。Command DB と Query DB を分離し、ドメインイベントを介して同期します。読み取り負荷が高く、独立した最適化戦略が必要なシナリオに適しています。 参考例：examples/07-order-l2-db-separation.md

L3 — イベントソーシング

最も高コストです。イベントストリームを唯一の真実のソースとして、プロジェクションを通じて読み取りモデルを再構築します。監査証跡、タイムトラベルクエリ、イベントの再生が必要なシナリオに適しています。 参考例：examples/08-order-l3-event-sourcing.md

イベントのライフサイクル

领域行为 → 构建 DomainEvent → 持久化 → EventBus 发布
                                        → 本地处理器 (同步)
                                        → MQ 外发 (异步, 跨服务)

発行戦略

• ポーリングによる発行（定期的なテーブルスキャン）：遅延 1～5s、複雑度は低く、中小規模のトラフィック向け
• CDC（Debezium binlog）：遅延 <100ms、複雑度は中程度、高トラフィック・低遅延向け
• トランザクションのコミットコールバック：遅延 <10ms、複雑度は低く、Spring プロジェクト向け

詳しくは references/02-cqrs-events.md を参照してください。

冪等性の設計

戦略	コスト	信頼性	シナリオ
イベント重複排除テーブル	中	★★★	金融レベルの重要イベント
ステートマシンのガード	低	★★★	状態駆動イベント
Redis + TTL	低	★★☆	重要度の低い通知
ビジネス上の冪等性	低	★★★	単純な操作

詳しくは（コード例を含む）references/07-event-governance.md を参照してください。

各アーキテクチャにおける CQRS の統合パターン

アーキテクチャ	統合ポイント	ディレクトリ構成
Layered	Application 層で Command／Query Service を分離	app/service/command/ + app/service/query/
Onion	Core 層の Command／Query UseCase インターフェース	core/application/command/ + core/application/query/
Hexagonal	Port 層の Command Port + Query Port	domain/port/command/ + domain/port/query/
Clean	UseCase 層の Command Interactor + Query Interactor	usecase/interactor/command/ + usecase/interactor/query/
COLA	App 層の Command + Query サブモジュール	app/command/ + app/query/

詳しくは examples/04-multi-architecture-integration.md を参照してください。

注意点

• 早すぎる L2/L3 への移行：まず L1 で CQRS の価値を検証してください。ほとんどのプロジェクトでは L1 で十分です
• Query 側から書き込み DB を直接参照する：Query 側は Command 側のデータベーステーブルを決して直接読み取ってはいけません
• イベントの冪等性を忘れる：コンシューマーは冪等性を実装する必要があります（at-least-once 配信）
• イベントバージョンに互換性がない：イベント構造を変更する場合は、後方互換性を維持する必要があります
• 結果整合性に対する UI の処理：L2/L3 では、フロントエンドでポーリングまたは WebSocket が必要です
• 大きすぎる集約：イベントソーシングの集約では、小さな集約の原則を守る必要があります

よくある質問

質問	回答
CQRS では必ず結果整合性が導入されますか？	L1 では不要ですが、L2/L3 では必要です
イベントソーシングと CQRS は必ず組み合わせる必要がありますか？	いいえ。個別に使用できます
Outbox パターンが必要なのはどのような場合ですか？	信頼性の高いイベント発行が必要で、二重書き込みの問題を避けたい場合です
CQRS とマイクロサービスの関係は？	互いに独立しており、モノリス内にも、マイクロサービス間にも導入できます
クエリモデルはどの程度複雑にできますか？	集約間／サービス間でデータを組み立て、非正規化されたマテリアライズドビューを作成できます

ルール

ルール	説明
Command 側で権限を検証する	コマンドを実行する前に認証・認可を行う必要があります
イベント本文に機密データを含めない	パスワード、PII などをイベントに含めてはいけません
Query 側で状態を変更しない	Query Handler／Service は書き込み操作を行ってはいけません
業務データと Outbox を同じトランザクションで書き込む	二重書き込みの問題を避けます
集約内では強い整合性、集約間では結果整合性	1 つのトランザクションで変更できる集約の状態は最大 1 つです

スキルの範囲

✅ 得意なこと

1. 読み書きのパターンが大きく異なるシステム（レポート対トランザクション）
2. イベント駆動アーキテクチャが必要なプロジェクト
3. CQRS の 3 段階での段階的な導入（L1 モデル分離／L2 DB 分離／L3 イベントソーシング）
4. 5 種類の DDD アーキテクチャとの統合パターン
5. ドメインイベントのライフサイクル全体の管理（発行／購読／冪等性／補償）

⚠️ 条件が必要

1. 基本アーキテクチャを選定済みであること（Layered／Onion／Hexagonal／Clean／COLA）
2. チームが結果整合性とイベント駆動の概念を理解していること
3. ビジネスシナリオで実際に読み書き分離が必要であること（単純な CRUD ではない）

❌ 使用すべきでない場合（対象範囲外）

1. 単純な CRUD（読み取り＝書き込み）→ CQRS は適しません
2. プロトタイプ／一度限りのプロジェクト → CQRS を使用すべきではありません
3. チームがイベント駆動に不慣れ → まず ddd-event-storming を使用してイベント駆動の考え方を身につけてください
4. CQRS フレームワーク（Axon）をすでに使用している → フレームワークに CQRS パターンが組み込まれています

セキュリティと安定性

• コードテンプレートは学習用です。URL／認証情報は環境変数に置き換えてください。
• コマンドハンドラーでは認可を検証する必要があります。呼び出し元が認可されていると決めつけないでください。
• イベントペイロードに機密データを含めないでください。イベントは保存され、再生されます。
• 最小権限の原則：Command API と Query API では、異なるアクセス権限を使用してください。

キーワード

CQRS, 读写分离, Event Sourcing, 事件溯源, Command Bus, Query Model, Command Model, 领域事件, Domain Event, 最终一致性, Eventual Consistency, Outbox Pattern, Transactional Outbox, Materialized View, Projection, Event Store, Idempotency, 幂等, L1/L2/L3, Clean Architecture CQRS, Hexagonal CQRS, COLA CQRS

参考資料

CQRS アーキテクチャパターン

• references/architecture/01-clean-ddd-hexagonal-cqrs.md — CQRS とドメインイベント：コマンド、クエリ、リードモデル、イベントディスパッチャー、Outbox
• references/02-cqrs-events.md — CQRS のドメインイベント：イベントの分類、イベントストア、プロジェクション戦略、バージョン管理
• references/03-cqrs-mindmap.md — CQRS マインドマップ：適用シナリオ、実装戦略
• references/04-ddd4j-cqrs-mindmap.md — CQRS マインドマップ：中核となる考え方、アーキテクチャパターン、コンポーネント

ドメインイベントとイベントガバナンス

• references/07-event-governance.md — イベントガバナンス：Outbox DDL、冪等性、再試行／デッドレター／補償／照合
• references/domain-events/01-domain-events-deep.md — ドメインイベントの詳細：イベント駆動設計の原則
• references/06-domain-vs-integration-events.md — ドメインイベントと統合イベント：境界の区分
• references/08-partme-06-domain-events.md — ドメインイベントの実践：保険引受の事例

例

• examples/06-order-l1-model-separation.md — L1 モデル分離の完全な例
• examples/07-order-l2-db-separation.md — L2 データベース分離とイベント同期
• examples/08-order-l3-event-sourcing.md — L3 Event Sourcing の完全な例
• examples/04-multi-architecture-integration.md — 5 種類のアーキテクチャにおける CQRS 統合の比較
• examples/03-inventory-cqrs.md — 在庫 CQRS と冪等性戦略の実装