DDD Architecture — COLA v5 (Diamond Architecture)

COLA v5 is Alibaba's open-source DDD architecture framework. It uses Diamond Architecture, with the Domain in the center and the Adapter and Infrastructure layers on either side. This Skill combines cola-creator (scaffolding generation) and cola-validator (architecture validation), providing end-to-end capabilities from project creation through continuous validation.

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

When to Use (Applicable Scenarios)

Enterprise-grade Java + Spring Boot projects using MyBatis/JPA
Projects requiring automated scaffolding for a multi-module COLA structure
Projects requiring automated architecture-compliance validation with ArchUnit
Projects within Alibaba's domestic technology ecosystem, such as Dubbo/RocketMQ/Nacos
Teams of 5–50 people working on medium- to high-complexity businesses

Inapplicable Scenarios

Non-Java projects → Not applicable; use
```
ddd-architecture-clean
```
or
```
ddd-architecture-hexagonal
```
instead
Non-Spring Boot projects → Not applicable; COLA is tightly coupled to the Spring ecosystem
Simple CRUD applications developed by teams of 2–3 people → Not applicable;
```
ddd-architecture-layered
```
is more lightweight
Existing Clean Architecture or Hexagonal Architecture implementations that work properly → Not applicable; no migration is needed
Rapid prototypes or PoC stages → Not applicable because the architecture overhead is too high

Core Principles of Diamond Architecture

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

Layer	Module	Responsibilities	Dependencies
Adapter	`{p}-adapter`	REST/RPC/MQ protocol adaptation, DTO conversion, and parameter validation	→ app, domain
Application	`{p}-app`	Command/Query executors, transaction orchestration, and extension-point routing	→ domain, infra
Domain	`{p}-domain`	Aggregates/E/VO, domain events, Repository/Gateway interfaces, and Ability	No dependencies
Infrastructure	`{p}-infrastructure`	Repository/Gateway implementations, PO↔DO conversion, configuration, and components	→ domain

New v5 features: Extension Point (

@ExtensionPoint

@Extension(bizId)

for multi-tenant differentiation), Ability (domain capability abstraction), componentized infrastructure (distributed locks/rate limiting/circuit breaking), and enhanced CQRS (strict separation of command/query executors).

Generation Capability: 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

Two approaches are available:

mvn archetype:generate -DarchetypeGroupId=com.alibaba.cola -DarchetypeArtifactId=cola-archetype-web -DarchetypeVersion=5.0.0

for quick setup, or a manually configured multi-module project for production use, which is recommended; see references/02 for details.

Validation Capability: cola-validator

Check Item	Level	Description	Detection Method
Dependency direction	P0	Domain must not depend on Infrastructure/App/Adapter	Import parsing
Domain purity	P0	Domain must have no Spring/JPA/MyBatis/Hibernate imports	Import scanning
Layer responsibilities	P0	Adapter contains no SQL; App contains no business if/else logic	AST analysis
Package naming conventions	P1	Names follow COLA conventions	Regex matching
Module circular dependencies	P1	Detect cycles in the dependency graph	Graph traversal
Aggregate design	P1	Aggregates with more than 5 entities, cross-aggregate references, and mutable value objects	AST analysis

Scoring model:

Score = 100 - deductions (P0 = 10 points/item, P1 = 5 points/item, P2 = 2 points/item)

. ≥90→A, 70–89→B, 50–69→C, <50→D.

Run:

mvn test -Dtest=ArchitectureComplianceTest

for the ArchUnit Java test, or

python scripts/check_cola.py /path/to/project

for lightweight Python validation.

Directory Structure (COLA v5 Multi-Module)

{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/              — 常量/异常/工具/注解/上下文

Implementation Steps

Phase 1 [1 day] Scaffolding → Phase 2 [2–3 days] Domain modeling with ddd-domain-designer → Phase 3 [2–3 days] Infrastructure, including Repository/Gateway/PO → Phase 4 [1–2 days] Application and Adapter, from Executor to Controller → Phase 5 [0.5 day] Architecture validation → Phase 6 [ongoing] Automated CI/CD validation

Core Rules

Four major constraints (P0): ①Zero framework dependencies in Domain, prohibiting Spring/JPA/MyBatis ②No business if/else logic in the App layer ③No SQL or business logic in the Adapter layer ④No circular dependencies between modules

Dependency direction:

adapter → app → domain ← infrastructure

(Domain depends on no other layer)

Gotchas — Common Pitfalls (15)

Controller in the Domain layer — Controllers belong in the Adapter layer. Finding
```
@RestController
```
under Domain means the layering is entirely incorrect.
App layer directly operates a Mapper — It must use the Repository interface:
```
orderRepository.save(order)
```
rather than
```
orderMapper.insert()
```
.
Module names do not match COLA — They must be
```
{project}-adapter/app/domain/infrastructure
```
; otherwise, ArchUnit validation fails.
Command/Query placed in the Domain layer — They should be placed in
```
app/model/command/
```
and
```
app/model/query/
```
.
Archetype version mismatch — cola-archetype-web 5.0.0 requires Spring Boot 3.x; version 2.x requires manual adaptation.
JPA
@Entity
used in the Domain layer — Persistence mappings belong in the Infrastructure layer and should use PO classes.
App layer throws framework exceptions — It should throw
```
BizException
```
, with the Adapter layer handling uniform conversion.
Direct object references across aggregates — Reference other aggregates by ID rather than directly calling
```
Order.getCustomer()
```
.
Value objects have setters — ValueObject should be immutable, using final fields without setters, and modifications should return a new object.
Missing domain events — Key operations such as creating an order, making a payment, or canceling an order must publish domain events.
Business logic in the Adapter layer — Controller/Consumer should not contain any if-else business logic.
God Service anti-pattern — A Service exceeding 500 lines should be split by aggregate.
Extension point without a default implementation — Every
```
ExtensionPoint
```
requires a default
```
@Extension
```
.
Missing
@EnableCola
— The startup class must add
```
@EnableCola
```
to enable extension points and the event bus.
Mixing PO and DO — Persistence objects and domain objects must remain separate and be converted with a Converter.

FAQ (15)

Q1: What is the relationship between COLA v5 and Clean Architecture? COLA v5 is Alibaba's implementation of Clean Architecture, with added package naming conventions, an extension-point mechanism, enhanced CQRS, and scaffolding.

Q2: Why not generate the project directly with cola-archetype? The Archetype is fast but fixed, while a manual setup is better suited to production customization.

Q3: Does COLA support microservices? Yes. Each microservice is internally organized according to the four COLA layers, while services communicate through RPC/MQ.

Q4: Is CQRS mandatory? No. Use

app/service/

orchestration for simple scenarios and switch to the CQRS executor for complex scenarios.

Q5: What is the difference between check_cola.py and ArchUnit? check_cola.py performs lightweight import scanning and is suitable for CI, whereas ArchUnit provides powerful AST analysis and requires a Java environment.

Q6: How should
@Autowired
be handled in the Domain layer? Domain prohibits

@Autowired

; inject interfaces through method parameters or the constructor.

Q7: How is domain-event delivery guaranteed? Call

EventBus.publish()

after the App-layer transaction commits, and use the Transactional Outbox pattern in production.

Q8: What is the relationship between COLA and Spring Cloud? COLA is an architecture specification, while Spring Cloud is infrastructure; the two can be fully integrated.

Q9: Should value objects be stored as JSON or in separate columns? Store simple value objects in separate columns and complex nested structures as JSON with Converter-based type conversion.

Q10: What should be done when an aggregate becomes too large? Keep it at ≤ 5 entities and split it according to business-operation frequency.

Q11: Where does the extension point's bizId come from? It is routed using frontend request headers, the logged-in user's membership level, or the tenant ID.

Q12: Can extension-point features be removed if they are not needed? Yes.

app/extension/

and

domain/ability/

do not need to be created.

Q13: What belongs in the common module? Constants, exception base classes, DTO base classes, context components such as UserContext/TenantContext, and custom annotations.

Q14: What is the relationship between start and adapter? start provides the startup entry point and global configuration, adapter handles protocol adaptation, and start depends on adapter.

Q15: How can sensitive configuration be prevented from leaking? Use externalized configuration and environment variables, prohibit hard-coded secrets, and prevent Domain from reading or writing configuration files.

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 is a Java reference implementation of the COLA v5 architecture. Based on Spring Boot 3.5.x, it integrates the lightweight ddd-4-java and cqrs-4-java libraries and fully implements DDD, CQRS, and Event Sourcing patterns.

Project generation:
```
scripts/init_project.py
```
can automatically generate a COLA multi-module project structure. It supports single-module monolith, multi-module monolith, and microservice project types, and covers required files such as pom.xml, package-info.java, .gitignore, and mvnw.
Compliance validation:
```
scripts/check_project.py
```
can verify DDD layer compliance, correct dependency direction, and package naming conventions, while producing detailed violation reports and remediation recommendations.
Scenario examples: See
```
examples/13-architecture-patterns.md
```
for four architecture patterns,
```
examples/14-single-module.md
```
for a single-module monolith,
```
examples/15-multi-module.md
```
for a multi-module monolith, and
```
examples/16-microservices.md
```
for microservices.
Detailed documentation: See
```
references/14-ddd4j-scaffold.md
```
for the complete project generation workflow, validation rules, layer dependency relationships, and package naming conventions.

References

Detailed references can be found in the

references/

directory: 01-architecture-principles (architecture principles), 02-project-scaffold (scaffolding), 03-domain-layer (domain layer), 04-app-layer (application layer), 05-adapter-layer (adapter layer), 06-infrastructure (infrastructure), 07-archunit-validation (ArchUnit validation), and 08-cqrs-integration (CQRS integration).

Examples

Complete code can be found in the

examples/

directory: 01-quickstart-order (complete Order aggregate implementation), 02-customer-crud (CRUD fundamentals), 03-extension-point (extension-point mechanism), 04-cqrs-separation (CQRS separation), and 05-archunit-config (ArchUnit validation and CI/CD integration).

Project-scale examples can be found in the

examples/

directory: 06-monolith-simple (simple monolith), 07-monolith-complex (complex monolith), 08-monolith-multi-module (multi-module monolith), 09-microservice-simple-monolith (simple monolith project for microservices), 10-microservice-complex-monolith (complex monolith project for microservices, based on ddd4j-gateway), 11-microservice-simple-multi-module (simple multi-module project for microservices, based on ddd4j-rednote), and 12-microservice-complex-multi-module (complex multi-module project for microservices, based on ddd4j-pay).

ddd-architecture-cola

NPX Install

Tags

SKILL.md Content (Chinese)