Understanding COLA: Clean Object‑Oriented and Layered Architecture for Backend Development

Modern internet business code often suffers from rapid iteration, frequent personnel changes, inconsistent coding habits, and a lack of time for refactoring, leading to technical debt and code decay.

What is COLA?

COLA, proposed by Alibaba’s Zhang Jianfei, stands for Clean Object‑Oriented and Layered Architecture. It offers a concrete, reusable code‑structure guideline that can be directly applied to projects, aiming to slow code rot and improve development efficiency.

Overall COLA Architecture

COLA divides an application into five main layers:

Adapter Layer : Handles request routing and adapts to different front‑ends (web, wireless, WAP). It is analogous to the MVC controller.

Client Layer : Defines service interfaces (API) and DTOs without implementation, allowing other modules to call services via RPC.

App Layer : Implements business use‑cases (executors), processes commands/queries, and also hosts consumers and schedulers.

Domain Layer : Contains core business logic, domain entities, domain services, and gateways (SPI) that abstract external dependencies.

Infrastructure Layer : Provides technical details such as MyBatis mappers, configuration files, and gateway implementations.

Module Structure (Maven)

The parent pom.xml lists sub‑modules like demo-web-client , demo-web-adapter , demo-web-app , demo-web-domain , demo-web-infrastructure , and start .

<modules>
  <module>demo-web-client</module>
  <module>demo-web-adapter</module>
  <module>demo-web-app</module>
  <module>demo-web-domain</module>
  <module>demo-web-infrastructure</module>
  <module>start</module>
</modules>

Start Layer

The start module is a Spring Boot entry point that contains only bootstrapping code and global configuration, making it easy for newcomers to run the project.

Adapter Layer

Acts as the controller layer; for example, a CustomerController receives HTTP requests and delegates to the client interface.

@RestController
public class CustomerController {
    @Autowired
    private CustomerServiceI customerService;

    @GetMapping(value = "/customer")
    public MultiResponse
listCustomerByName(@RequestParam(required = false) String name) {
        CustomerListByNameQry qry = new CustomerListByNameQry();
        qry.setName(name);
        return customerService.listByName(qry);
    }
}

Client Layer

Contains api (service interface definitions) and dto (data transfer objects). The actual implementation lives in the App layer.

App Layer

Implements the business logic defined by the client interfaces. Example implementation:

@Service
@CatchAndLog
public class CustomerServiceImpl implements CustomerServiceI {
    @Resource
    private CustomerListByNameQryExe customerListByNameQryExe;

    @Override
    public MultiResponse
listByName(CustomerListByNameQry qry) {
        return customerListByNameQryExe.execute(qry);
    }
}

Domain Layer

Organized by business domain (e.g., customer , order ) and includes:

Domain entities (e.g., Customer with business methods).

Domain services (capabilities).

Gateways (SPI interfaces) that are implemented in the Infrastructure layer.

@Data
@Entity
public class Customer {
    private String customerId;
    private String memberId;
    private long registeredCapital;
    // business methods like isBigCompany(), checkConflict()
}

public interface CustomerGateway {
    Customer getByById(String customerId);
}

Infrastructure Layer

Provides concrete implementations for gateways, database mappers, and configuration files.

@Component
public class CustomerGatewayImpl implements CustomerGateway {
    @Autowired
    private CustomerMapper customerMapper;

    @Override
    public Customer getByById(String customerId) {
        CustomerDO do = customerMapper.getById(customerId);
        // Convert DO to domain entity
        return null; // conversion omitted for brevity
    }
}

Key Characteristics of COLA

Domain‑first packaging: first by business domain, then by functional concerns, limiting code decay to a specific domain.

Decoupling of business logic from external dependencies via gateways.

Provides a ready‑to‑use code template that can be directly integrated into projects.

Limitations

While COLA reduces boilerplate, it can lead to an explosion of DTOs because each business operation defines its own request/response objects, increasing maintenance overhead.

Conclusion

COLA offers a clear, layered approach to building maintainable backend services, especially for fast‑moving internet businesses, but teams should balance its rigor with practical needs to avoid over‑engineering.