# cola-demo

**Repository Path**: code_enthusiasts/cola_demo

## Basic Information

- **Project Name**: cola-demo
- **Description**: 基于cola架构下ddd demo项目
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-10-15
- **Last Updated**: 2025-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## DDD Demo By Alibaba Cola

# 一、项目简介

领域驱动设计项目Demo，采用Alibaba Cola脚手架协助分层。采用JDK 1.8 + Spring Boot 2.7.18 + Mysql等技术栈

## 1.1 系统功能

|功能 | 描述 |
| -- | --- |
| 用户管理 | 用户是系统操作者，该功能主要完成系统用户配置 |
| 在线用户 | 当前系统中活跃用户状态监控，支持手动踢下线 |
| 角色管理 | 角色菜单权限分配、设置角色按机构进行数据范围权限划分 |
| 菜单管理 | 配置系统菜单、操作权限、按钮权限标识等，本地缓存提供性能 |
| 部门管理 | 配置系统组织机构（公司、部门、小组），树结构展现支持数据权限 |
| 岗位管理 | 配置系统用户所属担任职务 |
| 租户管理 | 配置系统租户，支持 SaaS 场景下的多租户功能 |
| 字典管理 | 对系统中经常使用的一些较为固定的数据进行维护 |
| 短信管理 | 短信渠道、短息模板、短信日志，对接阿里云、腾讯云等主流短信平台 |
| 邮件管理 | 邮箱账号、邮件模版、邮件发送日志，支持所有邮件平台 |
| 站内信 | 系统内的消息通知，提供站内信模版、站内信消息 |
| 通知公告 | 系统通知公告信息发布维护 |
| 操作日志 | 系统正常操作日志记录和查询，集成 Swagger 生成日志内容 |
| 登录日志 | 系统登录日志记录查询，包含登录异常 |
| Api接口日志 | 系统Api接口日志记录查询，包含调用异常 |
| Oauth2 Client管理 | 管理 SSO 单点登录的应用，支持多种 OAuth2 授权方式 |
| 文件服务 | 支持将文件存储到 S3（MinIO、阿里云、腾讯云、七牛云）、本地等 |

## 1.2 特色功能

| 功能     | 描述 |
|--------| --- |
| 统一异常处理 | GlobalExceptionHandler 全局异常处理，统一错误响应格式 |
| 国际化支持 | 基于Spring MessageSource的多语言支持，支持中文/英文切换 |
| 多级缓存 | 集成Spring Cache，支持Redis/Caffeine双重缓存策略 |
| 字典缓存 | 字典数据启动预热，支持缓存自动刷新和手动清理 |
| Excel导入导出 | 基于EasyExcel的数据导入导出，支持字典转换和国际化 |
| 数据验证 | JSR303验证 + 自定义验证器，支持Excel数据批量验证 |
| RESTful API | 符合REST规范的API设计，统一响应格式和错误处理 |
| 缓存预热 | 应用启动时自动预热关键缓存，提升系统响应性能 |
| 多租户支持 | SaaS场景下的租户隔离和数据权限控制 |
| 统一配置管理 | 基于Spring Boot配置体系的统一配置管理 |

# 二、项目架构

## 2.1 后端

### 2.1.1 项目结构

| 层次       | 包名          | 功能                        | 必选  |
| -------- | ------------ | ------------------------------- | --- |
| adapter层 | web         | 处理页面请求的Controller         | 否   |
| adapter层 | web         | 处理页面请求的Controller         | 否   |
| adapter层 | wap         | 处理wap端的适配                  | 否   |
| app层     | executor    | 处理request, 包括command和query  | 是   |
| app层     | consumer    | 消费者处理外部消息和事件          | 否   |
| app层     | scheduler   | 处理定时任务                     | 否   |
| client层  | api         | 服务对外透出的API                | 是   |
| client层  | dto         | 服务对外的DTO                    | 是   |
| domain层  | model       | 领域模型                         | 否   |
| domain层  | ability     | 领域能力, 包括DomainService      | 否   |
| domain层  | gateway     | 领域网关, 解耦利器                | 是   |
| infra层   | gatewayimpl | 网关实现                         | 是   |
| infra层   | mapper      | mybatis数据库映射                | 否   |
| infra层   | config      | 配置信息                         | 否   |

### 2.1.2 技术栈

**核心框架**
- 语言：Java JDK1.8
- Web服务框架：Spring Boot 2.7.18
- Cola DDD框架：4.3.2
- 数据库：MySQL 8.0+

**中间件**
- 缓存：Redis、Caffeine
- 配置中心：Apollo
- 消息队列：RabbitMQ（可选）

**功能组件**
- 数据访问：MyBatis Plus
- 缓存框架：Spring Cache
- 数据验证：Hibernate Validator (JSR303)
- Excel处理：EasyExcel
- 国际化：Spring MessageSource
- API文档：Swagger/OpenAPI 3
- JSON处理：FastJSON2
- 工具库：Hutool

# 三、特色功能详解

## 3.1 国际化支持

### 3.1.1 配置
```yaml
spring:
  messages:
    basename: i18n/messages
    encoding: UTF-8
```

### 3.1.2 使用方式
```java
// 获取当前语言的消息
String message = I18nUtil.getMessage("user.login.success");

// 带参数的消息
String message = I18nUtil.getMessage("excel.validation.required", new Object[]{"用户名"});

// 切换语言
PUT /system/i18n/language/zh-CN
PUT /system/i18n/language/en-US
```

## 3.2 缓存系统

### 3.2.1 字典缓存
```java
@Service
public class DictCacheService {
    // 获取字典列表（自动缓存）
    public List<DictData> getDictList(String dictType);
    
    // 字典值转标签
    public String toLabel(String dictType, String value);
}
```

### 3.2.2 缓存预热
```java
// 系统启动时自动预热
@Component
public class DictCachePreloader implements CachePreloader {
    @Override
    public void preload() {
        // 预热字典缓存
    }
}
```

## 3.3 Excel导入导出

### 3.3.1 注解配置
```java
public class UserExcelVO {
    @ExcelColumn(value = "用户名", i18nKey = "user.name", required = true)
    private String username;
    
    @ExcelColumn(value = "性别", dictType = "gender")
    private String gender;
    
    @ExcelColumn(value = "生日", dateFormat = "yyyy-MM-dd")
    private LocalDate birthday;
}
```

### 3.3.2 导入导出
```java
// 导入Excel
ExcelImportResult<UserExcelVO> result = excelImportUtil.readWithValidation(file, UserExcelVO.class);

// 导出Excel
excelExportUtil.export(response, "用户列表", UserExcelVO.class, dataList);
```

# 四、部署教程

# 五、开发手册

## 5.1 开发环境搭建



## 5.2 配置



## 5.3 定时任务配置


## 5.4 命名规范

### 5.4.1 方法名约定

| CRUD操作 | 方法名约定 |
| -------- | ---------- |
| 新增     | create*（Domain层、Infrastructure层）|
| 添加     | add*（App层）|
| 删除     | remove*（App和Domain层 |
| 删除     | delete*（Infrastructure层 |
| 修改     | update* |
| 查询（单个结果） | get* |
| 查询（多个结果） | list* |
| 分页查询 | page* |
| 查询树 | tree* |
| 统计     | count* |

### 5.4.2 类命名规范

| 规范 | 用途 | 解释 |
| ---- | ---- | ---- |
| BaseXx | Base Object | 基础对象，用于定义相同字段 |
| xxxCO | Client Object | 客户对象，用于传输数据，等同于DTO |
| xxxCmd | Client Request | Cmd代表Command，表示一个写请求 |
| xxxQuery | Client Request | Query，表示一个读请求 |
| xxxCmdExe | Command Executor | 命令模式，每一个写请求对应一个执行器 |
| xxxQueryExe | Query Executor | 命令模式，每一个读请求对应一个执行器 |
| xxxVO | Value Object | 值对象 |
| xxxEntity | Entity | 领域实体 |
| xxxDO | Data Object | 数据对象，用于持久化 |
| xxxInterceptor | Command Interceptor | 拦截器，用于处理切面逻辑 |
| IxxxService | API Service | xxxServiceI |
| xxxDomainService | Domain Service | 需要多个领域对象协作时，使用DomainService |
| xxxValidator | Validator | 校验器，用于校验的类 |
| xxxAssembler | Assembler | 组装器，DTO <---> Entity，用于Application层 |
| xxxConvertor | Convertor | 转化器，Entity <---> DO，用于Infrastructure层 |
| xxxStrategy | Strategy | 策略器，用于选择策略 |
| xxxHandler | Handler | 处理器，用于处理过程 |

## 5.4.3 代码提交规范

```bash
feat: 新功能
fix: 修复Bug
docs: 文档更新
style: 代码风格调整
refactor: 代码重构
perf: 性能优化
test: 测试代码
chore: 构建或工具变动
```

## 5.5 单元测试


# 六、注意事项