Java COLA 架构

COLA = Clean Object-Oriented and 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      │

依赖方向

Adapter → App → Domain ← Infrastructure
              ↘      ↙
               Client

| 层 | 职责 | 实现 | |---|------|------| | Adapter | 接收外部请求 | Controller, Scheduler, Consumer | | App | 用例编排 | ServiceImpl, CmdExe, QryExe | | Domain | 核心业务逻辑 | Entity, ValueObject, Gateway, Ability | | Infrastructure | 技术实现 | GatewayImpl, Mapper, Config | | Client | DTO 定义 | Command, Query, CO, ServiceI |

目录结构

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/                    # 启动模块

命名规范

| 类型 | 后缀 | 位置 | |------|------|------| | 命令 | Cmd | client/dto/command | | 查询 | Qry | client/dto/query | | 命令执行器 | CmdExe | app/command | | 查询执行器 | QryExe | app/command/query | | 客户端对象 | CO | client/dto/clientobject | | 数据对象 | DO | infrastructure | | 服务接口 | ServiceI | client/api | | 服务实现 | ServiceImpl | app/service | | 网关接口 | Gateway | domain/gateway | | 网关实现 | GatewayImpl | infrastructure/gatewayimpl | | 转换器 | Convertor | infrastructure/convertor |

快速创建项目

COLA 提供两种 Archetype：

cola-archetype-web（Web 应用）

适用于 Adapter 和后端服务一体的 Web 应用：

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

生成结构：

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（纯后端服务）

适用于纯后端服务（无 Web 层）：

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

生成结构：

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

COLA 组件

| 组件 | 功能 | |------|------| | cola-component-dto | Response, Command, Query, PageResponse | | cola-component-exception | BizException, SysException, ErrorCode | | cola-component-catchlog-starter | @CatchAndLog 异常捕获和日志 | | cola-component-extension-starter | 扩展点机制（多业务线支持） | | cola-component-statemachine | 状态机（订单流转等） | | cola-component-domain-starter | Spring 托管领域实体 | | cola-component-ruleengine | 规则引擎 | | cola-component-test-container | 测试容器 |

代码模板

详细代码示例请参考：

• DTO 和 Response: references/dto.md
• Service 和执行器: references/service.md
• Gateway 模式: references/gateway.md
• COLA 组件详解: references/components.md
• 完整示例: references/example.md

重构检查清单

1. 创建 adapter/app/client/domain/infrastructure/start 模块
2. 配置 Maven 依赖关系
3. 定义 Command、Query、CO 类
4. 创建 CmdExe/QryExe 和 ServiceImpl
5. 定义 Gateway 接口和 GatewayImpl
6. 创建 Convertor 转换器
7. 迁移 Controller 到 adapter/web