- 后端
【免费下载链接】COLA
🥤 COLA: Clean Object-oriented & Layered Architecture
本文基于开源仓库 COLA 的 README.md 编写。COLA（Clean Object-oriented and Layered Architecture）是一套由阿里巴巴开源团队沉淀的"整洁面向对象分层架构"框架，主张以业务为核心、解耦外部依赖、分离业务复杂度与技术复杂度，并通过可落地的 Archetype 脚手架与通用组件帮助 Java 开发者快速构建符合整洁架构思想的 Spring Boot 应用。读完本文，你将掌握 COLA 的整体架构分层思想、两条 Archetype 生成命令的完整用法、六大通用组件的职责与内部实现原理，以及如何基于生成的项目结构快速启动并验证一个可运行的 Web 应用。
一、COLA 是什么：架构的"要素"与"结构"
COLA 是Clean Object-oriented and Layered Architecture的缩写，意为"整洁面向对象分层架构"。它的命名本身就点明了它的两个内核：
- 要素（要素结构）：架构由"要素"组成，要素是组成架构的重要元素；
- 结构：结构是要素之间的关系。
应用架构的意义在于：定义一套良好的结构，治理应用复杂度、降低系统熵值，帮助业务系统从"随心所欲的混乱状态"走向"井井有条的有序状态"。这正是 COLA 架构的诞生动机——通过良好的分层结构、良好的包结构定义，治理混乱不堪的业务应用系统。
在理念上，COLA 与六边形架构（Hexagonal Architecture）、洋葱圈架构（Onion Architecture）、整洁架构（Clean Architecture）一脉相承：都提倡以业务为核心，解耦外部依赖，分离业务复杂度与技术复杂度。而 COLA 的独特之处在于，除了架构思想之外，它还提供了可落地的工具和实践指导——即下文要重点讲解的 Archetype 工程脚手架与通用组件库。
从仓库的聚合工程结构（见根目录 pom.xml）可以确认，COLA 由两大部分构成：
- COLA 架构（cola-archetypes 目录）：提供工程脚手架，帮助开发者快速生成符合 COLA 分层规范的应用；
- COLA 组件（cola-components 目录）：沉淀了一批通用组件，直接提升研发效率。
二、COLA Archetypes：一键生成整洁分层应用
好的应用架构都遵循共同模式，但 COLA 的可贵之处在于"可落地"。为了快速创建满足 COLA 架构的应用，仓库在 cola-archetypes 目录下提供了三个 archetype（Maven 原型工程），其中面向业务应用的主要有两个：
| Archetype | 用途 |
|---|---|
cola-archetype-service | 创建纯后端服务工程（不包含 Web 展示层） |
cola-archetype-web | 创建adapter 与后端服务一体的 Web 应用工程 |
另外，5.0.0 版本还新增了cola-archetype-light，支持基于 package 的轻量级分层架构（详见后文版本迭代部分）。三个 archetype 都聚合在 cola-archetypes/pom.xml 中统一管理。
1. 创建 Web 应用（adapter + 后端一体）
在任意空目录下执行以下 Maven 命令：
mvn archetype:generate \ -DgroupId=com.alibaba.cola.demo.web \ -DartifactId=demo-web \ -Dversion=1.0.0-SNAPSHOT \ -Dpackage=com.alibaba.demo \ -DarchetypeArtifactId=cola-framework-archetype-web \ -DarchetypeGroupId=com.alibaba.cola \ -DarchetypeVersion=5.0.0参数说明：
-DgroupId/-DartifactId/-Dversion：生成工程的 GAV 坐标，按需替换；-Dpackage：生成工程的根包名，源码会以该包名展开；-DarchetypeArtifactId：指定使用cola-framework-archetype-web（注意 archetype 的 artifactId 前缀为cola-framework-archetype-*）；-DarchetypeGroupId=com.alibaba.cola与-DarchetypeVersion=5.0.0：定位 COLA 官方发布的 archetype 版本。
2. 创建纯后端 Service 工程
如果不需要 Web 展示层，执行下面的命令：
mvn archetype:generate \ -DgroupId=com.alibaba.cola.demo.service \ -DartifactId=demo-service \ -Dversion=1.0.0-SNAPSHOT \ -Dpackage=com.alibaba.demo \ -DarchetypeArtifactId=cola-framework-archetype-service \ -DarchetypeGroupId=com.alibaba.cola \ -DarchetypeVersion=5.0.0两条命令仅-DgroupId、-DartifactId与-DarchetypeArtifactId不同，其余参数保持一致。
3. 生成后的工程结构长什么样？
命令执行成功后，会得到一个多模块 Maven 工程。以cola-archetype-web为例（见 cola-archetype-web 的 archetype-resources），生成的项目大致包含以下子模块，恰好体现了 COLA 的分层思想：
| 子模块 | 职责 | 典型内容 |
|---|---|---|
*-client | 对外 API 与 DTO 定义 | api/CustomerServiceI、dto/CustomerAddCmd、dto/CustomerListByNameQry、dto/data/CustomerDTO、dto/event/CustomerCreatedEvent |
*-app | 应用服务层，编排用例 | customer/CustomerServiceImpl、customer/executor/CustomerAddCmdExe、customer/executor/query/CustomerListByNameQryExe |
*-domain | 领域层，承载核心业务 | domain/customer/Customer、domain/customer/gateway/CustomerGateway、domain/customer/domainservice/CreditChecker |
*-infrastructure | 基础设施层，落地技术细节 | customer/CustomerDO、customer/CustomerMapper、customer/CustomerGatewayImpl |
*-adapter（仅 web 版） | 对外适配层，六边形架构中的入站适配器 | web/CustomerController、mobile/CustomerMobileAdaptor、wap/CustomerWapAdaptor |
start | 启动模块 | Application.java、application.properties |
其中*-adapter模块的命名直接呼应六边形架构：web / mobile / wap 三种适配器分别对应不同端的外层入口，而controller在 3.1.0 版本中正式更名为adapter。从 CustomerController.java 可以看到，Controller 只负责接收 HTTP 请求并转发给CustomerServiceI接口，本身不包含任何业务逻辑：
@RestController public class CustomerController { @Autowired private CustomerServiceI customerService; @GetMapping(value = "/helloworld") public String helloWorld(){ return "Hello, welcome to COLA world!"; } @GetMapping(value = "/customer") public MultiResponse<CustomerDTO> listCustomerByName(@RequestParam(required = false) String name){ CustomerListByNameQry customerListByNameQry = new CustomerListByNameQry(); customerListByNameQry.setName(name); return customerService.listByName(customerListByNameQry); } @PostMapping(value = "/customer") public Response addCustomer(@RequestBody CustomerAddCmd customerAddCmd){ return customerService.addCustomer(customerAddCmd); } }而 CustomerServiceImpl.java 展示了应用服务层的典型写法：通过@CatchAndLog注解接入统一异常处理与日志（对应下文cola-component-catchlog-starter组件），并把命令（Cmd）和查询（Qry）分别委托给对应的 Executor 执行，实现 CQRS 风格的用例编排。
三、如何运行生成的应用
生成工程后，按以下步骤即可启动一个可运行的 Spring Boot 应用：
- 构建项目：在生成的项目根目录下执行
mvn install；如果不想运行测试，可加上-DskipTests参数跳过。 - 启动应用：进入
start模块目录，执行mvn spring-boot:run。启动成功后可以看到 Spring Boot 的启动成功日志。 - 验证功能：生成的应用中已经内置了一个简单的 Rest 接口，直接在浏览器访问 http://localhost:8080/helloworld 即可看到欢迎响应（返回
Hello, welcome to COLA world!）。
以cola-archetype-web的 start 模块为例，其 application.properties 默认配置了 MySQL 数据源：
project.name=${artifactId} spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver spring.datasource.url=jdbc:mysql://localhost:3306/test spring.datasource.username=root spring.datasource.password=root注意：数据源地址
localhost:3306/test、账号root/root均为模板默认值，实际使用时需要按自己的数据库环境修改。helloworld接口不依赖数据库，可直接验证应用是否启动成功。
四、COLA 六大通用组件：职责与源码级原理
除了脚手架，COLA 还沉淀了一批"开箱即用"的通用组件，收拢在 cola-components 目录下。README 中明确列出的组件及依赖关系如下：
| 组件名称 | 功能 | 依赖 |
|---|---|---|
cola-component-dto | 定义 DTO 格式，包括分页 | 无 |
cola-component-exception | 定义异常格式，主要有BizException和SysException | 无 |
cola-component-statemachine | 状态机组件 | 无 |
cola-component-domain-starter | Spring 托管的领域实体组件 | 无 |
cola-component-catchlog-starter | 异常处理和日志组件 | exception、dto组件 |
cola-component-extension-starter | 扩展点组件 | 无 |
1. cola-component-dto：统一数据交互格式
该组件制定了 DTO 的相关规范，目的有二：一是为了复用，二是使应用层面的 Logging 和异常处理 AOP 成为可能（关于 Logging 和异常处理的更多信息可参考cola-component-catchlog-starter，见其 README）。
在代码层面，DTO 体系的根是抽象类 DTO.java，它实现Serializable，并在注释中明确指出Command 与 Query 属于 CQRS 概念。其下主要派生两类：
- 请求类：
Command（命令，改变系统状态）、Query（查询，不改变状态）、PageQuery（分页查询参数）； - 响应类：
Response及其子类。
核心响应类 Response.java 定义了统一的响应三要素：success（是否成功）、errCode（错误码）、errMessage（错误信息），并提供了两个静态工厂方法：
public static Response buildSuccess() { ... } public static Response buildFailure(String errCode, String errMessage) { ... }在此基础上：
- MultiResponse.java 用于返回批量数据（如条件查询列表），提供
of(Collection<T> data)静态工厂，getData()在数据为空时返回空列表而不是 null； - PageResponse.java 用于分页查询结果，包含
totalCount、pageSize、pageIndex、data四个字段，并内置健壮性处理——当pageSize或pageIndex小于 1 时自动归 1，还提供了getTotalPages()计算总页数。
正是这种统一的响应格式，让下文catchlog组件的 AOP 能根据方法的返回类型（Response、MultiResponse、PageResponse、SingleResponse）自动构造对应的失败响应。
2. cola-component-exception：统一异常体系
该组件定义了统一的异常格式，核心是BizException与SysException两大类，二者都继承自 BaseException。以 BizException.java 为例，它的 Javadoc 明确说明："BizException is known Exception, no need retry"——即业务异常是已知异常，无需重试；而未指定错误码时默认使用BIZ_ERROR。与之相对的SysException则代表系统级异常。异常体系中还包含ExceptionFactory（异常工厂）与Assert（断言工具），便于在代码中快速抛出统一格式的异常。
3. cola-component-statemachine：轻量级状态机 DSL
该组件是"简单、轻量、性能极高的状态机 DSL 实现，解决业务中的状态流转问题"（见其 README）。从源码结构看（cola-component-statemachine），它提供了完整的 Builder 体系：
StateMachineBuilderFactory（状态机工厂）+StateMachineBuilder（状态机构建器）；ExternalTransitionBuilder/InternalTransitionBuilder/ExternalTransitionsBuilder/ParallelTransitionBuilder等过渡构建器；StateMachine/State/Transition/Event等核心模型，以及Action（动作）、Condition（条件）等回调接口；- 附带
PlantUMLVisitor、SysOutVisitor等访问器，可将状态机导出为 PlantUML 图或控制台输出，方便可视化调试。
组件还提供了对应的测试用例（cola-component-statemachine/src/test），如StateMachineTest、StateMachinePlantUMLTest、StateMachineChoiceTest，可作为使用参考。
4. cola-component-domain-starter：Spring 托管的领域实体
该组件让领域实体可以被 Spring 容器托管。从源码看（cola-component-domain-starter），其核心包括：
Entity：领域实体标记类，配合DomainFactory在@Component场景下使用；DomainFactory：领域实体工厂，负责创建被 Spring 管理的领域对象；DomainAutoConfiguration：Spring Boot 自动装配入口，通过ApplicationContextHelper获取容器上下文。
这种"Spring 托管领域实体"的设计，让贫血模型（仅数据）的实体可以借助工厂获得容器注入的能力，从而承载更丰富的领域行为。
5. cola-component-catchlog-starter：异常处理与日志切面
该组件是 README 组件表中唯一有依赖的组件（依赖exception与dto），负责统一捕获异常并把异常转换为标准 Response 输出，同时记录请求/响应日志。
其核心机制如下：
- 自定义注解 CatchAndLog.java，可标注在方法或类上（
@Target({ElementType.METHOD, ElementType.TYPE})）； - 切面 CatchLogAspect.java 使用
@Pointcut("@within(CatchAndLog) && execution(public * *(..))")拦截所有标注了@CatchAndLog的类的 public 方法，并设置@Order(1)保证切面优先级； around环绕通知统一执行logRequest→joinPoint.proceed()→logResponse流程，并统计耗时（COST: {}ms）；handleException按异常类型分流处理：BizException：仅warn级日志（debug 模式下才打印堆栈），返回对应错误码与消息；SysException：error级日志并打印堆栈；- 其他未知异常：统一记为
UNKNOWN_ERROR； - 无论哪种异常，都通过
ResponseHandlerFactory根据方法返回类型（Response/MultiResponse等）构造对应的失败响应——这正是 dto 组件统一格式的价值所在。
在 archetype 生成的应用中，CustomerServiceImpl上的@CatchAndLog注解就是该组件的典型使用方式。
6. cola-component-extension-starter：扩展点组件
扩展点组件用于解决多业务、多场景下的差异化逻辑问题，是 COLA 支持业务定制化（如不同 BU 的客户校验规则不同）的关键能力。其核心源码位于 cola-component-extension-starter：
- Extension.java：扩展注解，包含
bizId、useCase、scenario三个维度，默认值来自BizScenario的默认常量，即一个扩展由"业务 + 用例 + 场景"三元组唯一定位； - ExtensionExecutor.java：扩展执行器，
locateExtension方法实现了从全量坐标到默认坐标逐级回退的查找策略。源码注释给出了清晰的检索路径：- 先用完整命名空间查找（如
ali.tmall.supermarket）； - 未命中则退回默认场景（如
ali.tmall.#defaultScenario#）； - 再退回默认用例 + 默认场景（如
ali.#defaultUseCase#.#defaultScenario#）； - 仍找不到则抛出
ExtensionException(extension_not_found)；
- 先用完整命名空间查找（如
ExtensionRepository：扩展注册仓库，以ExtensionCoordinate为 key 保存所有已注册扩展；ExtensionBootstrap/ExtensionRegister：负责在 Spring 启动时扫描并注册所有@Extension标注的 Bean。
组件自带的测试（cola-component-extension-starter/src/test）如ExtensionTest、MultiCoordinateTests、ExtensionRegisterTest展示了多业务、多场景坐标下的扩展解析行为，可直接参考。
五、版本迭代与演进脉络
README 的"版本迭代"章节梳理了 COLA 的演进历史（其中早期版本附有作者 Frank Zhang 的系列博客链接，仓库内不包含这些文章正文，此处仅保留仓库可验证的要点）：
- 5.0.0 版本：
- 支持 JDK 17 与 Spring Boot 3.x；
- 新增
cola-archetype-light，支持基于 package 的轻量级分层架构（不需要拆分成多模块，而是通过包名划分 adapter / application / domain / infrastructure 层次，其模板可参考 cola-archetype-light 的 archetype-resources）； - 新增
cola-component-unittest组件，支持新的单元测试模式； - 增强
cola-component-test-container组件，支持 JUnit 5 的 Extension。
- 3.1.0 版本：进一步简化
cola-core，只保留扩展能力；将exception从cola-core移入cola-common；对 archetype 的分包逻辑重构为按domain划分；将cola-archetype-web中的controller改名为adapter，呼应六边形架构命名。 - 2.0.0 / 1.0.0 版本：属于早期架构版本，相关迭代说明以作者博客文章为准（仓库内未收录正文）。
事实说明：README 中 4.0.0、3.0.0、2.0.0、1.0.0 等早期版本仅提供了外部博客链接，本文只转述 5.0.0 与 3.1.0 中可被仓库源码验证的内容，不展开无法核实的外部资料。
六、总结与上手路径
COLA 的价值总结起来是两条：
- 架构层面：给出了一套以业务为核心、强调分层解耦的应用架构规范，并且用 Archetype 把它变成"一行命令即可生成"的工程模板，让整洁架构不再停留在 PPT 上；
- 组件层面：把 DTO 规范、异常体系、状态机、领域实体托管、异常日志切面、扩展点等通用能力沉淀为可独立引用的组件，直接提升研发效率与一致性。
推荐的快速上手路径：
- 阅读本文第二章，用
cola-framework-archetype-web命令生成一个 Web 工程； - 按第三章执行
mvn install与mvn spring-boot:run，访问 http://localhost:8080/helloworld 验证启动； - 对照第四章组件说明，逐个阅读 cola-components 下的组件源码与其自带测试，理解每个组件在生成工程中的落点（例如
@CatchAndLog在CustomerServiceImpl上的作用）； - 需要构建多版本兼容的复杂业务时，深入 cola-component-extension-starter 与 cola-component-statemachine 的测试用例，掌握扩展点坐标与状态机 DSL 的用法。
如果想要直接查看完整代码与示例工程，可通过git clone https://link.gitcode.com/i/365bc158dbf969533ecda37a810526b7获取本仓库，其中 cola-samples 目录下还提供了 craftsman（工匠平台）等完整示例应用，可作为学习 COLA 落地写法的进阶材料。
- 后端
【免费下载链接】COLA
🥤 COLA: Clean Object-oriented & Layered Architecture
相关推荐
COLA架构详解：阿里巴巴整洁面向对象分层架构的终极指南 🥤
COLA架构详解：阿里巴巴整洁面向对象分层架构的终极指南 🥤 想要构建 整洁、可维护、可扩展 的企业级Java应用吗？COLA架构正是你需要的解决方案！COL
后端COLA v5完整指南：如何快速构建整洁面向对象分层架构 🥤
COLA v5完整指南：如何快速构建整洁面向对象分层架构 🥤 在当今复杂的软件开发环境中， COLA v5 作为Clean Object oriented &
后端? COLA v5：构建整洁面向对象分层架构的利器
? COLA v5：构建整洁面向对象分层架构的利器 在软件开发的世界里，架构的选择往往决定了项目的成败。今天，我们要向大家推荐的是一款由阿里巴巴开源的、名为CO
后端
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
