1392 lines
38 KiB
Markdown
1392 lines
38 KiB
Markdown
# AgileBoot DDD/CQRS 开发指南 - 新增表完整实现
|
||
|
||
## 📖 文档概述
|
||
|
||
本文档详细说明了在 AgileBoot 框架中新增一张数据表后，如何按照 DDD/CQRS 架构规范写出完整的 `command`、`db`、`dto`、`model`、`query`、`ApplicationService` 等全套代码。
|
||
|
||
基于对 `agileboot-domain` 模块的深度分析，结合 `system/user`、`shop`、`cabinet` 等真实业务模块的代码实践，本指南提供了可直接使用的代码模板和最佳实践。
|
||
|
||
---
|
||
|
||
## 🏗️ 目录结构概览
|
||
|
||
新增一张表后，在 `agileboot-domain/src/main/java/com/agileboot/domain/{module}/` 目录下需要创建以下结构：
|
||
|
||
```
|
||
{module}/
|
||
├── command/ # 命令对象（写操作）
|
||
│ ├── Add{Module}Command.java
|
||
│ ├── Update{Module}Command.java
|
||
│ ├── Delete{Module}Command.java
|
||
│ └── ...
|
||
├── db/ # 数据层
|
||
│ ├── {Module}Entity.java # 实体类
|
||
│ ├── {Module}Service.java # 服务接口
|
||
│ ├── {Module}ServiceImpl.java # 服务实现
|
||
│ ├── {Module}Mapper.java # 数据访问
|
||
│ └── Search{Module}DO.java # 数据对象（复杂查询）
|
||
├── dto/ # 数据传输对象
|
||
│ ├── {Module}DTO.java
|
||
│ ├── {Module}DetailDTO.java
|
||
│ └── {Module}ProfileDTO.java
|
||
├── model/ # 领域模型
|
||
│ ├── {Module}Model.java
|
||
│ └── {Module}ModelFactory.java
|
||
├── query/ # 查询对象
|
||
│ └── Search{Module}Query.java
|
||
└── {Module}ApplicationService.java # 应用服务层
|
||
```
|
||
|
||
---
|
||
|
||
## 🏛️ 架构原则与文件组织规范
|
||
|
||
### 目录层级规范
|
||
|
||
**严格遵守单层子文件夹原则**：
|
||
|
||
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/{Module}Entity.java`
|
||
|
||
**职责**: 数据库表的 Java 映射，继承 `BaseEntity` 获得通用字段
|
||
|
||
**关键特性**:
|
||
- 继承 `BaseEntity<SELF>`
|
||
- 实现 `pkVal()` 返回主键
|
||
- 使用 MyBatis-Plus 注解：`@TableName`、`@TableId`、`@TableField`
|
||
- 所有字段使用包装类型（Long, Integer），避免空指针
|
||
|
||
#### 代码示例
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user.db;
|
||
|
||
import com.agileboot.common.core.base.BaseEntity;
|
||
import com.baomidou.mybatisplus.annotation.IdType;
|
||
import com.baomidou.mybatisplus.annotation.TableField;
|
||
import com.baomidou.mybatisplus.annotation.TableId;
|
||
import com.baomidou.mybatisplus.annotation.TableName;
|
||
import io.swagger.annotations.ApiModel;
|
||
import io.swagger.annotations.ApiModelProperty;
|
||
import java.io.Serializable;
|
||
import java.math.BigDecimal;
|
||
import java.util.Date;
|
||
import lombok.Data;
|
||
import lombok.EqualsAndHashCode;
|
||
|
||
/**
|
||
* 用户信息表
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
@Data
|
||
@EqualsAndHashCode(callSuper = true)
|
||
@TableName("example_user")
|
||
@ApiModel(value = "ExampleUserEntity对象", description = "用户信息表")
|
||
public class ExampleUserEntity extends BaseEntity<ExampleUserEntity> {
|
||
|
||
private static final long serialVersionUID = 1L;
|
||
|
||
@ApiModelProperty("用户ID")
|
||
@TableId(value = "user_id", type = IdType.AUTO)
|
||
private Long userId;
|
||
|
||
@ApiModelProperty("用户姓名")
|
||
@TableField("user_name")
|
||
private String userName;
|
||
|
||
@ApiModelProperty("年龄")
|
||
@TableField("age")
|
||
private Integer age;
|
||
|
||
@ApiModelProperty("邮箱")
|
||
@TableField("email")
|
||
private String email;
|
||
|
||
@ApiModelProperty("余额")
|
||
@TableField("balance")
|
||
private BigDecimal balance;
|
||
|
||
@ApiModelProperty("状态（1正常 2停用）")
|
||
@TableField("status")
|
||
private Integer status;
|
||
|
||
@ApiModelProperty("部门ID")
|
||
@TableField("dept_id")
|
||
private Long deptId;
|
||
|
||
@ApiModelProperty("备注")
|
||
@TableField("remark")
|
||
private String remark;
|
||
|
||
@Override
|
||
public Serializable pkVal() {
|
||
return this.userId;
|
||
}
|
||
}
|
||
```
|
||
|
||
**关键点**:
|
||
- 类名: `{Module}Entity`，表名使用下划线命名 `{module}_{name}`
|
||
- 主键字段: `{module}_id`，类型为 `Long`，注解 `@TableId(type = IdType.AUTO)`
|
||
- 继承 `BaseEntity` 获得: `creatorId`, `createTime`, `updaterId`, `updateTime`, `deleted`
|
||
|
||
---
|
||
|
||
### 2. Service（服务层）
|
||
|
||
**位置**: `db/{Module}Service.java` 和 `db/{Module}ServiceImpl.java`
|
||
|
||
**职责**: 封装数据库操作和简单业务逻辑，继承 MyBatis-Plus 的 `IService`
|
||
|
||
#### 接口定义
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user.db;
|
||
|
||
import com.agileboot.common.core.page.AbstractPageQuery;
|
||
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
|
||
import com.baomidou.mybatisplus.extension.service.IService;
|
||
|
||
/**
|
||
* 用户信息表 服务类
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
public interface ExampleUserService extends IService<ExampleUserEntity> {
|
||
|
||
/**
|
||
* 检测邮箱是否唯一
|
||
*
|
||
* @param email 邮箱
|
||
* @param userId 用户ID（更新时传入，排除自身）
|
||
* @return 是否唯一
|
||
*/
|
||
boolean isEmailUnique(String email, Long userId);
|
||
|
||
/**
|
||
* 检测用户名是否唯一
|
||
*
|
||
* @param userName 用户名
|
||
* @return 是否唯一
|
||
*/
|
||
boolean isUserNameUnique(String userName);
|
||
|
||
/**
|
||
* 获取用户的部门信息
|
||
*
|
||
* @param userId 用户ID
|
||
* @return 部门信息
|
||
*/
|
||
Long getDeptIdOfUser(Long userId);
|
||
|
||
/**
|
||
* 根据条件分页查询用户列表
|
||
*
|
||
* @param query 查询参数
|
||
* @return 用户信息集合
|
||
*/
|
||
Page<ExampleUserEntity> getUserList(AbstractPageQuery<ExampleUserEntity> query);
|
||
|
||
/**
|
||
* 根据条件分页查询用户列表（带额外字段）
|
||
*
|
||
* @param query 查询参数
|
||
* @return 用户信息集合（含关联字段）
|
||
*/
|
||
Page<SearchUserDO> getUserListWithJoin(AbstractPageQuery<SearchUserDO> query);
|
||
}
|
||
```
|
||
|
||
#### 实现类
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user.db.impl;
|
||
|
||
import cn.hutool.core.util.StrUtil;
|
||
import com.agileboot.common.core.page.AbstractPageQuery;
|
||
import com.agileboot.domain.example.user.db.ExampleUserEntity;
|
||
import com.agileboot.domain.example.user.db.SearchUserDO;
|
||
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
|
||
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
|
||
import java.util.Objects;
|
||
import lombok.RequiredArgsConstructor;
|
||
import org.springframework.stereotype.Service;
|
||
|
||
/**
|
||
* 用户信息表 服务实现类
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
@Service
|
||
@RequiredArgsConstructor
|
||
public class ExampleUserServiceImpl extends ServiceImpl<ExampleUserMapper, ExampleUserEntity> implements ExampleUserService {
|
||
|
||
@Override
|
||
public boolean isEmailUnique(String email, Long userId) {
|
||
if (StrUtil.isEmpty(email)) {
|
||
return true;
|
||
}
|
||
|
||
LambdaQueryWrapper<ExampleUserEntity> wrapper = new LambdaQueryWrapper<>();
|
||
|
||
wrapper.eq(ExampleUserEntity::getEmail, email)
|
||
.eq(ExampleUserEntity::getDeleted, 0);
|
||
|
||
// 如果是更新操作，排除自身
|
||
if (userId != null) {
|
||
wrapper.ne(ExampleUserEntity::getUserId, userId);
|
||
}
|
||
|
||
return !(this.count(wrapper) > 0);
|
||
}
|
||
|
||
@Override
|
||
public boolean isUserNameUnique(String userName) {
|
||
if (StrUtil.isEmpty(userName)) {
|
||
return true;
|
||
}
|
||
|
||
LambdaQueryWrapper<ExampleUserEntity> wrapper = new LambdaQueryWrapper<>();
|
||
|
||
wrapper.eq(ExampleUserEntity::getUserName, userName)
|
||
.eq(ExampleUserEntity::getDeleted, 0);
|
||
|
||
return !(this.count(wrapper) > 0);
|
||
}
|
||
|
||
@Override
|
||
public Long getDeptIdOfUser(Long userId) {
|
||
if (userId == null) {
|
||
return null;
|
||
}
|
||
|
||
ExampleUserEntity entity = this.getById(userId);
|
||
return entity != null ? entity.getDeptId() : null;
|
||
}
|
||
|
||
@Override
|
||
public Page<ExampleUserEntity> getUserList(AbstractPageQuery<ExampleUserEntity> query) {
|
||
return this.page(query.toPage(), query.addQueryCondition());
|
||
}
|
||
|
||
@Override
|
||
public Page<SearchUserDO> getUserListWithJoin(AbstractPageQuery<SearchUserDO> query) {
|
||
// 自定义 SQL 查询，返回关联数据
|
||
return this.getBaseMapper().selectUserListWithJoin(query.toPage(), query);
|
||
}
|
||
}
|
||
```
|
||
|
||
**关键点**:
|
||
- 接口继承 `IService<Entity>`
|
||
- 实现类继承 `ServiceImpl<Mapper, Entity>`
|
||
- 简单业务逻辑在 Service 中处理
|
||
- 复杂业务逻辑交给 Model 处理
|
||
|
||
---
|
||
|
||
### 3. Mapper（数据访问层）
|
||
|
||
**位置**: `db/{Module}Mapper.java`
|
||
|
||
**职责**: MyBatis 数据访问接口，通常使用 MyBatis-Plus 的 `BaseMapper`
|
||
|
||
#### 代码示例
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user.db;
|
||
|
||
import com.agileboot.common.core.page.AbstractPageQuery;
|
||
import com.agileboot.domain.example.user.db.SearchUserDO;
|
||
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
|
||
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
|
||
import org.apache.ibatis.annotations.Mapper;
|
||
import org.apache.ibatis.annotations.Param;
|
||
import org.apache.ibatis.annotations.Select;
|
||
|
||
/**
|
||
* 用户信息表 Mapper 接口
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
@Mapper
|
||
public interface ExampleUserMapper extends BaseMapper<ExampleUserEntity> {
|
||
|
||
/**
|
||
* 分页查询用户列表（带关联数据）
|
||
*
|
||
* @param page 分页参数
|
||
* @param query 查询条件
|
||
* @return 用户列表
|
||
*/
|
||
@Select({
|
||
"<script>",
|
||
"SELECT u.*, d.dept_name, r.role_name",
|
||
"FROM example_user u",
|
||
"LEFT JOIN sys_dept d ON u.dept_id = d.dept_id",
|
||
"LEFT JOIN sys_role r ON u.role_id = r.role_id",
|
||
"WHERE u.deleted = 0",
|
||
"<if test='query.userName != null and query.userName != \"\"'>",
|
||
" AND u.user_name LIKE CONCAT('%', #{query.userName}, '%')",
|
||
"</if>",
|
||
"<if test='query.email != null and query.email != \"\"'>",
|
||
" AND u.email LIKE CONCAT('%', #{query.email}, '%')",
|
||
"</if>",
|
||
"ORDER BY u.create_time DESC",
|
||
"</script>"
|
||
})
|
||
Page<SearchUserDO> selectUserListWithJoin(
|
||
Page<SearchUserDO> page,
|
||
@Param("query") AbstractPageQuery<SearchUserDO> query
|
||
);
|
||
}
|
||
```
|
||
|
||
**关键点**:
|
||
- 继承 `BaseMapper<Entity>`
|
||
- 复杂查询使用 `@Select` 注解或 XML 文件
|
||
- 使用 `#{}` 进行参数绑定，避免 SQL 注入
|
||
|
||
---
|
||
|
||
### 4. DO（数据对象）
|
||
|
||
**位置**: `db/Search{Module}DO.java`
|
||
|
||
**职责**: 复杂查询返回的数据对象，包含关联表字段
|
||
|
||
#### 代码示例
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user.db;
|
||
|
||
import com.baomidou.mybatisplus.annotation.TableField;
|
||
import java.math.BigDecimal;
|
||
import java.util.Date;
|
||
import lombok.Data;
|
||
|
||
/**
|
||
* 用户查询数据对象（包含关联字段）
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
@Data
|
||
public class SearchUserDO {
|
||
|
||
private Long userId;
|
||
|
||
private String userName;
|
||
|
||
private Integer age;
|
||
|
||
private String email;
|
||
|
||
private BigDecimal balance;
|
||
|
||
private Integer status;
|
||
|
||
private Long deptId;
|
||
|
||
@TableField("dept_name")
|
||
private String deptName;
|
||
|
||
@TableField("role_name")
|
||
private String roleName;
|
||
|
||
private Date createTime;
|
||
|
||
private Date updateTime;
|
||
|
||
private String remark;
|
||
}
|
||
```
|
||
|
||
**关键点**:
|
||
- 用于复杂查询，包含关联表字段
|
||
- 字段名使用数据库列名或 `as` 别名
|
||
- 不需要继承任何类
|
||
|
||
---
|
||
|
||
### 5. Command（命令对象）
|
||
|
||
**位置**: `command/Add{Module}Command.java`、`Update{Module}Command.java`
|
||
|
||
**职责**: 封装写操作的输入参数，用于接收前端传入的数据
|
||
|
||
#### 添加命令
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user.command;
|
||
|
||
import com.agileboot.common.annotation.ExcelColumn;
|
||
import lombok.Data;
|
||
|
||
/**
|
||
* 添加用户命令
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
@Data
|
||
public class AddUserCommand {
|
||
|
||
@ExcelColumn(name = "用户姓名")
|
||
private String userName;
|
||
|
||
@ExcelColumn(name = "年龄")
|
||
private Integer age;
|
||
|
||
@ExcelColumn(name = "邮箱")
|
||
private String email;
|
||
|
||
@ExcelColumn(name = "余额")
|
||
private String balance; // 使用 String 接收，前端传入
|
||
|
||
@ExcelColumn(name = "状态")
|
||
private Integer status;
|
||
|
||
@ExcelColumn(name = "部门ID")
|
||
private Long deptId;
|
||
|
||
@ExcelColumn(name = "备注")
|
||
private String remark;
|
||
}
|
||
```
|
||
|
||
#### 更新命令
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user.command;
|
||
|
||
import com.agileboot.common.annotation.ExcelColumn;
|
||
import lombok.Data;
|
||
|
||
/**
|
||
* 更新用户命令
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
@Data
|
||
public class UpdateUserCommand extends AddUserCommand {
|
||
|
||
@ExcelColumn(name = "用户ID")
|
||
private Long userId;
|
||
}
|
||
```
|
||
|
||
**关键点**:
|
||
- 纯 POJO 类，仅用于数据传输
|
||
- 使用 `@ExcelColumn` 注解支持 Excel 导入导出
|
||
- 命令对象通常继承或包含基础字段
|
||
- 字段名与前端保持一致
|
||
|
||
---
|
||
|
||
### 6. Query（查询对象）
|
||
|
||
**位置**: `query/Search{Module}Query.java`
|
||
|
||
**职责**: 封装查询条件和分页参数，构建 MyBatis 查询条件
|
||
|
||
#### 代码示例
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user.query;
|
||
|
||
import cn.hutool.core.util.StrUtil;
|
||
import com.agileboot.common.core.page.AbstractPageQuery;
|
||
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
|
||
import lombok.Data;
|
||
import lombok.EqualsAndHashCode;
|
||
|
||
/**
|
||
* 用户查询条件
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
@EqualsAndHashCode(callSuper = true)
|
||
@Data
|
||
public class SearchUserQuery<T> extends AbstractPageQuery<T> {
|
||
|
||
private Long userId;
|
||
|
||
private String userName;
|
||
|
||
private String email;
|
||
|
||
private Integer status;
|
||
|
||
private Long deptId;
|
||
|
||
private Integer minAge;
|
||
|
||
private Integer maxAge;
|
||
|
||
@Override
|
||
public QueryWrapper<T> addQueryCondition() {
|
||
QueryWrapper<T> queryWrapper = new QueryWrapper<>();
|
||
|
||
queryWrapper.like(StrUtil.isNotEmpty(userName), "user_name", userName)
|
||
.like(StrUtil.isNotEmpty(email), "email", email)
|
||
.eq(userId != null, "user_id", userId)
|
||
.eq(status != null, "status", status)
|
||
.eq(deptId != null, "dept_id", deptId)
|
||
.eq("deleted", 0)
|
||
.between(minAge != null && maxAge != null, "age", minAge, maxAge);
|
||
|
||
// 设置时间范围排序字段
|
||
this.timeRangeColumn = "create_time";
|
||
|
||
return queryWrapper;
|
||
}
|
||
}
|
||
```
|
||
|
||
**关键点**:
|
||
- 继承 `AbstractPageQuery<T>`
|
||
- 实现 `addQueryCondition()` 方法构建查询条件
|
||
- 使用链式调用构建查询条件
|
||
- 非空判断：`StrUtil.isNotEmpty()` 和 `!= null`
|
||
- 设置默认排序字段
|
||
|
||
---
|
||
|
||
### 7. DTO（数据传输对象）
|
||
|
||
**位置**: `dto/{Module}DTO.java`、`{Module}DetailDTO.java`、`{Module}ProfileDTO.java`
|
||
|
||
**职责**: 向前端传输数据，支持缓存集成和字段转换
|
||
|
||
#### 基础 DTO
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user.dto;
|
||
|
||
import cn.hutool.core.bean.BeanUtil;
|
||
import com.agileboot.common.annotation.ExcelColumn;
|
||
import com.agileboot.common.annotation.ExcelSheet;
|
||
import com.agileboot.domain.common.cache.CacheCenter;
|
||
import com.agileboot.domain.example.user.db.ExampleUserEntity;
|
||
import com.agileboot.domain.example.user.db.SearchUserDO;
|
||
import java.math.BigDecimal;
|
||
import java.util.Date;
|
||
import lombok.Data;
|
||
|
||
/**
|
||
* 用户DTO
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
@ExcelSheet(name = "用户列表")
|
||
@Data
|
||
public class UserDTO {
|
||
|
||
public UserDTO(ExampleUserEntity entity) {
|
||
if (entity != null) {
|
||
BeanUtil.copyProperties(entity, this);
|
||
|
||
// 从缓存中获取关联数据
|
||
if (entity.getDeptId() != null) {
|
||
// 示例：获取部门名称（如果缓存中有）
|
||
// this.deptName = CacheCenter.deptCache.get(entity.getDeptId() + "")...;
|
||
}
|
||
}
|
||
}
|
||
|
||
public UserDTO(SearchUserDO entity) {
|
||
if (entity != null) {
|
||
BeanUtil.copyProperties(entity, this);
|
||
}
|
||
}
|
||
|
||
@ExcelColumn(name = "用户ID")
|
||
private Long userId;
|
||
|
||
@ExcelColumn(name = "用户姓名")
|
||
private String userName;
|
||
|
||
@ExcelColumn(name = "年龄")
|
||
private Integer age;
|
||
|
||
@ExcelColumn(name = "邮箱")
|
||
private String email;
|
||
|
||
@ExcelColumn(name = "余额")
|
||
private BigDecimal balance;
|
||
|
||
@ExcelColumn(name = "状态")
|
||
private String status; // 可以转换为文字描述
|
||
|
||
@ExcelColumn(name = "部门ID")
|
||
private Long deptId;
|
||
|
||
@ExcelColumn(name = "部门名称")
|
||
private String deptName;
|
||
|
||
@ExcelColumn(name = "创建时间")
|
||
private Date createTime;
|
||
|
||
@ExcelColumn(name = "备注")
|
||
private String remark;
|
||
}
|
||
```
|
||
|
||
#### 详情 DTO（包含更多选项数据）
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user.dto;
|
||
|
||
import com.agileboot.domain.example.user.db.ExampleUserEntity;
|
||
import com.agileboot.domain.system.dept.dto.DeptDTO;
|
||
import com.agileboot.domain.system.role.dto.RoleDTO;
|
||
import java.util.List;
|
||
import lombok.Data;
|
||
|
||
/**
|
||
* 用户详情DTO（包含选项数据）
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
@Data
|
||
public class UserDetailDTO {
|
||
|
||
private UserDTO user;
|
||
|
||
private List<DeptDTO> deptOptions;
|
||
|
||
private List<RoleDTO> roleOptions;
|
||
}
|
||
```
|
||
|
||
**关键点**:
|
||
- 支持从 Entity 或 DO 转换
|
||
- 使用 `BeanUtil.copyProperties()` 进行属性复制
|
||
- 可以集成多级缓存获取关联数据
|
||
- 支持 Excel 导入导出（`@ExcelColumn`）
|
||
- 可包含选项数据（如部门列表、角色列表）
|
||
|
||
---
|
||
|
||
### 8. Model（领域模型）
|
||
|
||
**位置**: `model/{Module}Model.java`
|
||
|
||
**职责**: 领域模型，封装核心业务逻辑，包括校验、状态转换等
|
||
|
||
#### 代码示例
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user.model;
|
||
|
||
import cn.hutool.core.bean.BeanUtil;
|
||
import cn.hutool.core.util.StrUtil;
|
||
import com.agileboot.common.exception.ApiException;
|
||
import com.agileboot.common.exception.error.ErrorCode;
|
||
import com.agileboot.domain.example.user.command.AddUserCommand;
|
||
import com.agileboot.domain.example.user.command.UpdateUserCommand;
|
||
import com.agileboot.domain.example.user.db.ExampleUserEntity;
|
||
import com.agileboot.domain.example.user.db.ExampleUserService;
|
||
import java.math.BigDecimal;
|
||
import lombok.Data;
|
||
import lombok.EqualsAndHashCode;
|
||
import lombok.NoArgsConstructor;
|
||
|
||
/**
|
||
* 用户领域模型
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
@EqualsAndHashCode(callSuper = true)
|
||
@Data
|
||
@NoArgsConstructor
|
||
public class UserModel extends ExampleUserEntity {
|
||
|
||
private ExampleUserService userService;
|
||
|
||
public UserModel(ExampleUserEntity entity, ExampleUserService userService) {
|
||
if (entity != null) {
|
||
BeanUtil.copyProperties(entity, this);
|
||
}
|
||
this.userService = userService;
|
||
}
|
||
|
||
public UserModel(ExampleUserService userService) {
|
||
this.userService = userService;
|
||
}
|
||
|
||
/**
|
||
* 加载添加用户命令
|
||
*/
|
||
public void loadAddUserCommand(AddUserCommand command) {
|
||
if (command != null) {
|
||
BeanUtil.copyProperties(command, this, "userId");
|
||
|
||
// 转换余额字段
|
||
if (StrUtil.isNotEmpty(command.getBalance())) {
|
||
try {
|
||
this.setBalance(new BigDecimal(command.getBalance()));
|
||
} catch (NumberFormatException e) {
|
||
throw new ApiException(ErrorCode.Business.COMMON_BAD_REQUEST, "余额格式不正确");
|
||
}
|
||
}
|
||
|
||
// 设置默认值
|
||
if (this.getStatus() == null) {
|
||
this.setStatus(1); // 默认正常状态
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 加载更新用户命令
|
||
*/
|
||
public void loadUpdateUserCommand(UpdateUserCommand command) {
|
||
if (command != null) {
|
||
loadAddUserCommand(command);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 校验用户名唯一性
|
||
*/
|
||
public void checkUserNameIsUnique() {
|
||
if (!userService.isUserNameUnique(getUserName())) {
|
||
throw new ApiException(ErrorCode.Business.USER_NAME_IS_NOT_UNIQUE);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 校验邮箱唯一性
|
||
*/
|
||
public void checkEmailIsUnique() {
|
||
if (!userService.isEmailUnique(getEmail(), getUserId())) {
|
||
throw new ApiException(ErrorCode.Business.USER_EMAIL_IS_NOT_UNIQUE);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 校验关联数据是否存在
|
||
*/
|
||
public void checkFieldRelatedEntityExist() {
|
||
// 示例：校验部门是否存在
|
||
if (getDeptId() != null) {
|
||
// 可以通过其他 Service 校验部门是否存在
|
||
// Example: deptService.getById(getDeptId());
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 校验是否可以删除
|
||
*/
|
||
public void checkCanBeDelete() {
|
||
// 业务逻辑：例如检查用户是否有未完成的订单
|
||
// if (hasUnfinishedOrders()) {
|
||
// throw new ApiException(ErrorCode.Business.COMMON_BAD_REQUEST, "用户存在未完成的订单，无法删除");
|
||
// }
|
||
|
||
// 示例：检查是否为系统管理员
|
||
if (this.getIsAdmin() != null && this.getIsAdmin()) {
|
||
throw new ApiException(ErrorCode.Business.COMMON_BAD_REQUEST, "系统管理员不能删除");
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 设置密码（加密）
|
||
*/
|
||
public void setEncryptedPassword(String rawPassword) {
|
||
// 示例：加密密码
|
||
// this.setPassword(PasswordUtils.encrypt(rawPassword));
|
||
}
|
||
|
||
/**
|
||
* 校验年龄是否合法
|
||
*/
|
||
public void checkAgeIsValid() {
|
||
if (getAge() != null && (getAge() < 0 || getAge() > 150)) {
|
||
throw new ApiException(ErrorCode.Business.COMMON_BAD_REQUEST, "年龄必须在0-150之间");
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 预保存校验
|
||
*/
|
||
public void validateBeforeSave() {
|
||
if (StrUtil.isEmpty(getUserName())) {
|
||
throw new ApiException(ErrorCode.Business.COMMON_BAD_REQUEST, "用户名不能为空");
|
||
}
|
||
|
||
checkUserNameIsUnique();
|
||
checkEmailIsUnique();
|
||
checkFieldRelatedEntityExist();
|
||
checkAgeIsValid();
|
||
}
|
||
}
|
||
```
|
||
|
||
**关键点**:
|
||
- 继承实体类，获得所有字段
|
||
- 注入 Service 用于数据操作
|
||
- 包含 `load*Command()` 方法加载命令数据
|
||
- 包含 `check*()` 方法进行业务校验
|
||
- 包含业务逻辑处理方法
|
||
- 在 Model 中封装所有业务规则
|
||
|
||
---
|
||
|
||
### 9. ModelFactory（模型工厂）
|
||
|
||
**位置**: `model/{Module}ModelFactory.java`
|
||
|
||
**职责**: 统一创建 Model 实例，管理依赖注入和错误处理
|
||
|
||
#### 代码示例
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user.model;
|
||
|
||
import com.agileboot.common.exception.ApiException;
|
||
import com.agileboot.common.exception.error.ErrorCode;
|
||
import com.agileboot.domain.example.user.db.ExampleUserEntity;
|
||
import com.agileboot.domain.example.user.db.ExampleUserService;
|
||
import lombok.RequiredArgsConstructor;
|
||
import org.springframework.stereotype.Component;
|
||
|
||
/**
|
||
* 用户模型工厂
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
@Component
|
||
@RequiredArgsConstructor
|
||
public class UserModelFactory {
|
||
|
||
private final ExampleUserService userService;
|
||
|
||
/**
|
||
* 根据ID加载用户模型
|
||
*
|
||
* @param userId 用户ID
|
||
* @return 用户模型
|
||
*/
|
||
public UserModel loadById(Long userId) {
|
||
ExampleUserEntity entity = userService.getById(userId);
|
||
if (entity == null) {
|
||
throw new ApiException(ErrorCode.Business.COMMON_OBJECT_NOT_FOUND, userId, "用户");
|
||
}
|
||
return new UserModel(entity, userService);
|
||
}
|
||
|
||
/**
|
||
* 创建新用户模型
|
||
*
|
||
* @return 用户模型
|
||
*/
|
||
public UserModel create() {
|
||
return new UserModel(userService);
|
||
}
|
||
}
|
||
```
|
||
|
||
**关键点**:
|
||
- 使用 `@Component` 注解注入 Spring 容器
|
||
- 使用 `@RequiredArgsConstructor` 自动注入依赖
|
||
- `loadById()` 检查数据是否存在，不存在则抛异常
|
||
- `create()` 创建空模型，用于新增操作
|
||
|
||
---
|
||
|
||
### 10. ApplicationService（应用服务）
|
||
|
||
**位置**: `{Module}ApplicationService.java`
|
||
|
||
**职责**: 事务脚本层，协调 Model 和 Service，处理业务流程编排
|
||
|
||
#### 代码示例
|
||
|
||
```java
|
||
package com.agileboot.domain.example.user;
|
||
|
||
import com.agileboot.common.core.page.PageDTO;
|
||
import com.agileboot.domain.common.command.BulkOperationCommand;
|
||
import com.agileboot.domain.example.user.command.AddUserCommand;
|
||
import com.agileboot.domain.example.user.command.UpdateUserCommand;
|
||
import com.agileboot.domain.example.user.db.SearchUserDO;
|
||
import com.agileboot.domain.example.user.dto.UserDTO;
|
||
import com.agileboot.domain.example.user.dto.UserDetailDTO;
|
||
import com.agileboot.domain.example.user.model.UserModel;
|
||
import com.agileboot.domain.example.user.model.UserModelFactory;
|
||
import com.agileboot.domain.example.user.query.SearchUserQuery;
|
||
import com.agileboot.domain.system.dept.db.SysDeptService;
|
||
import com.agileboot.domain.system.dept.dto.DeptDTO;
|
||
import com.agileboot.domain.example.user.db.ExampleUserEntity;
|
||
import com.agileboot.domain.example.user.db.ExampleUserService;
|
||
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
|
||
import java.util.List;
|
||
import java.util.stream.Collectors;
|
||
import lombok.RequiredArgsConstructor;
|
||
import org.springframework.stereotype.Service;
|
||
import org.springframework.transaction.annotation.Transactional;
|
||
|
||
/**
|
||
* 用户应用服务
|
||
*
|
||
* @author your-name
|
||
* @since 2025-01-01
|
||
*/
|
||
@Service
|
||
@RequiredArgsConstructor
|
||
public class UserApplicationService {
|
||
|
||
private final ExampleUserService userService;
|
||
|
||
private final SysDeptService deptService;
|
||
|
||
private final UserModelFactory userModelFactory;
|
||
|
||
/**
|
||
* 获取用户列表（分页）
|
||
*/
|
||
public PageDTO<UserDTO> getUserList(SearchUserQuery<SearchUserDO> query) {
|
||
Page<SearchUserDO> userPage = userService.getUserListWithJoin(query);
|
||
List<UserDTO> userDTOList = userPage.getRecords()
|
||
.stream()
|
||
.map(UserDTO::new)
|
||
.collect(Collectors.toList());
|
||
return new PageDTO<>(userDTOList, userPage.getTotal());
|
||
}
|
||
|
||
/**
|
||
* 获取用户详情
|
||
*/
|
||
public UserDetailDTO getUserDetailInfo(Long userId) {
|
||
ExampleUserEntity userEntity = userService.getById(userId);
|
||
|
||
UserDetailDTO detailDTO = new UserDetailDTO();
|
||
detailDTO.setUser(new UserDTO(userEntity));
|
||
|
||
// 获取部门选项
|
||
List<DeptDTO> deptOptions = deptService.list()
|
||
.stream()
|
||
.map(DeptDTO::new)
|
||
.collect(Collectors.toList());
|
||
detailDTO.setDeptOptions(deptOptions);
|
||
|
||
return detailDTO;
|
||
}
|
||
|
||
/**
|
||
* 添加用户
|
||
*/
|
||
@Transactional(rollbackFor = Exception.class)
|
||
public void addUser(AddUserCommand command) {
|
||
UserModel model = userModelFactory.create();
|
||
model.loadAddUserCommand(command);
|
||
|
||
// 业务校验
|
||
model.validateBeforeSave();
|
||
|
||
// 保存
|
||
model.insert();
|
||
}
|
||
|
||
/**
|
||
* 更新用户
|
||
*/
|
||
@Transactional(rollbackFor = Exception.class)
|
||
public void updateUser(UpdateUserCommand command) {
|
||
UserModel model = userModelFactory.loadById(command.getUserId());
|
||
model.loadUpdateUserCommand(command);
|
||
|
||
// 业务校验
|
||
model.checkEmailIsUnique();
|
||
model.checkFieldRelatedEntityExist();
|
||
model.checkAgeIsValid();
|
||
|
||
// 更新
|
||
model.updateById();
|
||
}
|
||
|
||
/**
|
||
* 删除用户（单个）
|
||
*/
|
||
@Transactional(rollbackFor = Exception.class)
|
||
public void deleteUser(Long userId) {
|
||
UserModel model = userModelFactory.loadById(userId);
|
||
|
||
// 业务校验
|
||
model.checkCanBeDelete();
|
||
|
||
// 软删除
|
||
model.deleteById();
|
||
}
|
||
|
||
/**
|
||
* 批量删除用户
|
||
*/
|
||
@Transactional(rollbackFor = Exception.class)
|
||
public void deleteUsers(BulkOperationCommand<Long> command) {
|
||
for (Long userId : command.getIds()) {
|
||
UserModel model = userModelFactory.loadById(userId);
|
||
model.checkCanBeDelete();
|
||
model.deleteById();
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 更改用户状态
|
||
*/
|
||
@Transactional(rollbackFor = Exception.class)
|
||
public void changeUserStatus(Long userId, Integer status) {
|
||
UserModel model = userModelFactory.loadById(userId);
|
||
|
||
model.setStatus(status);
|
||
model.updateById();
|
||
}
|
||
|
||
/**
|
||
* 重置用户密码
|
||
*/
|
||
@Transactional(rollbackFor = Exception.class)
|
||
public void resetPassword(Long userId, String newPassword) {
|
||
UserModel model = userModelFactory.loadById(userId);
|
||
|
||
model.setEncryptedPassword(newPassword);
|
||
model.updateById();
|
||
}
|
||
}
|
||
```
|
||
|
||
**关键点**:
|
||
- 使用 `@Service` 注解
|
||
- 使用 `@RequiredArgsConstructor` 注入依赖
|
||
- 写操作使用 `@Transactional` 注解保证事务
|
||
- 协调 Model 和 Service
|
||
- 返回 DTO 给 Controller
|
||
- 包含完整的 CRUD 操作
|
||
|
||
---
|
||
|
||
## 🔄 CQRS 流程
|
||
|
||
### Command（写操作）流程
|
||
|
||
```
|
||
Controller → Command → ApplicationService → Model → 业务校验 → 保存
|
||
```
|
||
|
||
**示例**：
|
||
```java
|
||
// 1. Controller 接收参数，封装为 Command
|
||
AddUserCommand command = new AddUserCommand();
|
||
// ... 设置参数
|
||
|
||
// 2. ApplicationService 处理
|
||
userApplicationService.addUser(command);
|
||
|
||
// 3. ApplicationService 创建 Model 并加载 Command
|
||
UserModel model = userModelFactory.create();
|
||
model.loadAddUserCommand(command);
|
||
|
||
// 4. Model 进行业务校验
|
||
model.validateBeforeSave();
|
||
|
||
// 5. Model 执行保存操作
|
||
model.insert();
|
||
```
|
||
|
||
### Query（读操作）流程
|
||
|
||
```
|
||
Controller → Query → Service → Mapper → DTO
|
||
```
|
||
|
||
**示例**：
|
||
```java
|
||
// 1. Controller 接收查询参数，封装为 Query
|
||
SearchUserQuery<SearchUserDO> query = new SearchUserQuery<>();
|
||
// ... 设置查询条件
|
||
|
||
// 2. ApplicationService 处理
|
||
PageDTO<UserDTO> result = userApplicationService.getUserList(query);
|
||
|
||
// 3. Service 执行查询
|
||
Page<SearchUserDO> userPage = userService.getUserListWithJoin(query);
|
||
|
||
// 4. 转换为 DTO
|
||
List<UserDTO> userDTOList = userPage.getRecords()
|
||
.stream()
|
||
.map(UserDTO::new)
|
||
.collect(Collectors.toList());
|
||
|
||
return new PageDTO<>(userDTOList, userPage.getTotal());
|
||
```
|
||
|
||
---
|
||
|
||
## 📌 最佳实践
|
||
|
||
### 1. 命名规范
|
||
|
||
| 类型 | 命名规则 | 示例 |
|
||
|------|----------|------|
|
||
| Entity | `{Module}Entity` | `SysUserEntity` |
|
||
| Service 接口 | `{Module}Service` | `SysUserService` |
|
||
| Service 实现 | `{Module}ServiceImpl` | `SysUserServiceImpl` |
|
||
| Mapper | `{Module}Mapper` | `SysUserMapper` |
|
||
| Model | `{Module}Model` | `UserModel` |
|
||
| ModelFactory | `{Module}ModelFactory` | `UserModelFactory` |
|
||
| Command | `{Operation}{Module}Command` | `AddUserCommand` |
|
||
| Query | `Search{Module}Query` | `SearchUserQuery` |
|
||
| DTO | `{Module}DTO` | `UserDTO` |
|
||
| ApplicationService | `{Module}ApplicationService` | `UserApplicationService` |
|
||
|
||
### 2. 字段命名规范
|
||
|
||
- **Entity**: 使用下划线命名，与数据库保持一致
|
||
- `user_id`, `user_name`, `create_time`
|
||
- **Command/Query/DTO**: 使用驼峰命名，与前端保持一致
|
||
- `userId`, `userName`, `createTime`
|
||
|
||
### 3. 类型选择
|
||
|
||
- **主键**: 使用 `Long`（包装类型）
|
||
- **状态/数量**: 使用 `Integer`（包装类型）
|
||
- **金额**: 使用 `BigDecimal`（避免精度问题）
|
||
- **字符串**: 避免基本类型，使用 `String`
|
||
- **时间**: 使用 `Date` 或 `LocalDateTime`
|
||
|
||
### 4. 空值处理
|
||
|
||
- 始终使用包装类型，避免 NPE
|
||
- 使用 `StrUtil.isNotEmpty()` 判断字符串
|
||
- 使用 `!= null` 判断对象和数字
|
||
- 使用 MyBatis-Plus 的链式调用：`eq(condition, "column", value)`
|
||
|
||
### 5. 业务校验位置
|
||
|
||
- **唯一性校验**: Model 层
|
||
- **关联数据存在性校验**: Model 层
|
||
- **字段格式校验**: Model 层
|
||
- **业务规则校验**: Model 层
|
||
- **数据库约束**: Entity 层
|
||
|
||
### 6. 缓存集成
|
||
|
||
DTO 中可以从缓存获取关联数据：
|
||
```java
|
||
public UserDTO(ExampleUserEntity entity) {
|
||
if (entity != null) {
|
||
BeanUtil.copyProperties(entity, this);
|
||
|
||
// 从缓存获取部门名称
|
||
if (entity.getDeptId() != null) {
|
||
SysDeptEntity dept = CacheCenter.deptCache.get(entity.getDeptId() + "");
|
||
this.deptName = dept != null ? dept.getDeptName() : "";
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7. 事务管理
|
||
|
||
- ApplicationService 负责事务管理
|
||
- 使用 `@Transactional(rollbackFor = Exception.class)`
|
||
- 写操作必须开启事务
|
||
- 读操作可以不加事务（但建议加 `@Transactional(readOnly = true)`）
|
||
|
||
### 8. 异常处理
|
||
|
||
- 业务异常使用 `ApiException`
|
||
- 错误码使用 `ErrorCode` 枚举
|
||
- Model 层抛出异常，ApplicationService 不捕获
|
||
- Controller 层统一处理异常
|
||
|
||
### 9. 代码复用
|
||
|
||
- 公共方法抽取到工具类
|
||
- 通用 DTO/Entity 放在 `common` 模块
|
||
- 公共 Service 方法抽取到基类
|
||
- 使用组合而非继承
|
||
|
||
---
|
||
|
||
## 🛠️ 开发步骤清单
|
||
|
||
新增一张表后的完整开发流程：
|
||
|
||
### 1. 数据库层面
|
||
- [ ] 创建数据库表（`sql/YYYYMMDD_feature_name.sql`）
|
||
- [ ] 添加表注释和字段注释
|
||
- [ ] 创建必要的索引
|
||
|
||
### 2. Entity 层
|
||
- [ ] 在 `db/` 目录下创建 `{Module}Entity.java`，继承 `BaseEntity`
|
||
- [ ] 配置 `@TableName`、`@TableId`、`@TableField` 注解
|
||
- [ ] 实现 `pkVal()` 方法
|
||
|
||
### 3. Mapper 层
|
||
- [ ] 在 `db/` 目录下创建 `{Module}Mapper.java`，继承 `BaseMapper<Entity>`
|
||
- [ ] 添加自定义查询方法（如需要）
|
||
|
||
### 4. Service 层
|
||
- [ ] 在 `db/` 目录下创建 `{Module}Service.java` 接口
|
||
- [ ] 在 `db/` 目录下创建 `{Module}ServiceImpl.java` 实现类
|
||
- [ ] 继承 `ServiceImpl<Mapper, Entity>`
|
||
- [ ] 实现核心业务方法
|
||
|
||
### 5. Command 层
|
||
- [ ] 在 `command/` 目录下创建 `Add{Module}Command.java`
|
||
- [ ] 在 `command/` 目录下创建 `Update{Module}Command.java`（可选：继承基础 Command）
|
||
- [ ] 在 `command/` 目录下创建其他 Command（如 `Delete{Module}Command.java`）
|
||
|
||
### 6. Query 层
|
||
- [ ] 在 `query/` 目录下创建 `Search{Module}Query.java`
|
||
- [ ] 继承 `AbstractPageQuery<T>`
|
||
- [ ] 实现 `addQueryCondition()` 方法
|
||
|
||
### 7. DTO 层
|
||
- [ ] 在 `dto/` 目录下创建 `{Module}DTO.java`
|
||
- [ ] 添加构造函数（从 Entity/DO 转换）
|
||
- [ ] 添加 `@ExcelColumn` 注解（如果需要导出）
|
||
- [ ] 集成缓存获取关联数据（如果需要）
|
||
|
||
### 8. Model 层
|
||
- [ ] 在 `model/` 目录下创建 `{Module}Model.java`，继承 Entity
|
||
- [ ] 添加 `load*Command()` 方法
|
||
- [ ] 添加 `check*()` 业务校验方法
|
||
- [ ] 添加业务逻辑处理方法
|
||
|
||
### 9. ModelFactory 层
|
||
- [ ] 在 `model/` 目录下创建 `{Module}ModelFactory.java`
|
||
- [ ] 使用 `@Component` 注解
|
||
- [ ] 添加 `loadById()` 方法
|
||
- [ ] 添加 `create()` 方法
|
||
|
||
### 10. ApplicationService 层
|
||
- [ ] 创建 `{Module}ApplicationService.java`（位于模块根目录）
|
||
- [ ] 使用 `@Service` 注解
|
||
- [ ] 注入 Service 和 ModelFactory
|
||
- [ ] 实现 CRUD 方法
|
||
- [ ] 添加 `@Transactional` 注解
|
||
|
||
### 11. Controller 层（在 agileboot-admin 中）
|
||
- [ ] 创建 Controller
|
||
- [ ] 注入 ApplicationService
|
||
- [ ] 定义 RESTful API
|
||
- [ ] 添加 `@Operation` 注解
|
||
|
||
### 12. 测试
|
||
- [ ] 编写单元测试（Service、Model）
|
||
- [ ] 编写集成测试
|
||
- [ ] 测试 CRUD 操作
|
||
- [ ] 测试业务校验
|
||
- [ ] 测试缓存（如果使用）
|
||
|
||
### 13. 文档
|
||
- [ ] 更新 API 文档
|
||
- [ ] 补充业务说明
|
||
- [ ] 更新数据库文档
|
||
|
||
---
|
||
|
||
## 📚 参考资料
|
||
|
||
### 代码结构参考
|
||
- **System 用户管理**: `agileboot-domain/src/main/java/com/agileboot/domain/system/user/`
|
||
- **Shop 电商模块**: `agileboot-domain/src/main/java/com/agileboot/domain/shop/`
|
||
- **Cabinet 智能柜**: `agileboot-domain/src/main/java/com/agileboot/domain/cabinet/`
|
||
|
||
### 核心类参考
|
||
- **BaseEntity**: `com.agileboot.common.core.base.BaseEntity`
|
||
- **AbstractPageQuery**: `com.agileboot.common.core.page.AbstractPageQuery`
|
||
- **PageDTO**: `com.agileboot.common.core.page.PageDTO`
|
||
- **ApiException**: `com.agileboot.common.exception.ApiException`
|
||
- **ErrorCode**: `com.agileboot.common.exception.error.ErrorCode`
|
||
- **CacheCenter**: `com.agileboot.domain.common.cache.CacheCenter`
|
||
|
||
---
|
||
|
||
## 🎯 总结
|
||
|
||
AgileBoot 的 DDD/CQRS 架构通过清晰的分层和职责分离，为企业级应用开发提供了强有力的支撑：
|
||
|
||
1. **Entity**: 数据库映射，继承 BaseEntity
|
||
2. **Service**: 数据库操作和简单业务逻辑
|
||
3. **Command**: 写操作参数封装
|
||
4. **Query**: 读操作查询条件
|
||
5. **DTO**: 前端数据传输，支持缓存
|
||
6. **Model**: 领域模型，封装核心业务逻辑
|
||
7. **ModelFactory**: 统一创建 Model
|
||
8. **ApplicationService**: 事务脚本层，协调各组件
|
||
|
||
### 关键架构原则
|
||
|
||
- **单层子文件夹原则**：严格遵守每个模块下最多只能有一层子文件夹的规范，避免深层嵌套
|
||
- **职责分离**：每个目录和文件都有明确的职责边界
|
||
- **依赖倒置**：Domain 层不依赖 Infrastructure 层，通过 ApplicationService 协调
|
||
|
||
遵循本指南的规范，可以快速构建符合 DDD/CQRS 架构的高质量代码。
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0
|
||
**最后更新**: 2025-01-01
|
||
**作者**: AgileBoot Team
|