ddd-architecture-cola

DDD Architecture — COLA v5（菱形架构）

COLA v5 是阿里巴巴开源的 DDD 架构框架，采用菱形架构——Domain 居中，Adapter 和 Infrastructure 分居两侧。本 Skill 合并 cola-creator（脚手架生成）和 cola-validator（架构校验），提供从创建到持续校验的全流程能力。

Workflow

输入 → 意图识别
  ├─ "创建 COLA 项目" → Creator 流程（5 步）
  │   Step 1: 确认项目名/包名/语言/Spring Boot 版本/CQRS 开关
  │   Step 2: 生成多模块 Maven/Gradle 骨架
  │   Step 3: 生成基类（AggregateRoot/Entity/VO/DomainEvent）
  │   Step 4: 生成 Demo 聚合代码（四层完整链路）
  │   Step 5: 生成 ArchUnit 测试 + check_cola.py 脚本
  └─ "检查架构合规" → Validator 流程（4 步）
      Step 1: 接收项目路径或代码片段
      Step 2: 执行 6 项合规检查
      Step 3: P0/P1/P2 权重扣分，输出评分报告
      Step 4: 输出违规清单 + 修复建议
完成后引导 → ddd-domain-designer / ddd-api-designer / ddd-code-reviewer

When to Use / Boundary

什么时候该用（适用场景）

• Java + Spring Boot 企业级项目，MyBatis/JPA 技术栈
• 需要脚手架自动生成多模块 COLA 项目
• 需要 ArchUnit 自动校验架构合规
• 国内阿里系技术生态（Dubbo/RocketMQ/Nacos）
• 团队 5-50 人，业务中高复杂度

不适用场景

• 非 Java 项目 → 不适用，推荐 ddd-architecture-clean / ddd-architecture-hexagonal
• 非 Spring Boot → 不适用，COLA 强绑定 Spring 生态
• 2-3 人团队简单 CRUD → 不适用，ddd-architecture-layered 更轻量
• 已有整洁/六边形架构正常运行 → 不适用，无需迁移
• 快速原型/PoC 阶段 → 不适用，架构成本过高

菱形架构核心原理

          ┌──────────────┐
          │   Adapter    │  ← 适配层：HTTP/MQ/RPC 协议适配与 DTO 转换
          └──────┬───────┘
          ┌──────▼───────┐
          │   Application│  ← 应用层：用例编排、事务管理、CQRS 执行器
  ┌───────┴───────┬───────┴───────┐
  ▼               ▼               ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│  Domain  │ │  Domain  │ │  Domain  │  ← 领域层：业务规则 ★ 零框架依赖
│   ★      │ │   ★      │ │   ★      │
└──────────┘ └──────────┘ └──────────┘
  ▲               ▲               ▲
  └───────────────┴───────────────┘
                 │
          ┌──────▼───────┐
          │Infrastructure│  ← 基础设施层：DB/MQ/缓存/外部 API 实现
          └──────────────┘

层	模块	职责	依赖
Adapter	{p}-adapter	REST/RPC/MQ 协议适配、DTO 转换、参数校验	→ app, domain
Application	{p}-app	Command/Query 执行器、事务编排、扩展点路由	→ domain, infra
Domain	{p}-domain	聚合/E/VO、领域事件、Repository/Gateway 接口、Ability	无依赖
Infrastructure	{p}-infrastructure	Repository/Gateway 实现、PO↔DO 转换、配置、组件	→ domain

v5 新增特性：Extension Point（@ExtensionPoint + @Extension(bizId) 多租户差异化）、Ability（领域能力抽象）、组件化基础设施（分布式锁/限流/熔断）、CQRS 强化（command/query 执行器严格分离）

生成能力：cola-creator

AI 交互确认 → 项目名/包名(com.example.order) / 语言(Java 17+/Kotlin) / Spring Boot(3.2+/3.1) / CQRS(否/L1/L2) / Demo(默认Order)
生成内容：
  ├── pom.xml/build.gradle（6 模块：start/adapter/app/domain/infrastructure/common）
  ├── COLA v5 标准目录结构 + 基类（AggregateRoot/Entity/VO/DomainEvent）
  ├── Demo 聚合（Order 四层完整示例）
  ├── DDD 中间件配置（DomainEventBus、ExtensionExecutor）
  ├── ArchUnit 测试 + check_cola.py 脚本
  └── .gitignore + README

两种方式：mvn archetype:generate -DarchetypeGroupId=com.alibaba.cola -DarchetypeArtifactId=cola-archetype-web -DarchetypeVersion=5.0.0（快速）或手动多模块（生产推荐，详见 references/02）。

校验能力：cola-validator

检查项	级别	说明	检测方式
依赖方向	P0	Domain 不可依赖 Infrastructure/App/Adapter	import 解析
Domain 纯净度	P0	Domain 无 Spring/JPA/MyBatis/Hibernate import	import 扫描
层职责	P0	Adapter 无 SQL、App 无业务 if/else	AST 分析
包命名规范	P1	按 COLA 约定命名	正则匹配
模块循环依赖	P1	DFS 检测依赖图	图遍历
聚合设计	P1	聚合＞5 实体、跨聚合引用、值对象可变性	AST 分析

评分模型：评分 = 100 - 扣分（P0=10分/项，P1=5分/项，P2=2分/项）。≥90→A，70-89→B，50-69→C，<50→D。

运行：mvn test -Dtest=ArchitectureComplianceTest（ArchUnit Java 测试）或 python scripts/check_cola.py /path/to/project（Python 轻量校验）。

目录结构（COLA v5 多模块）

{project}/
├── start/               — 启动模块：Application.java(@EnableCola), config/
├── adapter/             — 适配器层
│   ├── web/             — controller/dto/advice(GlobalExceptionHandler)
│   ├── rpc/             — Dubbo/gRPC provider/consumer/facade
│   ├── job/             — 定时任务调度
│   └── message/         — MQ consumer/producer
├── app/                 — 应用层
│   ├── executor/        — command/query/event/extension 执行器
│   ├── model/           — command/query/event/dto 对象
│   ├── eventhandler/    — 事件处理器
│   └── extension/       — 扩展点(point/biz/impl)
├── domain/ ★            — 领域层（零框架依赖）
│   ├── model/           — entity/vo/aggregate/event/enums
│   ├── service/         — 领域服务
│   ├── ability/         — 领域能力（v5 新概念）
│   ├── gateway/         — 防腐层接口
│   └── repository/      — 仓储接口
├── infrastructure/      — 基础设施层
│   ├── config/          — DB/缓存/MQ/RPC 配置
│   ├── persistence/     — repositoryimpl/mapper/dao/entity(PO)
│   ├── gatewayimpl/     — 网关实现
│   ├── external/        — 外部服务客户端
│   └── component/       — 分布式锁/限流/熔断/重试
└── common/              — 常量/异常/工具/注解/上下文

落地步骤

Phase 1 [1天] 脚手架 → Phase 2 [2-3天] 领域建模（配合 ddd-domain-designer）→ Phase 3 [2-3天] 基础设施（Repository/Gateway/PO）→ Phase 4 [1-2天] 应用+适配（Executor → Controller）→ Phase 5 [0.5天] 架构校验 → Phase 6 [持续] CI/CD 自动校验

核心规则（Core Rules）

四大约束（P0）：①Domain 零框架依赖（禁止 Spring/JPA/MyBatis）②App 层无业务 if/else ③Adapter 无 SQL/业务判断 ④模块间无循环依赖

依赖方向：adapter → app → domain ← infrastructure（domain 不依赖任何人）

Gotchas — 常见坑（15条）

1. Domain 层放 Controller — Controller 在 Adapter 层。Domain 下出现 @RestController 说明分层全错。
2. App 层直接操作 Mapper — 必须通过 Repository 接口：orderRepository.save(order) 而非 orderMapper.insert()。
3. 模块命名不匹配 COLA — 必须为 {project}-adapter/app/domain/infrastructure，否则 ArchUnit 校验失败。
4. Command/Query 放 Domain 层 — 应放 app/model/command/ 和 app/model/query/。
5. Archetype 版本不匹配 — cola-archetype-web 5.0.0 要求 Spring Boot 3.x，2.x 需手动适配。
6. Domain 层用 JPA @Entity — 持久化映射在 Infrastructure 层用 PO 类。
7. App 层抛框架异常 — 应抛 BizException，Adapter 层统一转换。
8. 跨聚合直接引用对象 — 聚合间通过 ID 引用，不直接 Order.getCustomer()。
9. 值对象带 setter — ValueObject 应不可变（final + 无 setter），修改返回新对象。
10. 缺少领域事件 — 创建订单/支付/取消等关键操作必须发布领域事件。
11. Adapter 层有业务判断 — Controller/Consumer 不应有任何 if-else。
12. God Service 反模式 — Service 超 500 行应按聚合拆分。
13. 扩展点无默认实现 — 每个 ExtensionPoint 需有默认 @Extension。
14. @EnableCola 缺失 — 启动类必须加 @EnableCola 启用的扩展点和事件总线。
15. PO 与 DO 混用 — 持久化对象和领域对象必须分离，用 Converter 转换。

FAQ（15項目）

Q1: COLA v5 とクリーンアーキテクチャの関係は？ COLA v5 はクリーンアーキテクチャを Alibaba 向けに実装したもので、パッケージ命名規則、拡張ポイント機構、CQRS の強化、スキャフォールディングを追加しています。

Q2: cola-archetype を使って直接生成しないのはなぜですか？ Archetype は迅速に生成できますが、構成が固定されています。手動で構築するほうが、本番環境向けのカスタマイズに適しています。

Q3: COLA はマイクロサービスに対応していますか？ 対応しています。各マイクロサービスの内部は COLA の 4 層で構成し、サービス間は RPC/MQ で通信します。

Q4: CQRS は必須ですか？ いいえ。単純なシナリオでは app/service/ でオーケストレーションし、複雑なシナリオでは CQRS executor に切り替えます。

Q5: check_cola.py と ArchUnit の違いは何ですか？ check_cola.py は軽量な import スキャンで CI に適しており、ArchUnit は強力な AST 分析を行いますが、Java 環境が必要です。

Q6: Domain 層の @Autowired はどのように扱いますか？ Domain では @Autowired を禁止し、メソッドの引数またはコンストラクターを通じてインターフェイスを注入します。

Q7: ドメインイベントの配信はどのように保証しますか？ App 層でトランザクションをコミットした後に EventBus.publish() を実行し、本番環境では Transactional Outbox パターンを併用します。

Q8: COLA と Spring Cloud の関係は？ COLA はアーキテクチャ規範であり、Spring Cloud はインフラストラクチャです。完全に統合して使用できます。

Q9: 値オブジェクトは JSON に保存すべきですか、それとも列に分割すべきですか？ 単純な値オブジェクトは列に分割し、複雑なネスト構造は JSON に保存して、Converter で型変換します。

Q10: 集約が大きすぎる場合はどうすればよいですか？ エンティティを 5 個以下にし、業務操作の頻度に応じて分割します。

Q11: 拡張ポイントの bizId はどこから取得しますか？ フロントエンドのリクエストヘッダー、ログインユーザーの会員ランク、テナント ID などをルーティングに使用します。

Q12: 拡張ポイントが不要な場合、削除できますか？ できます。app/extension/ と domain/ability/ は作成しなくてもかまいません。

Q13: common モジュールには何を含めますか？ 定数、例外基底クラス、DTO 基底クラス、コンテキスト（UserContext/TenantContext）、カスタムアノテーションです。

Q14: start と adapter の関係は？ start は起動エントリーポイントとグローバル設定を担い、adapter はプロトコルを適合させます。start は adapter に依存します。

Q15: 機密設定の漏えいをどのように防ぎますか？ 設定を外部化し、環境変数を使用します。キーのハードコーディングは禁止し、Domain 層では設定ファイルの読み書きを行いません。

キーワード

COLA COLA v5 菱形アーキテクチャ diamond architecture cola-creator cola-validator ArchUnit CQRS Extension Point 拡張ポイント Ability ドメイン能力 Aggregate Root Entity Value Object Domain Event Repository Gateway 腐敗防止層 DDD Spring Boot MyBatis @EnableCola CommandExecutor QueryExecutor

プロジェクトのスキャフォールディング

ddd4j Boot は COLA v5 アーキテクチャの Java リファレンス実装です。Spring Boot 3.5.x をベースに、軽量ライブラリ ddd-4-java と cqrs-4-java を統合し、DDD、CQRS、Event Sourcing パターンを完全に実装しています。

• プロジェクト生成: scripts/init_project.py を使用すると、COLA のマルチモジュールプロジェクト構造を自動生成できます。単一モジュールのモノリス、マルチモジュールのモノリス、マイクロサービスの 3 種類のプロジェクトに対応し、pom.xml、package-info.java、.gitignore、mvnw などの必須ファイルを含みます
• 準拠性の検証: scripts/check_project.py を使用すると、プロジェクトの DDD レイヤー構成への準拠性、依存方向の正確性、パッケージ命名規則を検証できます。違反の詳細なレポートと修正案が出力されます
• シナリオ例: examples/13-architecture-patterns.md（4 種類のアーキテクチャパターン）、examples/14-single-module.md（単一モジュールのモノリス）、examples/15-multi-module.md（マルチモジュールのモノリス）、examples/16-microservices.md（マイクロサービス）を参照してください
• 詳細説明: references/14-ddd4j-scaffold.md を参照すると、プロジェクト生成の全手順、検証ルール、層間の依存関係、パッケージ命名規則を確認できます

リファレンス

詳細は references/ ディレクトリを参照してください：01-architecture-principles（アーキテクチャの原則）、02-project-scaffold（スキャフォールディング）、03-domain-layer（ドメイン層）、04-app-layer（アプリケーション層）、05-adapter-layer（アダプター層）、06-infrastructure（インフラストラクチャ）、07-archunit-validation（ArchUnit による検証）、08-cqrs-integration（CQRS 統合）

サンプル

完全なコードは examples/ ディレクトリを参照してください：01-quickstart-order（Order 集約の完全な実装）、02-customer-crud（CRUD 入門）、03-extension-point（拡張ポイント機構）、04-cqrs-separation（CQRS の分離）、05-archunit-config（ArchUnit による検証の CI/CD 統合）

プロジェクト規模のサンプルは examples/ ディレクトリを参照してください：06-monolith-simple（単純なモノリスプロジェクト）、07-monolith-complex（複雑なモノリスプロジェクト）、08-monolith-multi-module（マルチモジュールのモノリスプロジェクト）、09-microservice-simple-monolith（単純なマイクロサービスのモノリスプロジェクト）、10-microservice-complex-monolith（複雑なマイクロサービスのモノリスプロジェクト。ddd4j-gateway ベース）、11-microservice-simple-multi-module（単純なマイクロサービスのマルチモジュールプロジェクト。ddd4j-rednote ベース）、12-microservice-complex-multi-module（複雑なマイクロサービスのマルチモジュールプロジェクト。ddd4j-pay ベース）