ddd-architecture-onion

DDD アーキテクチャ — オニオンアーキテクチャ

Jeffrey Palermo（2008）が提唱した同心円アーキテクチャモデルに基づき、Domain を円の中心として、依存関係の方向を厳密に内側へ向けます。

ワークフロー

Step 1: 適用性の確認 — プロジェクトがオニオンアーキテクチャに適しているか判断します | 参照：SKILL.md When to Use

Step 2: ディレクトリの骨組みを作成 — 4 層モジュール core/infrastructure/api/composition を作成します | 参照：references/04

Step 3: Domain コアを作成 — 集約ルート、値オブジェクト、Repository インターフェース、ドメインイベント（フレームワークへの依存はゼロ）| 参照：references/01

Step 4: Application インターフェースを作成 — アプリケーションサービスのインターフェース契約を定義します。純粋なオーケストレーションのみで、ビジネスロジックは含めません | 参照：references/02

Step 5: Infrastructure の実装を作成 — Domain 層の Repository/MQ/外部クライアントを実装します | 参照：references/03

Step 6: API アダプターを作成 — Controller、DTO、Assembler、グローバル例外処理 | 参照：references/04

Step 7: DI の組み立てを設定 — composition モジュールで一元的に組み立てます | 参照：references/05

Step 8: テストを作成 — Domain 層の単体テスト → Application の Mock → Infra の統合テスト | 参照：references/06

Step 9: 落とし穴を確認 — よくある落とし穴と照らし合わせて、1 つずつ検証します | 参照：各 references の落とし穴の節

Step 10: 移行（該当する場合） — 3 層アーキテクチャからオニオンアーキテクチャへ段階的に移行します | 参照：references/07

読むタイミング（トリガー条件）

ユーザーの質問	読み込みアクション
「オニオンアーキテクチャでプロジェクトを構築して」	SKILL.md + references/01-05 を開く
「Repository インターフェースはどこに置くべき？」	references/01-domain-model を開く
「オニオンアーキテクチャではどうテストする？」	references/06-testing を開く
「3 層アーキテクチャからどう移行する？」	references/07-migration-from-layered を開く
「オニオンアーキテクチャと六角形アーキテクチャの違いは？」	references/08-comparison を開く
「オニオンアーキテクチャは CQRS をサポートしている？」	examples/example-04-cqrs-onion を開く
「複数のエントリーポイントをどう設計する？」	examples/example-03-multi-entry を開く
「Spring Boot で DI をどう設定する？」	references/05-di-composition を開く

使用するケース

✅ 適しているケース	❌ 適していないケース
インフラストラクチャが頻繁に変更される（DB/MQ/キャッシュのベンダー変更）	シンプルな CRUD プロジェクト（過剰設計）
単体テストのカバレッジ要件が 80% 超	2 週間で納品するプロトタイプ/PoC
複数のエントリーポイントを持つシステム（REST + CLI + MQ + gRPC）	エントリーポイント 1 つ + データベース 1 つのシンプルなサービス
チームにインターフェース抽象化と DI の設計能力がある	チームが依存性逆転に不慣れ
ビジネスルールが複雑で、厳密な分離が必要	3 層アーキテクチャで十分

適用範囲

領域	担当
3 層アーキテクチャからオニオンアーキテクチャへの移行	✅ この Skill（references/07-migration）
オニオンアーキテクチャ vs 六角形アーキテクチャ vs クリーンアーキテクチャの比較	✅ この Skill（references/08-comparison）
アーキテクチャ選定	❌ ddd-architecture-selector を使用
ドメインモデリング	❌ ddd-domain-designer を使用
コードレビュー	❌ ddd-code-reviewer を使用
COLA プロジェクト	❌ ddd-architecture-cola を使用

対象読者

この Skill は、バックエンド開発者（DDD アーキテクチャを実装する方）、ソフトウェアアーキテクト（パターンを評価・選定する方）、テックリード（チームの実装をレビューする方）、DDD 初心者（ドメイン駆動設計の基礎を学ぶ方）を対象としています。

コア原則：同心円の依存ルール

すべての依存関係は円の中心（Domain）に向かい、内側の層がインターフェースを定義し、外側の層がインターフェースを実装します。

Infrastructure → API/Adapters → Application → Domain Core ★
所有依赖指向圆心，内层零框架依赖。

Jeffrey Palermo の 4 原則

1. アプリケーションのコアはインフラストラクチャから独立 — Domain 層では、フレームワークやデータベースのクラスを一切 import しません
2. 内側の層がインターフェースを定義し、外側の層が実装 — たとえば、OrderRepository インターフェースは Domain に置き、実装は Infrastructure に置きます
3. 依存関係は円の中心に向かう — Infrastructure → Application → Domain。逆方向は禁止です
4. 外側の層は内側の層を知っているが、内側の層は外側の層を知らない — Domain は Infrastructure について何も知りません

ルール

#	ルール	検出方法	レベル
1	Domain 層はフレームワークへの依存ゼロ	Domain パッケージ内のフレームワーク import を検索	P0
2	Repository インターフェースは Domain、実装は Infra	インターフェースと実装の配置を確認	P0
3	Application 層は純粋なオーケストレーションのみとし、ビジネス上の if/else を含めない	コードレビュー	P0
4	値オブジェクトは不変（final フィールド、setter なし）	ValueObject クラスを確認	P1
5	集約をまたぐ参照には ID を使用	集約ルートのフィールド型を確認	P1
6	DTO は API 層で定義し、Domain に漏らさない	Domain 内の DTO import を確認	P0
7	Composition Root で DI を一元管理	各層に new による依存生成がないか確認	P1

オニオンアーキテクチャ、六角形アーキテクチャ、クリーンアーキテクチャの詳細な比較については、references/08-comparison.md を参照してください。

ディレクトリ構成

{project}/
├── {project}-core/domain/          # 领域模型（零框架依赖）
├── {project}-core/application/     # 应用服务接口
├── {project}-infrastructure/       # Repository 实现、MQ、外部集成
├── {project}-api/                  # Controller、DTO、Assembler
└── {project}-composition/          # DI 组装

モジュールの依存ルール

モジュール	依存可能	依存不可
core/domain	なし（純粋な Java）	Spring/JPA/MyBatis
core/application	domain	infrastructure, api
infrastructure	core	api
api	core, infrastructure	—
composition	すべてのモジュール	—

開発規約（詳細は各 references を参照）

#	規約	違反例
1	Domain はフレームワークへの依存ゼロ	import org.springframework.stereotype.Service
2	Repository インターフェースは Domain に置く	インターフェースと実装の両方が Infra にある
3	Application はオーケストレーションのみを行い、実装しない	AppService にビジネス判断が含まれている
4	トランザクション境界は Application に置く	Controller または Repository でトランザクションを開始する
5	集約をまたぐ連携にはドメインイベントを使用	集約 A が集約 B を直接参照する
6	値オブジェクトは不変	ValueObject に setter がある
7	エンティティはドメインロジックを持つ	エンティティが getter/setter のみ
8	DTO は API 層で定義	Domain に DTO import がある
9	Composition Root は最外層に置く	各層で依存を new する
10	厳密に層を分ける	API が Infrastructure を直接呼び出す

よくある落とし穴 —（各 references の「落とし穴」章を参照）

重要な落とし穴 15 項目：Domain 層へのフレームワーク漏洩／Repository インターフェースの配置／Application 層の肥大化／過度な抽象化／Composition Root の分散／可変な値オブジェクト／大きすぎる集約ルート／集約をまたいだ直接参照／ビジネスロジックを含む Controller／DTO の漏洩／PO アノテーション／イベントの不足／集約をまたぐトランザクション／テストへの Infra の侵入

FAQ —（references/08-comparison.md および各層の references を参照）

オニオンアーキテクチャとヘキサゴナルアーキテクチャの比較、Domain 層のフレームワーク制約、値オブジェクトとエンティティの違い、Repository インターフェースの配置、集約のサイズ、移行戦略、CQRS との互換性、テストの階層、マイクロサービスへの適用、サービス間のイベントなどを取り上げます。

キーワード

onion architecture, 洋葱架构, Jeffrey Palermo, domain-centric architecture,
layered isolation, dependency inversion, 依赖倒置, concentric layers,
core/domain, application interfaces, infrastructure implementation,
API adapters, composition root, DI assembly, domain model,
repository pattern, aggregate root, value object, domain service,
DDD layered, clean architecture comparison, hexagonal comparison

リファレンス

ファイル	用途
references/01-domain-model.md	ドメイン層の設計詳解：集約ルート、値オブジェクト、ドメインサービス
references/02-application-interfaces.md	アプリケーション層のインターフェース設計：サービスのオーケストレーションとトランザクション境界
references/03-infrastructure-implementation.md	インフラストラクチャ層の実装：Repository、MQ、外部連携
references/04-api-adapters.md	API アダプター層：Controller、DTO、Assembler
references/05-di-composition.md	DI の組み立て：Composition Root の設定
references/06-testing.md	テスト戦略：ユニットテスト、統合テスト、契約テスト
references/07-migration-from-layered.md	3 層アーキテクチャからオニオンアーキテクチャへの完全な移行手順
references/08-comparison.md	オニオンアーキテクチャ、ヘキサゴナルアーキテクチャ、クリーンアーキテクチャの詳細な比較

例

ビジネスシナリオの例

例	説明
examples/example-01-order-payment.md	注文決済の完全な例（Domain/Application/Infra/API を含む）
examples/example-02-product-catalog.md	製品カタログ管理の例（複数の集約間の連携を含む）
examples/example-03-multi-entry.md	複数エントリーポイントを持つシステムの例（REST + MQ + CLI の 3 種類のアダプター）
examples/example-04-cqrs-onion.md	CQRS とオニオンアーキテクチャの融合例（Command/Query の分離）
examples/example-05-user-registration.md	ユーザー登録とメール認証の例

プロジェクト規模別の例

例	説明
examples/06-monolith-simple.md	シンプルなモノリス：1 つのモジュールで構成されるプロジェクト、1 つの境界づけられたコンテキスト
examples/07-monolith-complex.md	複雑なモノリス：1 つのモジュールに複数の境界づけられたコンテキストを配置し、内部で分離
examples/08-monolith-multi-module.md	マルチモジュールのモノリス：Maven のマルチモジュールでレイヤー分離を強制
examples/09-microservice-simple.md	シンプルなマイクロサービス：1 サービス、1 コンテキストのオニオンアーキテクチャ
examples/10-microservice-complex.md	複雑なマイクロサービス：1 サービスに複数のコンテキストを配置し、内部で分離
examples/11-microservice-multi-module.md	マルチモジュールのマイクロサービス：1 サービスを Maven のマルチモジュールで構成するオニオンアーキテクチャ
examples/12-microservice-complex-multi.md	複雑なマルチモジュールのマイクロサービス：複数のコンテキストを Maven のマルチモジュールで構成

主な参考資料：Onion Architecture Part 1-4 — Jeffrey Palermo（2008） · DDD Blue Book — Eric Evans（2003） · Implementing DDD — Vaughn Vernon（2013）

実装：Microsoft DDD Microservice · Testcontainers

出力

回答には常に、適用性の判断 → ディレクトリー構造 → 各層のコードテンプレート → DI の組み立て → テストの骨組み → よくある落とし穴への準拠チェックを含めます。詳細は references/ および examples/ ファイルを参照してください。

---

スキルの道のり

📍 現在：オニオンアーキテクチャの実践

← 前のステップ：ddd-architecture-selector スキルに引き継ぐ（インストール：npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-selector） → 次のステップ：ddd-domain-designer スキルに引き継ぐ（インストール：npx skills add full-stack-skills/ddd-skills --skill ddd-domain-designer） 🔗 関連：ddd-cqrs-architecture スキルに引き継ぐ（インストール：npx skills add full-stack-skills/ddd-skills --skill ddd-cqrs-architecture） | ddd-code-reviewer スキル（インストール：npx skills add full-stack-skills/ddd-skills --skill ddd-code-reviewer） 🏠 ホーム：ddd-architecture-awesome スキルに引き継ぐ（インストール：npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-awesome）

核心の原則：内側の層がインターフェースを定義し、外側の層がインターフェースを実装する。依存関係は円の中心に向かいます。

セキュリティと安全性

このスキルは純粋なドキュメントです。実行可能なスクリプトは含まれておらず、ユーザーデータの収集や外部サービスまたはネットワークへのアクセスも行いません。

検証チェックリスト

• Domain 層にフレームワークの import がない
• Repository インターフェースが Domain 層にある
• Repository の実装が Infrastructure 層にある
• Application 層にビジネスロジックの if/else がない
• 値オブジェクトが不変である
• 集約間の参照に ID を使用している
• DTO が API 層のみに定義されている
• DI が composition モジュールに集約されている
• ドメインイベントが発行されている