COLA v5: Alibaba's Clean Object-oriented and Layered Architecture for Java

The problem COLA actually addresses is package sprawl, not dependency inversion

Most Java services do not fail because someone drew the wrong hexagon. They fail because the controller, the service, the mapper and the DTO end up in one package, and after two years nobody can tell which class is allowed to call which. COLA's stated aim is to define a good application structure and govern application complexity, which in practice means prescribing where classes live and how layers depend on each other.

The README frames this as moving from a disordered state to an ordered one, and lists the architecture's core job as defining a good application structure and providing best-practice guidance. That is a documentation-and-convention product more than a runtime product. The repository backs it up with two things: archetypes that generate a project already laid out that way, and components that fill in the cross-cutting pieces you would otherwise write yourself.

Who is it for? Java teams building a service from scratch, or rebuilding one, who want the layering decision made once and written into the build. It is not aimed at teams maintaining a working monolith that already has its own conventions; nothing here migrates an existing codebase.

Two archetypes, seven components, and one repository layout

The repository splits cleanly. cola-archetypes holds the project generators, cola-components holds the reusable libraries, and cola-samples holds examples. The README describes two archetypes: cola-archetype-service for a pure backend service, and cola-archetype-web for an application that combines the adapter layer and the backend service. The v5 release notes add a third, cola-archetype-light, described as supporting a new package-based lightweight layered architecture.

The component table in the README is the more concrete half of the story. cola-component-dto defines the DTO format including pagination. cola-component-exception defines the exception format, with BizException and SysException as the two named types. cola-component-statemachine is a state machine component. cola-component-domain-starter provides Spring-managed domain entities. cola-component-catchlog-starter handles exception handling and logging and depends on the exception and dto components. cola-component-extension-starter provides the extension-point mechanism. cola-component-test-container is a test container component.

Notice the dependency column: five of the seven list no dependencies at all. That is a deliberate shape. The DTO, exception, state machine and extension-point pieces are standalone libraries, so pulling one in does not drag a framework behind it. The catchlog starter is the exception, because it composes two of the others.

The extension-point component is the part worth understanding before adopting. It is the mechanism behind COLA's claim to offer tooling and practice guidance rather than just ideas, and v3.1.0 notes that cola-core was simplified to keep only the extension capability. If you are evaluating COLA for a plugin-style codebase, that component is the reason to look.

Generating a COLA web project and hitting the hello-world endpoint

The README gives the archetype command directly. Run it from a shell with Maven available, substituting your own group and artifact identifiers. The archetype group is com.alibaba.cola and the version is 5.0.0.

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

On success the README says you get an application source tree, illustrated in the README with a screenshot rather than a text listing. That is a small annoyance: you cannot see the generated package layout without running the command.

Building and running is three steps. From the project directory, install the modules; the README notes you can add -DskipTests if you do not want to run tests. Then move into the start directory and run the Spring Boot plugin.

mvn install
cd start
mvn spring-boot:run

A successful start shows Spring Boot's startup banner. The generated application already implements one REST request, and the README says to test it by opening http://localhost:8080/helloworld in a browser. That endpoint is your proof that the generated wiring works before you add anything.

For a non-web service the command is the same shape with a different artifact: cola-framework-archetype-service instead of cola-framework-archetype-web, and a service-oriented groupId such as com.alibaba.cola.demo.service. The README does not document the light archetype's generate command, only its existence in the release notes.

The archetype generates structure; it does not enforce it

This is the limitation to internalise before you sell COLA to a team. An archetype is a one-time scaffold. After generation, nothing stops a developer from calling a mapper straight from an adapter class or putting a repository interface in the wrong package. COLA's architecture is a convention plus a starting layout, and the README's own framing is about defining structure and providing practice guidance, not about compile-time enforcement.

If you want layering that fails the build, you need something else: ArchUnit tests, module boundaries in a multi-module Maven build, or Java modules. COLA's multi-module layout helps, because a dependency between modules can be declared or withheld in Maven, but that is your build configuration, not COLA's.

The second boundary is version currency. v5.0.0 is the release that supports JDK 17 and Spring Boot 3.x, and the README's Java badge says Java 17+. If your organisation is on JDK 8 or 11, v5 is not the version for you, and the README does not describe a supported path for running v5 on older runtimes. Earlier releases exist (4.3.2, 4.3.1) but the README's version history is a list of links to external blog posts, not upgrade instructions. There is no documented migration guide from v4 to v5 in the README.

Third: the README, release notes and component table are the documentation surface here. The README does not document rollback, and it does not describe what happens when you regenerate or update an archetype-generated project. Treat the generated code as yours from the moment it lands.

COLA against plain Spring Boot and against an enforced-architecture linter

The honest comparison is not COLA versus another architecture framework. It is COLA versus doing it yourself on plain Spring Boot.

Plain Spring Boot gives you a runtime and no opinion on package layout. You would then hand-write a DTO base class with pagination fields, a BizException and SysException pair, an exception-and-logging aspect, and an extension-point lookup. That is roughly the work the cola-components table describes, and it is not enormous. What you gain by writing it yourself is that it matches your existing conventions exactly. What you lose is the shared vocabulary: a new hire who has seen COLA recognises cola-component-dto and cola-component-exception immediately.

The second comparison is against a build-time architecture checker such as ArchUnit. ArchUnit tests what your code does. COLA shapes what your code looks like before you write it. They are complementary, and a team that cares about layering will likely end up with both: COLA for the starting structure, ArchUnit for the rule that keeps it.

The third option, and the one worth naming explicitly, is Spring Modulith, which takes the opposite approach: instead of generating a package layout, it verifies module boundaries and documents them from the code you already have. COLA is prescriptive-first; Modulith is verification-first. If your codebase already exists, Modulith's model fits better. If you are starting clean, COLA's archetype saves you the first week of arguing about package names.

Licence and the cost of staying current

COLA is licensed under LGPL-2.1, per the README's licence badge and the LICENSE file. That is a weaker copyleft than the GPL but it is still copyleft, and it is worth understanding before you ship. The LGPL was written with libraries in mind: the common reading is that you can link to an LGPL library from a proprietary application provided you meet the licence's conditions around the library itself, including allowing replacement of the library. COLA is distributed as Maven artifacts under com.alibaba.cola, which is exactly the linking case the licence was designed for. This is not legal advice; if your product is distributed to customers, have your own counsel read the LGPL-2.1 text rather than relying on a summary.

Maintenance cost has two parts. The first is upgrade cost. The last release listed is v5.0.0 from 2024-06-02, and the jump from 4.3.2 to 5.0.0 moved the baseline to JDK 17 and Spring Boot 3.x. That is a major-version migration for anyone on v4, and the README points to external blog posts for the older version notes rather than providing an in-repo upgrade path. Budget for it as a real project.

The second is the cost of the archetype's output. Generated code is a starting point that becomes your code. When a new COLA version changes the scaffold, there is no documented mechanism in the README for reconciling your modified project against the new template. You will diff by hand or regenerate into a scratch directory and copy across. The repository's last push was on 2026-08-31, so the project is not dormant, but that does not reduce the reconciliation work.

Editorial conclusion

Adopt COLA if you are starting a Java service on JDK 17 and Spring Boot 3.x and want package boundaries, a DTO and exception convention, and an extension-point mechanism that is already wired into Spring. Do not adopt it if you expect the archetype to enforce layering for you, or if your build is pinned to an older JDK. Before committing, generate both archetypes, run the hello-world endpoint, and read the LGPL-2.1 text to confirm it fits how you distribute your service.

Frequently asked questions

Official sources

1. alibaba/COLA on GitHub
2. Issues
3. License: LGPL-2.1
4. README
5. Releases