COLA：阿里整洁面向对象分层架构脚手架创建与使用指南

官方信息

项目背景：为什么需要一套应用架构

COLA 是 Clean Object-Oriented and Layered Architecture 的缩写，代表「整洁面向对象分层架构」，目前已经发展到第五代 COLA v5。它把自己分为两个部分：一部分是 COLA 架构，另一部分是 COLA 组件。除了开源仓库，作者还围绕 COLA 写了多本技术书籍，并在社区持续分享架构思想，帮助开发者理解如何用 COLA 这类「AI 友好的应用架构」来组织 Harness 工程。

要理解 COLA 在解决什么问题，先要理解「架构」这个词本身。架构的意义就是「要素结构」——要素是组成架构的重要元素，结构是要素之间的关系。而应用架构的意义则在于三点：第一，定义一套良好的结构；第二，治理应用复杂度，降低系统的熵值；第三，让系统从随心所欲的混乱状态，走向井井有条的有序状态。很多业务系统随着版本迭代，代码越来越乱、模块之间相互缠绕、改一个需求要动七八个文件，本质上就是缺少一套被所有人遵守的、稳定的应用结构。COLA 架构就是为此而生，它的核心职责就是定义良好的应用结构，提供最佳应用架构的最佳实践。通过不断探索，团队发现良好的分层结构、良好的包结构定义，可以帮助我们治理混乱不堪的业务应用系统，让代码重新变得可维护。

COLA 区别于其他架构思想的地方在于：它不只讲理念，还提供了可以直接落地的工具和实践指导。无论是六边形架构、洋葱圈架构还是整洁架构，大家都提倡以业务为核心、解耦外部依赖、分离业务复杂度和技术复杂度；而 COLA 在这些思想之上，进一步提供了 Maven Archetype 脚手架和一组通用组件，让你打开终端就能生成一个符合 COLA 规范的工程骨架，而不是对着架构图不知从何下手。

在 COLA 定义的工程结构里，业务复杂度和技术复杂度被刻意分开：业务核心逻辑放在领域层和应用层，不依赖 Web、消息、数据库等具体技术细节；而 HTTP 接口、消息消费、外部 RPC 调用等技术实现，被收口在对外的适配层。这样做的好处是，当业务规则发生变化时，你不需要同时修改接口层和数据层；当外部接入方式从 HTTP 换成消息队列时，业务代码几乎不用动。COLA 把这种「以业务为中心、外围都是可替换的适配器」的结构固化到了 Archetype 模板里，开发者只要照着包结构写代码，就天然地遵循了这套分层原则。此外，COLA 还引入了扩展点机制，用 cola-component-extension-starter 来承载不同业务线、不同租户之间的差异化逻辑，避免在核心代码里塞满 if-else。

环境要求与安装

COLA v5 要求 JDK 17 及以上，并基于 Spring Boot 3.x。它本身不是一个需要单独安装的服务，而是通过 Maven Archetype 的方式在开发机上生成工程骨架。只要本机配置好了 JDK 17 与 Maven，执行下面的命令即可。

生成 Web 应用工程

下面这条命令会创建一个 adapter 和后端服务一体的 Web 应用工程：

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

生成纯后端服务工程

如果不需要 Web 层，只想生成一个纯后端服务工程，使用下面这条命令即可，二者的区别只在于 archetypeArtifactId：

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

这两个 Archetype 位于仓库的 cola-archetypes 目录下：cola-archetype-service 用来创建纯后端服务，cola-archetype-web 用来创建 adapter 与后端服务一体的 Web 应用。

运行与使用

工程生成成功后，按照下面的步骤即可跑起来：

1. 在项目根目录下运行 mvn install；如果不想运行测试，可以加上 -DskipTests 参数。
2. 进入 start 目录，执行 mvn spring-boot:run。
3. 运行成功后，可以看到 Spring Boot 启动成功的界面。生成的应用中已经预置了一个简单的 REST 请求，在浏览器中访问 http://localhost:8080/helloworld 即可测试。这个预置接口的意义不在于它本身多复杂，而在于它完整地走通了从 HTTP 入口到应用层再到返回值的整条链路，让你一眼就能看出新业务代码应该加在哪一层、用什么样的写法去扩展。

生成的工程会按照 COLA 规范划分好包结构，把业务逻辑、领域对象、外部适配、消息处理等分别放在不同的层次里，避免所有代码堆在一个 controller 里。以 Web 工程为例，生成后通常是一个多模块 Maven 工程，里面既有负责对外暴露接口的适配层，也有承载业务编排的应用层，以及承载领域模型的领域层和负责基础设施实现的领域层实现；start 模块则是真正启动 Spring Boot 的入口。你只需要在对应的包里补充业务代码，结构就不会散掉。

对于中大型业务系统，这种约定带来的最大价值是「可预测」：任何一个新加入团队的工程师，拿到一个 COLA 工程都能很快找到接口在哪、业务逻辑在哪、数据访问在哪，code review 时也能聚焦在真正的业务差异上，而不是争论某个类应该放在哪个包。这也是 COLA 团队反复强调「治理复杂度、降低系统熵值」的实际含义——结构本身就是一种生产力。

COLA 组件：开箱即用的通用工具

除了架构骨架，COLA 还在 cola-components 目录下沉淀了一批非常有用的通用组件，用来提升研发效率。它们都可以被单独引入，按需使用：

这些组件覆盖了日常开发中最常见的横切关注点：统一的数据传输对象、业务异常与系统异常的划分、轻量级状态机、领域对象的 Spring 托管、统一的异常捕获与日志、用于业务定制的扩展点机制，以及测试容器。它们之间的依赖关系非常简单，除了 catchlog-starter 依赖 exception 和 dto 之外，其余组件都是零依赖，可以按需引入。

具体来看，cola-component-dto 规定了所有跨层传输对象的基类，并内置了分页结构，让 Controller 返回值、Service 出入参都有统一形态；cola-component-exception 把异常分成 BizException（业务异常，例如库存不足）和 SysException（系统异常，例如数据库连接失败）两大类，便于上层统一拦截和错误码处理；cola-component-statemachine 提供了一个轻量级状态机实现，适合订单、审批这类有明确状态流转的业务，避免手写大量状态判断；cola-component-domain-starter 让领域实体能够被 Spring 托管，方便在领域对象里注入基础设施；cola-component-catchlog-starter 把异常捕获和日志打印收拢到一处，减少每个接口重复写 try-catch；cola-component-extension-starter 是 COLA 差异化业务的核心，用扩展点隔离不同业务变体；cola-component-test-container 则为集成测试提供可复用的测试容器。

版本迭代

COLA 经过多次迭代，每一代都在简化核心、贴近社区：

• 5.0.0 版本：这是目前最新的大版本，核心变化有四点：第一，全面支持 JDK 17 和 Spring Boot 3.x，跟上了 Java 生态的主线升级；第二，新增 cola-archetype-light，支持新的基于 package 的轻量级分层架构，让工程结构不再被多模块强制绑定；第三，新增 cola-component-unittest 组件，支持新的单元测试写法；第四，增强 cola-component-test-container 组件，支持 JUnit 5 的 Extension，让集成测试写起来更顺手。
• 4.0.0 版本：参见官方博客《COLA 4.0 发布》。
• 3.1.0 版本：进一步简化 cola-core，只保留扩展能力；将 exception 从 cola-core 移到 cola-common；对 Archetype 中的分包逻辑进行重构，改成按 domain 划分；将 cola-archetype-web 中的 controller 改名为 adapter，以呼应六边形架构的命名。这一版是 COLA 思想从「大而全」转向「小而精」的关键节点，核心只留最有用的扩展点能力，其余一律下沉到通用组件。
• 3.0.0 版本：参见官方博客《COLA 3.0 发布》。
• 2.0.0 版本：参见官方博客《COLA 2.0 发布》。
• 1.0.0 版本：参见官方博客《COLA 1.0 发布》。从 1.0 到 5.0，COLA 的演进主线非常清晰：不断简化核心、让分层更贴近业务、让组件更易独立使用，同时紧跟 JDK 与 Spring Boot 的版本节奏。

常见问题（FAQ）

问：COLA 是一个框架吗？学了会不会被绑定？ 答：COLA 更像是一套「应用架构规范 + 脚手架 + 通用组件」的组合，核心价值在于分层和包结构约定。它基于 Spring Boot 构建，业务代码仍然是普通的 Spring 代码，迁移成本主要在结构调整上，而不是被某个私有 API 锁定。

问：v5 对 JDK 有什么要求？ 答：COLA v5 要求 JDK 17 及以上，并基于 Spring Boot 3.x。如果团队还停留在 JDK 8/11，需要先升级运行环境才能使用 v5。

问：service 工程和 web 工程怎么选？ 答：只需要对内提供 RPC 或 REST 服务、不需要 Web 适配层的，用 cola-archetype-service；需要把 HTTP 接口、消息等外部请求统一收口在 adapter 层的，用 cola-archetype-web。

问：为什么 3.x 要把 controller 改名为 adapter？ 答：这是为了呼应六边形架构（端口与适配器）的命名思想，把「对外请求的入口」统一抽象成适配器，让业务核心逻辑与外部接入方式解耦，将来换成消息、定时任务等其他入口时不用动业务层。

问：组件之间可以单独用吗？ 答：可以。除 cola-component-catchlog-starter 依赖 exception 和 dto 外，其余组件都是零依赖，需要哪个引哪个，不必把整个 COLA 全家桶都引进来。

问：COLA 适合什么样的团队和项目？ 答：它最适合业务持续演进、人员会流动的中大型 Java 业务系统——这类项目最怕代码越写越乱。对于一个只有两三个人、需求简单、一两个月就下线的小工具，引入 COLA 的分层规范反而可能显得重，按需裁剪即可。

问：v5 里新增的 cola-archetype-light 是什么？ 答：它是 v5 提供的一个更轻量的 Archetype，支持基于 package 的轻量级分层架构，不强制多模块拆分，适合想保留 COLA 思想但又不想被多模块工程结构束缚的团队。

问：怎么参与 COLA 开发？ 答：仓库完整开放在 GitHub 上，支持 Gitpod 一键在线开发，也欢迎大家提 issue、修 bug、补组件；所有贡献者都会出现在贡献者列表中。

问：COLA 和 Spring Boot 是什么关系？ 答：COLA 不是要替代 Spring Boot，而是在 Spring Boot 之上加一层「应用结构约定」。生成的工程最终仍然是一个普通的 Spring Boot 应用，启动方式、依赖注入、配置文件都和普通 Spring Boot 项目一致；COLA 帮你做的，是把代码组织得更有条理，而不是引入一套新的编程模型。

问：COLA 里为什么要强调扩展点？ 答：业务系统经常遇到同一段流程在不同业务线、不同租户下行为不一样的情况。如果直接在核心代码里写 if-else，很快就会变成难以维护的面条代码。COLA 的扩展点组件允许你把这些差异实现成独立的扩展，核心流程只调用扩展点接口，运行时再按业务标识路由到具体实现，既保持了主干清晰，又能灵活支撑差异化需求。

跳转链接

• GitHub 仓库：alibaba/COLA
• Maven 中央仓库：com.alibaba.cola
• GitHub Releases：alibaba/COLA/releases
• 贡献指南：github.com/alibaba/COLA/graphs/contributors
• 在线开发环境：Gitpod 打开 COLA