ddd-architecture-layered

DDD レイヤードアーキテクチャ — レイヤードアーキテクチャ導入ガイド

DDD レイヤードアーキテクチャは、DDD エコシステムで最もシンプルな入門アーキテクチャです。従来の三層（Controller/Service/DAO）を四層（Interface/Application/Domain/Infrastructure）に再構成し、依存性逆転によってドメイン層をシステムの中核にします。

対象ユーザー

ユーザータイプ	特徴	おすすめの入口
DDD 初学者	MVC 三層を理解しており、DDD を学び始めたい方	まず Core Principles を読み → 06 単体のシンプルな例を確認 → Implementation Phases に沿って進める
アーキテクト	プロジェクトのアーキテクチャ選定と技術計画を担当する方	まず When to Use の適用境界を読み → 06-12 の規模別の選択肢を比較 → Evolution の進化パスを確認
上級開発者	三層開発の経験があり、レイヤー分割を導入する必要がある方	Directory Structure + Writing Rules を直接確認 → 07/08 の例を使ってプロジェクトを開始
技術責任者	チームに DDD を導入する実現可能性とコストを評価する方	まず When to Use + シナリオの適用境界を読み → Implementation Phases の所要時間を評価 → 09-12 のマイクロサービス計画を参照

ワークフロー

Step 1: awesome (入门)              →  了解 DDD 概念
Step 2: selector (架构选型)         →  确认分层架构适合
Step 3: layered (分层架构) ★         ← 你在这里
Step 4: domain-designer (领域设计)  →  设计领域模型
Step 5: code-reviewer (审查)        →  分层合规检查

適用場面と境界

✅ 適用できる場面

#	場面	説明
1	チームが 10 人未満で、DDD を始めたばかり	学習コストが低く、レイヤードアーキテクチャは最もシンプルな入口です
2	中程度に複雑なビジネスで、明確なドメインモデルがある	集約ルートが明確で、リッチモデルの効果が大きいです
3	既存の三層プロジェクトを段階的に進化させる	三層から四層へ段階的に移行でき、元のアーキテクチャを覆しません
4	Spring Boot/MyBatis の技術スタック	国内で主流の技術スタックで、サンプルをそのまま再利用できます

⚠️ 条件が必要な場面（慎重に評価したうえで利用可能）

#	場面	条件
1	チームが 10〜20 人	物理的なモジュール分離が必要か、先に評価する必要があります → 08 マルチモジュール案を参照
2	複数の集約ルートを持つ複雑なビジネス	集約境界が明確であることを確認する必要があります → まずイベントストーミングを行ってからレイヤー分割を導入
3	すでにマイクロサービスへの分割を検討している	まずレイヤードアーキテクチャで単一サービスを導入 → その後、09-12 のマイクロサービス案を参考に分割
4	Spring Boot 以外の技術スタック	DDD のレイヤー分割の考え方は汎用的ですが、ディレクトリ構成とコード例は独自に適合させる必要があります

❌ 適用できない場面

#	場面	代替案
1	ビジネスルールのない純粋な CRUD	Spring Boot の三層構成 + MyBatis-Plus を直接使うほうがコストを抑えられます
2	複数の入口を持つシステム（REST+CLI+MQ）	Hexagonal Architecture（ヘキサゴナルアーキテクチャ）のほうが適しています
3	物理的なモジュール分離が必要	COLA アーキテクチャまたはマイクロサービス案を使用します（09-12 の例を参照）
4	インフラストラクチャを高頻度で置き換える	インフラストラクチャが頻繁に変化する場合は、Clean Architecture をおすすめします

利用の前提条件：安定したドメインエキスパートがいて、チームがリッチモデルへの移行に前向きであること。

コア原則

三層 → 四層

三层架构:           DDD 四层:
Controller          Interface (用户接口层)
  ↓                   ↓
Service             Application (应用层) — 纯编排
  ↓                   ↓
DAO                 Domain (领域层) ★ — 核心业务
                      ↓
                    Infrastructure (基础设施层)

4 つのコア原則

#	原則	説明
1	Domain は依存ゼロ	Spring/JPA/MyBatis を import しません
2	依存性逆転	Infra が Domain で定義されたインターフェースを実装します
3	Application は薄い層	オーケストレーションのみを行い、ビジネス上の if/else は含めません
4	Interface はプロトコル変換	DTO 変換のみを行い、ビジネスロジックは含めません

ディレクトリ構成

{project}/
├── {project}-interface/              # 用户接口层
│   ├── controller/                   # REST 控制器
│   ├── dto/                          # 请求/响应 DTO
│   │   ├── request/
│   │   └── response/
│   ├── converter/                    # DTO ↔ Command 转换
│   └── advice/                       # 全局异常处理
├── {project}-application/            # 应用层
│   ├── service/                      # 应用服务（纯编排）
│   ├── command/                      # 命令对象（写）
│   ├── query/                        # 查询对象（读）
│   ├── assembler/                    # DO ↔ DTO 组装
│   └── event/                        # 事件处理
├── {project}-domain/                 # 领域层 ★（零依赖）
│   ├── {aggregate}/                  # 按聚合分包
│   │   ├── entity/                   # 实体+聚合根（充血）
│   │   ├── valueobject/              # 值对象（不可变）
│   │   ├── service/                  # 领域服务
│   │   ├── repository/               # 仓储接口（只定义）
│   │   └── event/                    # 领域事件
│   ├── factory/                      # 领域工厂
│   └── shared/                       # 共享值对象
└── {project}-infrastructure/         # 基础设施层
    ├── repository/                   # 仓储实现
    ├── persistence/                  # PO 实体+映射
    ├── messaging/                    # 消息队列
    ├── external/                     # 外部服务
    └── config/                       # 配置

開発ルール

依存の方向：Interface → Application → Domain ← Infrastructure

層	依存可能	依存不可
Interface	Application	Domain、Infrastructure
Application	Domain	Interface、Infrastructure
Domain	JDK の標準型	その他すべての層 + フレームワーク
Infrastructure	Domain	Interface、Application

コードの命名：

• 集約ルート：Order（ビジネス名。OrderEntity ではありません）
• 値オブジェクト：Money、Email（不変で、setter を持ちません）
• リポジトリインターフェース：OrderRepository（Domain に配置）
• リポジトリ実装：JpaOrderRepository（Infra に配置）
• ドメインイベント：OrderPlaced（過去形）

禁止事項：

• Controller に if/else によるビジネス判定を記述しない
• Application Service で SQL を記述しない
• Domain 層で Spring または JPA のアノテーションを import しない
• 集約をまたいでオブジェクトを直接参照しない（ID で参照します）

導入フェーズ

Phase 1: 识别聚合（1-2天）
  → 事件风暴 → 聚合根 → 不变式 → 通用语言表

Phase 2: 搭建分层骨架（1天）
  → 多模块 pom.xml → 基类（Entity/VO/AggregateRoot）

Phase 3: 实现领域层（2-5天）
  → 充血模型 → Repository 接口 → 领域服务 → 领域事件

Phase 4: 实现基础设施层（2-3天）
  → Repository 实现 → PO↔DO 映射 → DB 配置

Phase 5: 实现应用层（1-2天）
  → AppService 编排 → Command/Query → 事务管理

Phase 6: 实现接口层（1-2天）
  → Controller → DTO → 参数校验 → 异常处理

Phase 7: 审查验证（0.5天）
  → ddd-code-reviewer → ArchUnit → Domain 测试 ≥ 80%

発展

Phase 1: 传统三层       ← 当前状态
Phase 2: 四层基础       ← 抽取 Domain + Infra
Phase 3: 充血模型       ← 实体含业务方法
Phase 4: 领域事件+CQRS  ← L1 模型分离
Phase 5: 升级架构       ← 根据需要选 Hexagonal/Clean/COLA

注意点

よくある 15 の落とし穴については、references/09-gotchas.md を参照してください。

FAQ

よくある 15 の質問については、references/10-faq.md を参照してください。

キーワード

レイヤードアーキテクチャ, DDD 四層, 従来型レイヤー分割, 三層から四層への移行, DDD レイヤー分割, layered architecture, DDD layered, three tier to DDD four layer, 依存性逆転, リッチモデル, 貧血モデル, リポジトリパターン, Repository パターン, Spring Boot DDD, MyBatis DDD, DDD ディレクトリ構成, ArchUnit によるレイヤー検査, 依存方向の検証

参考資料

ファイル	内容
references/01-domain-layer.md	ドメイン層の詳細：エンティティ、値オブジェクト、集約、ドメインサービス
references/02-application-layer.md	アプリケーション層の詳細：AppService、Command/Query、トランザクション
references/03-interface-layer.md	インターフェース層の詳細：Controller、DTO、例外処理
references/04-infrastructure-layer.md	インフラストラクチャ層の詳細：Repository の実装、PO マッピング
references/05-dependency-rules.md	依存方向のルールと層間通信の規約
references/06-migration-guide.md	三層から四層への段階的な移行ガイド
references/07-archunit-config.md	ArchUnit による自動検証の設定
references/08-cqrs-integration.md	CQRS の軽量な統合（L1 モデル分離）
references/09-gotchas.md	よくある 15 の落とし穴
references/10-faq.md	よくある 15 の質問

Examples

文件	内容
examples/spring-boot-order-example.md	Spring Boot 订单系统完整示例
examples/ddd4j-springboot-practice.md	DDD4J Spring Boot 实战（Nova Coffee）
examples/partme-91-code-example.md	在线请假系统完整代码
examples/ddd4j-spring-boot-guide.md	Spring Boot DDD 分层实操指南
examples/05-archunit-layered-config.md	ArchUnit 分层验证配置
examples/06-monolith-simple.md	单体简单项目：单模块四层分包
examples/07-monolith-complex.md	单体复杂项目：多聚合根 + 跨聚合编排
examples/08-monolith-multi-module.md	单体多模块：四层 Maven 模块隔离
examples/09-microservice-simple.md	微服务简单：每服务一个 DDD 分层单体
examples/10-microservice-complex.md	微服务复杂：事件驱动 + Saga 编排
examples/11-microservice-multi-module.md	微服务多模块：每服务四层子模块
examples/12-microservice-complex-multi.md	微服务复杂多模块：Shared Kernel + CQRS

Output

当使用本 Skill 时，提供以下产出：

1. 项目骨架：完整的分层目录结构（多模块或单模块）
2. 基类模板：Entity/AggregateRoot/ValueObject/DomainEvent
3. 依赖配置：Maven/Gradle（含 ArchUnit、Spring Boot、JPA）
4. 完整 Demo：一个聚合端到端实现
5. ArchUnit 配置：依赖方向自动化验证
6. 演进路线图：三层→四层→可选架构升级
7. 迁移指南：存量三层项目迁移步骤

Security & Stability

• 代码模板为教学示例，请替换占位符为环境配置
• ArchUnit 规则强制分层边界，建议集成 CI 流水线
• DDD 四层结构隔离领域逻辑与基础设施，减少攻击面
• 本 Skill 不包含可执行脚本，所有操作为代码生成和审查
• 本 Skill 为纯文档型 Skill：不收集、不处理、不存储任何用户数据；不访问网络或外部服务；不使用任何第三方脚本。