From 48cab32859dc26da804e76c1d87e1a2b411123fd Mon Sep 17 00:00:00 2001 From: dzq Date: Wed, 5 Nov 2025 11:07:24 +0800 Subject: [PATCH] =?UTF-8?q?docs(DDD-CQRS):=20=E7=AE=80=E5=8C=96=E7=9B=AE?= =?UTF-8?q?=E5=BD=95=E7=BB=93=E6=9E=84=E5=B9=B6=E6=9B=B4=E6=96=B0=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 重构文档中的目录结构描述，从多层嵌套改为单层子文件夹原则 新增架构原则与文件组织规范章节，明确目录职责和命名规范 更新核心组件详解中的文件路径说明以符合新规范 --- doc/DDD-CQRS开发指南-新增表完整实现.md | 100 ++++++++++++++++++------- 1 file changed, 74 insertions(+), 26 deletions(-) diff --git a/doc/DDD-CQRS开发指南-新增表完整实现.md b/doc/DDD-CQRS开发指南-新增表完整实现.md index 01ed311..c417b68 100644 --- a/doc/DDD-CQRS开发指南-新增表完整实现.md +++ b/doc/DDD-CQRS开发指南-新增表完整实现.md @@ -20,16 +20,11 @@ │ ├── Delete{Module}Command.java │ └── ... ├── db/ # 数据层 -│ ├── entity/ # 实体类 -│ │ └── {Module}Entity.java -│ ├── service/ # 服务层 -│ │ ├── {Module}Service.java -│ │ └── impl/ -│ │ └── {Module}ServiceImpl.java -│ ├── mapper/ # 数据访问 -│ │ └── {Module}Mapper.java -│ └── do/ # 数据对象（复杂查询） -│ └── Search{Module}DO.java +│ ├── {Module}Entity.java # 实体类 +│ ├── {Module}Service.java # 服务接口 +│ ├── {Module}ServiceImpl.java # 服务实现 +│ ├── {Module}Mapper.java # 数据访问 +│ └── Search{Module}DO.java # 数据对象（复杂查询） ├── dto/ # 数据传输对象 │ ├── {Module}DTO.java │ ├── {Module}DetailDTO.java @@ -44,11 +39,58 @@ --- +## 🏛️ 架构原则与文件组织规范 + +### 目录层级规范 + +**严格遵守单层子文件夹原则**： + +1. **每个模块下最多只能有一层子文件夹**，不允许出现多层嵌套的包结构 +2. **例外情况**： + - command 包：可以直接包含多个 Command 类文件，无需再分层 + - query 包：可以直接包含多个 Query 类文件，无需再分层 + - dto 包：可以直接包含多个 DTO 类文件，无需再分层 + - model 包：可以直接包含 Model 和 ModelFactory 类文件，无需再分层 + +3. **正确的组织方式**： + ``` + ✓ db/{Module}Entity.java + ✓ db/{Module}Service.java + ✓ db/{Module}ServiceImpl.java + ✓ db/{Module}Mapper.java + ✓ db/Search{Module}DO.java + + ✗ 错误：db/entity/{Module}Entity.java + ✗ 错误：db/service/{Module}Service.java + ✗ 错误：db/service/impl/{Module}ServiceImpl.java + ✗ 错误：db/mapper/{Module}Mapper.java + ✗ 错误：db/do/Search{Module}DO.java + ``` + +### 命名规范 + +- **包名**：全部使用小写字母，单词间用下划线分隔（如 `command`、`dto`、`model`） +- **文件命名**：采用 PascalCase 命名法，体现类的职责 +- **目录名**：采用小写字母，与包名保持一致 + +### 目录职责划分 + +| 目录 | 职责 | 文件类型 | +|------|------|----------| +| `command/` | 封装写操作请求参数 | Add/Update/Delete 命令对象 | +| `query/` | 封装读操作查询条件 | Search 查询对象 | +| `dto/` | 向前端传输数据 | DTO、详情DTO、配置文件DTO | +| `model/` | 领域模型和业务逻辑 | Model、ModelFactory | +| `db/` | 数据访问层 | Entity、Service、Mapper、DO | +| ApplicationService | 应用服务层 | 事务脚本、流程编排 | + +--- + ## 📝 核心组件详解 ### 1. Entity（实体类） -**位置**: `db/entity/{Module}Entity.java` +**位置**: `db/{Module}Entity.java` **职责**: 数据库表的 Java 映射，继承 `BaseEntity` 获得通用字段 @@ -138,7 +180,7 @@ public class ExampleUserEntity extends BaseEntity { ### 2. Service（服务层） -**位置**: `db/service/{Module}Service.java` 和 `impl/{Module}ServiceImpl.java` +**位置**: `db/{Module}Service.java` 和 `db/{Module}ServiceImpl.java` **职责**: 封装数据库操作和简单业务逻辑，继承 MyBatis-Plus 的 `IService` @@ -291,7 +333,7 @@ public class ExampleUserServiceImpl extends ServiceImpl { ### 4. DO（数据对象） -**位置**: `db/do/Search{Module}DO.java` +**位置**: `db/Search{Module}DO.java` **职责**: 复杂查询返回的数据对象，包含关联表字段 @@ -1234,50 +1276,50 @@ public UserDTO(ExampleUserEntity entity) { - [ ] 创建必要的索引 ### 2. Entity 层 -- [ ] 创建 `{Module}Entity.java`，继承 `BaseEntity` +- [ ] 在 `db/` 目录下创建 `{Module}Entity.java`，继承 `BaseEntity` - [ ] 配置 `@TableName`、`@TableId`、`@TableField` 注解 - [ ] 实现 `pkVal()` 方法 ### 3. Mapper 层 -- [ ] 创建 `{Module}Mapper.java`，继承 `BaseMapper` +- [ ] 在 `db/` 目录下创建 `{Module}Mapper.java`，继承 `BaseMapper` - [ ] 添加自定义查询方法（如需要） ### 4. Service 层 -- [ ] 创建 `{Module}Service.java` 接口 -- [ ] 创建 `{Module}ServiceImpl.java` 实现类 +- [ ] 在 `db/` 目录下创建 `{Module}Service.java` 接口 +- [ ] 在 `db/` 目录下创建 `{Module}ServiceImpl.java` 实现类 - [ ] 继承 `ServiceImpl` - [ ] 实现核心业务方法 ### 5. Command 层 -- [ ] 创建 `Add{Module}Command.java` -- [ ] 创建 `Update{Module}Command.java`（可选：继承基础 Command） -- [ ] 创建其他 Command（如 `Delete{Module}Command.java`） +- [ ] 在 `command/` 目录下创建 `Add{Module}Command.java` +- [ ] 在 `command/` 目录下创建 `Update{Module}Command.java`（可选：继承基础 Command） +- [ ] 在 `command/` 目录下创建其他 Command（如 `Delete{Module}Command.java`） ### 6. Query 层 -- [ ] 创建 `Search{Module}Query.java` +- [ ] 在 `query/` 目录下创建 `Search{Module}Query.java` - [ ] 继承 `AbstractPageQuery` - [ ] 实现 `addQueryCondition()` 方法 ### 7. DTO 层 -- [ ] 创建 `{Module}DTO.java` +- [ ] 在 `dto/` 目录下创建 `{Module}DTO.java` - [ ] 添加构造函数（从 Entity/DO 转换） - [ ] 添加 `@ExcelColumn` 注解（如果需要导出） - [ ] 集成缓存获取关联数据（如果需要） ### 8. Model 层 -- [ ] 创建 `{Module}Model.java`，继承 Entity +- [ ] 在 `model/` 目录下创建 `{Module}Model.java`，继承 Entity - [ ] 添加 `load*Command()` 方法 - [ ] 添加 `check*()` 业务校验方法 - [ ] 添加业务逻辑处理方法 ### 9. ModelFactory 层 -- [ ] 创建 `{Module}ModelFactory.java` +- [ ] 在 `model/` 目录下创建 `{Module}ModelFactory.java` - [ ] 使用 `@Component` 注解 - [ ] 添加 `loadById()` 方法 - [ ] 添加 `create()` 方法 ### 10. ApplicationService 层 -- [ ] 创建 `{Module}ApplicationService.java` +- [ ] 创建 `{Module}ApplicationService.java`（位于模块根目录） - [ ] 使用 `@Service` 注解 - [ ] 注入 Service 和 ModelFactory - [ ] 实现 CRUD 方法 @@ -1333,6 +1375,12 @@ AgileBoot 的 DDD/CQRS 架构通过清晰的分层和职责分离，为企业级 7. **ModelFactory**: 统一创建 Model 8. **ApplicationService**: 事务脚本层，协调各组件 +### 关键架构原则 + +- **单层子文件夹原则**：严格遵守每个模块下最多只能有一层子文件夹的规范，避免深层嵌套 +- **职责分离**：每个目录和文件都有明确的职责边界 +- **依赖倒置**：Domain 层不依赖 Infrastructure 层，通过 ApplicationService 协调 + 遵循本指南的规范，可以快速构建符合 DDD/CQRS 架构的高质量代码。 ---