# Ddd Architecture Cola

> Comprehensive guidance for COLA v5 Architecture (菱形架构) — Alibaba's COLA framework with adapter/application/domain/infrastructure layers. Covers full project scaffolding, architecture validation (cola-creator + cola-validator combined), dependency rule checking with ArchUnit, CQRS integration, and multi-module Maven/Gradle project generation. Use when user asks about COLA architecture, 菱形架构, cola-creator, cola-validator, 创建 COLA 项目, or needs Alibaba DDD framework.

- Skill: `full-stack-skills/ddd-architecture-cola` (Agent Skill, multi-file: 31 files)
- Install (CLI): `npx skillmds@latest add full-stack-skills/ddd-architecture-cola`
- Raw SKILL.md: https://api.skillmd.com/api/skills/full-stack-skills/ddd-architecture-cola/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: Apache-2.0
- Author: full-stack-skills (https://skillmd.com/u/full-stack-skills)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/full-stack-skills/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 是整洁架构的阿里化实现，增加包命名规范、扩展点机制、CQRS 强化和脚手架。

**Q2: 为何不用 cola-archetype 直接生成？** Archetype 快速但固定，手动搭建更适合生产定制。

**Q3: COLA 支持微服务吗？** 支持。每个微服务内部按 COLA 四层组织，服务间通过 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 层不读写配置文件。

## Keywords

`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`
## Project Scaffolding

**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 多模块项目结构，支持单模块单体、多模块单体和微服务三种项目类型，涵盖 pom.xml、package-info.java、.gitignore、mvnw 等必需文件
- **合规验证**: 使用 `scripts/check_project.py` 可验证项目的 DDD 分层合规性、依赖方向正确性和包命名规范，输出详细的违规报告和修复建议
- **场景示例**: 参考 `examples/13-architecture-patterns.md`（四种架构模式）、`examples/14-single-module.md`（单模块单体）、`examples/15-multi-module.md`（多模块单体）、`examples/16-microservices.md`（微服务）
- **详细说明**: 参考 `references/14-ddd4j-scaffold.md` 了解完整的项目生成流程、验证规则、层依赖关系和包命名规范

## References

详细参考见 `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

完整代码见 `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）