# JAVA_DDD_CLI

**Repository Path**: Xiao_agiao/java_-ddd_-cli

## Basic Information

- **Project Name**: JAVA_DDD_CLI
- **Description**: ddd架构脚手架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-19
- **Last Updated**: 2026-01-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JAVA_DDD_CLI

## 1. 项目愿景
构建一个基于领域驱动设计（DDD）思想的标准 Java 后端工程模板。
本项目旨在解决企业级开发中重复造轮子的痛点，通过预置统一的响应规范、异常体系、安全策略、日志追踪、对象映射以及生产级运维能力（监控、防 OOM、高并发处理），实现“下载即开发，开箱即上线”。

## 2. 技术栈选型

| 组件 | 版本/选型 | 核心用途 | 备注 |
| --- | --- | --- | --- |
| JDK | 1.8 (8) | 运行环境 | 经典稳定版本 |
| Framework | Spring Boot 2.7.x | 核心容器 | 2.x 系列的最终稳定版 |
| Build Tool | Maven | 依赖管理 | 多模块聚合 |
| Persistence | MyBatis-Plus 3.5.x | ORM 框架 | 集成自动填充、分页插件 |
| DB Pool | Alibaba Druid 1.2.x | 连接池 | 自带 SQL 监控与防火墙 |
| Security | Spring Security 5.7.x | 认证授权 | 配合 Boot 2.7，使用 SecurityFilterChain |
| Cache/Lock | Redisson 3.17.x | 分布式锁 | 替代 RedisTemplate 实现锁 |
| Utils | Hutool 5.8.x | 工具库 | 糊涂工具包（AES, Random, etc.） |
| Excel | EasyExcel 3.x | 报表处理 | 阿里开源，流式处理防 OOM |
| Mapping | MapStruct 1.5.x | 对象映射 | 编译期生成，替代 BeanUtils |
| Docs | Knife4j 4.x | API 文档 | 兼容 OpenAPI 3 和 Swagger 2 |
| Validation | Hibernate Validator | 参数校验 | 使用 javax.validation 包 |
| Logging | Logback | 日志系统 | 集成 MDC 全链路追踪 |
| JSON | Jackson | 序列化 | 全局时间/精度配置 |
| Database | MySQL 8.0 | 数据存储 |  |
| Migration | Flyway 7.x | DB 版本控制 | 可选但推荐集成 |

## 3. 模块架构设计
项目采用标准的 DDD 四层架构，父工程名为 `ygsuper`。

### 3.0 项目层级结构
```
.
├── .gitignore
├── README.md
└── ygsuper/
    ├── pom.xml
    ├── application/
    ├── common/
    ├── domain/
    ├── infrastructure/
    └── start/
```

### 3.1 模块依赖关系
待补充。

### 3.2 模块职责详解

#### 1) common（通用层）
定位：纯工具层，零业务逻辑，不依赖 Spring（尽量）。

核心组件：
- `Result<T>`：统一响应结构（`code`、`msg`、`data`、`requestId`）。
- `PageResult<T>`：分页响应结构（`total`、`pageNum`、`pageSize`、`list`）。
- `exception`：自定义异常（`BizException`, `AuthException`）和错误码枚举（`ErrorCode`）。
- `utils`：Hutool 封装（`AESUtils`, `IdGenerator`, `MD5Utils`）。
- `excel`：EasyExcel 封装（通用导入导出工具类，防 OOM）。
- `constant`：全局常量（`RegexConstants`, `CacheConstants`）。
- `validator`：自定义校验注解（`@Phone`, `@IdCard`）。

#### 2) domain（领域层）
定位：业务核心，纯净的 Java 对象，不依赖数据库实现。

核心组件：
- Entity：充血模型（包含核心业务逻辑，如 `Order.confirm()`）。
- ValueObject：值对象（如 `Address`, `Money`）。
- Repository Interface：仓储接口（`UserRepository`, `OrderRepository`）。
- Domain Service：跨实体的业务逻辑（`OrderService`）。
- Domain Event：领域事件（`OrderCreatedEvent`）。

#### 3) infrastructure（基础设施层）
定位：技术底座，为 Domain 提供支撑。

核心组件：
- Persistence：
  - MyBatis-Plus Mapper 接口。
  - DO/PO 对象（含 `@TableField(typeHandler = AESEncryptHandler.class)`）。
  - Repository Impl：实现 Domain 层定义的接口。
- Config：
  - MyBatis 配置（分页插件、自动填充）。
  - Druid 配置（`StatFilter` 慢 SQL 监控，`WallFilter` 防火墙）。
  - Redisson 配置（单机/哨兵/集群模式 Client Bean）。
  - Flyway 配置（数据库迁移）。
- Converter：MapStruct 转换器（`UserConverter`：Entity <-> PO）。
- Cache：缓存操作封装（`RedisCacheService`）。
- Lock：分布式锁实现（基于 Redisson 的 Lock 封装）。

#### 4) application（应用层）
定位：用例编排，对外暴露服务接口。

核心组件：
- DTO：
  - Command（CUD 操作，如 `UserCreateCmd`）。
  - Query（查询条件，如 `UserPageQuery`）。
  - Response（返回对象，如 `UserDetailResp`）。
- Service：应用服务（`UserApplicationService`），编排 Domain 逻辑，使用 Redisson 处理并发锁。
- Security：
  - `UserContext`（当前登录用户上下文）。
  - `PermissionChecker`（权限校验器）。
- Converter：MapStruct 转换器（`UserDTOConverter`：DTO <-> Entity）。

#### 5) start（启动/接入层）
定位：程序入口，HTTP 适配。

核心组件：
- Controller：REST 接口（遵循 RESTful 规范，如 `UserController`）。
- GlobalConfig：
  - Jackson 全局配置（时间格式、Long 转 String）。
  - Knife4j 增强配置（分组、认证）。
  - CORS 跨域配置。
  - AsyncConfig（全局线程池配置）。
  - Actuator 监控端点。
- Handler：全局异常处理（`GlobalExceptionHandler` 统一捕获异常）。
- Aspect/Filter：
  - `RequestIdFilter`：生成唯一请求 ID。
  - `WebLogAspect`：记录请求日志。
  - `RateLimitAspect`：基础限流。
- profile：多环境配置（`application-dev.yml`, `application-prod.yml`）。

## 4. 核心规范契约

### 4.1 时间契约
- 数据库：`datetime`
- Java：`LocalDateTime`（JDK 8 Time API）
- JSON（前端）：`yyyy-MM-dd HH:mm:ss`（Jackson 全局配置）

### 4.2 ID 契约
- 数据库：`bigint`（雪花算法，MyBatis-Plus `@TableId(type = IdType.ASSIGN_ID)`）
- Java：`Long`
- JSON（前端）：`String`（防止 JS 精度丢失，通过 Jackson MixIn 全局处理）

### 4.3 追踪契约
- 每个请求生成唯一 `request-id`（通过 Filter 生成，存入 MDC）。
- 日志格式：`[%X{requestId}] %d{yyyy-MM-dd HH:mm:ss.SSS} ...`
- 响应体：必须包含 `requestId` 字段。

### 4.4 安全契约
- 敏感字段加密：通过 MyBatis TypeHandler 实现自动加解密。
- 参数校验：Controller 层必须使用 `@Validated`（`javax.validation`）。

### 4.5 资源与并发契约
1) 线程使用契约：禁止手动 `new Thread()`，必须使用脚手架注入的线程池。
2) 分布式锁契约：禁止使用 RedisTemplate 手写 `setnx`，必须使用 Redisson。
3) 报表处理契约：禁止使用 Apache POI 处理大文件，必须使用 EasyExcel 防止 OOM。

## 5. 扩展性设计

### 5.1 多环境与监控
- Druid 监控：
  - 开发环境（dev）：开启 P6Spy 打印完整 SQL 参数。
  - 生产环境（prod）：开启 Druid 的 StatViewServlet，通过 `/druid/login.html` 查看 SQL 慢查询监控与连接池状态（需配置 IP 白名单）。
- 通过 Spring Profile 管理环境：`active: @profile.active@`。

### 5.2 缓存策略
- 二级缓存：Caffeine（本地）+ Redis（分布式）。
- 缓存注解：`@Cacheable`。

## 6. 最佳实践

### 6.1 测试策略

| 层级 | 测试类型 | 工具 | 覆盖率要求 |
| --- | --- | --- | --- |
| common | 单元测试 | JUnit 5 + AssertJ | ≥90% |
| domain | 单元测试 | JUnit 5 + Mockito | 100% 核心逻辑 |
| infrastructure | 集成测试 | Testcontainers + JUnit | 关键路径 100% |
| application | 服务测试 | SpringBootTest（Mock） | 核心用例 100% |

### 6.2 部署方案
- Dockerfile：基于 `openjdk:8u342-jdk-slim` 构建。
- 健康检查：Actuator `/actuator/health`。

### 6.3 代码规范
- 命名：DTO 后缀明确（`Cmd`, `Query`, `Resp`）。
- 分层：Infrastructure 层严禁出现 DTO，Controller 层严禁出现 Entity。

## 7. 初始化指南

### 7.1 快速启动
1. 克隆脚手架：`git clone https://github.com/your-repo/ygsuper.git`
2. 配置环境：修改 `application-dev.yml` 中的 Redis 地址和 MySQL 账号密码。
3. 启动应用：`mvn spring-boot:run -pl start -Dspring-boot.run.profiles=dev`
4. 验证监控：
   - 访问 `http://localhost:8080/druid/login.html` 验证数据库监控。
   - 访问 `http://localhost:8080/doc.html` 查看接口文档。

### 7.2 生成新模块
使用 Maven archetype 生成新业务模块：

1) `mvn archetype:generate -DgroupId=com.example -DartifactId=ygsuper-order ...`

### 7.3 集成 Checklist
- 在 `bootstrap.yml` 配置数据源与 Redis。
- 确认 Druid 监控页面可访问。
- 确认 Redisson 连接成功。
- 编写应用层用例服务。
- 配置 Knife4j 文档分组。
- 调整 ThreadPoolConfig 参数适配业务。