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