java-cola-skill

Java COLA Architecture

COLA = Clean Object-Oriented and Layered Architecture

Layered Architecture

                        ┌─────────────────────────────────────┐
  Driving Adapter:      │  浏览器  │  定时器  │  消息队列      │
                        └─────────────────────────────────────┘
                                         ↓
  VO ←─────────────── ┌─────────────────────────────────────┐
  (View Object)       │            Adapter 层                │
                      │  controller │ scheduler │ consumer   │
                      └─────────────────────────────────────┘
                                         ↓
  DTO ←────────────── ┌─────────────────────────────────────┐
  (Data Transfer      │              App 层                  │
   Object)            │       service  │  executor           │
                      └─────────────────────────────────────┘
                                         ↓
  Entity ←─────────── ┌─────────────────────────────────────┐
                      │            Domain 层                 │
                      │   gateway │ model │ ability          │
                      └─────────────────────────────────────┘
                                         ↑
  DO ←─────────────── ┌─────────────────────────────────────┐
  (Data Object)       │        Infrastructure 层             │
                      │  gatewayImpl │ mapper │ config       │
                      └─────────────────────────────────────┘
                                         ↓
  Driven Adapter:     │    DB    │   Search   │    RPC      │

Dependency Direction

Adapter → App → Domain ← Infrastructure
              ↘      ↙
               Client

Layer	Responsibility	Implementation
Adapter	Receive external requests	Controller, Scheduler, Consumer
App	Use case orchestration	ServiceImpl, CmdExe, QryExe
Domain	Core business logic	Entity, ValueObject, Gateway, Ability
Infrastructure	Technical implementation	GatewayImpl, Mapper, Config
Client	DTO definition	Command, Query, CO, ServiceI

Directory Structure

project-name/
├── project-adapter/          # Controller
│   └── com/company/project/web/
├── project-app/              # Service 实现
│   └── com/company/project/
│       ├── command/          # *CmdExe.java
│       │   └── query/        # *QryExe.java
│       └── service/          # *ServiceImpl.java
├── project-client/           # API 定义
│   └── com/company/project/
│       ├── api/              # *ServiceI.java
│       └── dto/
│           ├── command/      # *Cmd.java
│           ├── query/        # *Qry.java
│           └── clientobject/ # *CO.java
├── project-domain/           # 领域层
│   └── com/company/project/domain/
│       ├── {aggregate}/      # Entity, ValueObject
│       └── gateway/          # *Gateway.java
├── project-infrastructure/   # 基础设施
│   └── com/company/project/
│       ├── gatewayimpl/      # *GatewayImpl.java
│       └── convertor/        # *Convertor.java
└── start/                    # 启动模块

Naming Conventions

Type	Suffix	Location
Command	`Cmd`	client/dto/command
Query	`Qry`	client/dto/query
Command Executor	`CmdExe`	app/command
Query Executor	`QryExe`	app/command/query
Client Object	`CO`	client/dto/clientobject
Data Object	`DO`	infrastructure
Service Interface	`ServiceI`	client/api
Service Implementation	`ServiceImpl`	app/service
Gateway Interface	`Gateway`	domain/gateway
Gateway Implementation	`GatewayImpl`	infrastructure/gatewayimpl
Convertor	`Convertor`	infrastructure/convertor

Quick Project Creation

COLA provides two Archetypes:

cola-archetype-web (Web Application)

Suitable for Web applications that integrate Adapter and backend services:

mvn archetype:generate \
    -DgroupId=com.company.project \
    -DartifactId=my-web-app \
    -Dversion=1.0.0-SNAPSHOT \
    -Dpackage=com.company.project \
    -DarchetypeArtifactId=cola-framework-archetype-web \
    -DarchetypeGroupId=com.alibaba.cola \
    -DarchetypeVersion=5.0.0

Generated structure:

my-web-app/
├── my-web-app-adapter/      # Controller、定时任务、消息监听
├── my-web-app-app/          # Service 实现、执行器
├── my-web-app-client/       # API 接口、DTO
├── my-web-app-domain/       # 领域模型、Gateway 接口
├── my-web-app-infrastructure/  # Gateway 实现、Mapper
└── start/                   # 启动模块

cola-archetype-service (Pure Backend Service)

Suitable for pure backend services (without Web layer):

mvn archetype:generate \
    -DgroupId=com.company.project \
    -DartifactId=my-service \
    -Dversion=1.0.0-SNAPSHOT \
    -Dpackage=com.company.project \
    -DarchetypeArtifactId=cola-framework-archetype-service \
    -DarchetypeGroupId=com.alibaba.cola \
    -DarchetypeVersion=5.0.0

Generated structure:

my-service/
├── my-service-app/          # Service 实现、执行器
├── my-service-client/       # API 接口、DTO（供其他服务调用）
├── my-service-domain/       # 领域模型、Gateway 接口
├── my-service-infrastructure/  # Gateway 实现、Mapper
└── start/                   # 启动模块

COLA Components

Component	Function
`cola-component-dto`	Response, Command, Query, PageResponse
`cola-component-exception`	BizException, SysException, ErrorCode
`cola-component-catchlog-starter`	@CatchAndLog exception catching and logging
`cola-component-extension-starter`	Extension point mechanism (multi-business line support)
`cola-component-statemachine`	State machine (order flow, etc.)
`cola-component-domain-starter`	Spring-managed domain entities
`cola-component-ruleengine`	Rule engine
`cola-component-test-container`	Test container

Code Templates

For detailed code examples, please refer to:

DTO and Response: references/dto.md
Service and Executor: references/service.md
Gateway Pattern: references/gateway.md
COLA Component Details: references/components.md
Complete Example: references/example.md

Refactoring Checklist

Create adapter/app/client/domain/infrastructure/start modules
Configure Maven dependencies
Define Command, Query, and CO classes
Create CmdExe/QryExe and ServiceImpl
Define Gateway interface and GatewayImpl
Create Convertor
Migrate Controller to adapter/web