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）