287 lines
14 KiB
Markdown
287 lines
14 KiB
Markdown
---
|
||
trigger: always_on
|
||
---
|
||
|
||
## XTools App Java后端规范
|
||
|
||
### 0. 概述
|
||
生成的代码仅需要关注api、biz、client三个模块。
|
||
|
||
### 1. 整体架构规范
|
||
- **JDK**: 25
|
||
- **技术栈**：Spring Boot 4.x + Spring Cloud 2025.x + MyBatis Plus + Nacos + Spring Cloud LoadBalancer + MapStruct
|
||
- **父POM**：`org.xujun:xtools-parent-cloud:5.0.0`
|
||
- **模块结构**：多模块Maven项目，支持微服务和单体部署
|
||
- **包结构**：统一以`xtools.app`开头，按模块分层组织
|
||
|
||
#### 1.1 项目模块划分
|
||
```
|
||
xtools-app/
|
||
├── xtools-app-common/ # 公共模块
|
||
│ ├── xtools-app-common-cache/ # 缓存(Redis)
|
||
│ ├── xtools-app-common-call/ # 远程调用
|
||
│ ├── xtools-app-common-config/ # 配置模块
|
||
│ ├── xtools-app-common-jar/ # JAR管理
|
||
│ ├── xtools-app-common-job/ # 定时任务(XXL-JOB)
|
||
│ ├── xtools-app-common-log/ # 日志模块
|
||
│ │ ├── xtools-app-common-log-bus/ # 日志总线
|
||
│ │ └── xtools-app-common-log-filter/ # 日志过滤器
|
||
│ ├── xtools-app-common-mq/ # 消息队列(RabbitMQ)
|
||
│ ├── xtools-app-common-sentinel/ # 限流(Sentinel)
|
||
│ └── xtools-app-common-task/ # 异步任务
|
||
├── xtools-app-monitor/ # 监控模块
|
||
│ ├── xtools-app-monitor-boot/ # 监控服务端
|
||
│ ├── xtools-app-monitor-client/ # 监控客户端
|
||
│ └── xtools-app-monitor-health/ # 健康检查
|
||
├── xtools-app-standalone/ # 单体部署启动模块
|
||
├── xtools-app-sys/ # 系统管理模块
|
||
│ ├── xtools-app-sys-api/ # API接口定义
|
||
│ ├── xtools-app-sys-auth/ # 认证授权(SM2/SM3加密)
|
||
│ ├── xtools-app-sys-biz/ # 业务逻辑实现
|
||
│ ├── xtools-app-sys-boot/ # 微服务启动
|
||
│ ├── xtools-app-sys-call/ # 远程调用
|
||
│ ├── xtools-app-sys-file/ # 文件管理
|
||
│ ├── xtools-app-sys-file-web/ # 文件Web服务
|
||
│ ├── xtools-app-sys-log-bus-elasticsearch/ # 日志ES存储
|
||
│ ├── xtools-app-sys-param/ # 系统参数
|
||
│ ├── xtools-app-sys-risk/ # 风控管理
|
||
│ └── xtools-app-sys-scheduled/ # 定时任务
|
||
├── xtools-app-gen/ # 代码生成模块
|
||
│ ├── xtools-app-gen-biz/ # 代码生成业务
|
||
│ └── xtools-app-gen-boot/ # 代码生成启动
|
||
└── pom.xml # 父POM
|
||
```
|
||
|
||
#### 1.2 biz模块内部结构
|
||
```
|
||
xtools-app-{module}-biz/
|
||
├── src/main/java/xtools/app/{module}/
|
||
│ ├── api/ # API接口实现
|
||
│ ├── auth/ # 认证授权
|
||
│ ├── config/ # 配置类
|
||
│ ├── consts/ # 常量定义
|
||
│ ├── controller/ # 控制器层
|
||
│ ├── convert/ # 对象转换器(MapStruct)
|
||
│ ├── es/ # Elasticsearch相关
|
||
│ ├── job/ # 定时任务
|
||
│ ├── mapper/ # MyBatis Mapper接口
|
||
│ ├── model/ # 模型对象
|
||
│ │ ├── entity/ # 实体类
|
||
│ │ └── dto/ # 数据传输对象
|
||
│ │ ├── req/ # 请求对象(AddReq, UpdateReq, PageReq)
|
||
│ │ ├── resp/ # 响应对象(Resp)
|
||
│ │ └── excel/ # Excel对象
|
||
│ ├── mq/ # 消息队列处理
|
||
│ ├── service/ # 服务接口及实现
|
||
│ │ ├── base/ # BaseService(继承ServiceImpl)
|
||
│ │ └── impl/ # ServiceImpl
|
||
│ └── utils/ # 工具类
|
||
├── src/main/resources/
|
||
│ └── mapper/ # MyBatis XML映射文件
|
||
└── ...
|
||
```
|
||
|
||
### 2. 命名规范体系
|
||
|
||
#### 2.1 包命名规范
|
||
- 所有包名统一以`xtools.app`开头
|
||
- 模块包名格式：`xtools.app.{module}`
|
||
- 分层包名格式：`xtools.app.{module}.{layer}`
|
||
- 模型子包格式：`xtools.app.{module}.model.{sub}`
|
||
|
||
#### 2.2 类命名规范
|
||
- 实体类：使用业务名词，如`SysUser`
|
||
- DTO类：以`Dto`结尾，如`SysBlacklistDto`
|
||
- 添加请求类：以`AddReq`结尾，如`SysUserAddReq`
|
||
- 更新请求类：以`UpdateReq`结尾，如`SysUserUpdateReq`
|
||
- 分页请求类：以`PageReq`结尾，如`SysUserPageReq`
|
||
- 响应类：以`Resp`结尾，如`SysUserResp`
|
||
- Excel导入导出类：以`Excel`结尾
|
||
- BaseService接口：以`BaseService`结尾，如`SysUserBaseService`
|
||
- Service接口：以`Service`结尾，如`SysUserService`
|
||
- Service实现类：以`ServiceImpl`结尾，如`SysUserServiceImpl`
|
||
- Controller类：以`Controller`结尾，如`SysUserController`
|
||
- Mapper接口：以`Mapper`结尾，如`SysUserMapper`
|
||
- 转换器接口：以`Convert`结尾，如`SysUserConvert`
|
||
|
||
#### 2.3 方法命名规范
|
||
- 分页查询：`page(PageReq<XxxPageReq> pageReq)`
|
||
- 单条查询：`getById(Long id)`
|
||
- 添加：`add(XxxAddReq req)`
|
||
- 更新：`update(XxxUpdateReq req)`
|
||
- 删除：`delById(List<Long> idList)`
|
||
- 批量查询：`getListByIds(IdListReq req)`
|
||
- 转换方法：`addReqToEntity()`、`updateReqToEntity()`、`entityToResp()`、`entityToRespList()`
|
||
|
||
### 3. 编码实现规范
|
||
|
||
#### 3.1 注解使用规范
|
||
- 控制器类使用`@RestController`注解
|
||
- 服务实现类使用`@Service`注解；实现API接口时需添加`@Primary`注解
|
||
- BaseService类使用`@Component`注解
|
||
- Mapper接口使用`@Mapper`注解
|
||
- 转换器接口使用`@Mapper(componentModel = "spring")`注解（MapStruct）
|
||
- 控制器类添加`@Tag(name = "...")`注解（OpenAPI 3.0文档）
|
||
- 控制器方法添加`@Operation(summary = "...")`注解
|
||
- DTO字段添加`@Schema(description = "...", example = "...")`注解
|
||
- 依赖注入统一使用`@RequiredArgsConstructor`构造器注入，不使用字段注入
|
||
- 写操作方法添加`@Transactional(rollbackFor = Exception.class)`注解
|
||
|
||
#### 3.2 继承关系规范
|
||
- BaseService类继承`ServiceImpl<Mapper, Entity>`（MyBatis Plus），使用`@Component`注解
|
||
- ServiceImpl类实现Service接口，注入BaseService和Convert进行业务操作；实现API接口时需添加`@Primary`注解
|
||
- Controller类通过构造器注入Service接口
|
||
- API接口定义为Java interface，方法返回`Result<T>`
|
||
- 实体类继承`BaseEntity`（来自`xtools.boot.api.model.entity.BaseEntity`）
|
||
- 响应类继承`BaseEntity`（来自`xtools.boot.api.model.entity.BaseEntity`）
|
||
|
||
#### 3.3 返回值规范
|
||
- 所有对外接口统一返回`Result<T>`封装对象
|
||
- 分页查询返回`Result<PageResp<T>>`封装对象
|
||
- 分页请求参数使用`PageReq<XxxPageReq>`封装
|
||
- 删除请求使用`IdListReq`封装ID集合
|
||
- 成功时使用`Result.ok(data)`方法封装数据
|
||
- 失败时抛出`BizError`（业务错误）或`BizWarning`（业务警告）
|
||
- 请求参数错误返回`Result.badRequest()`
|
||
|
||
#### 3.4 DTO使用规范
|
||
- API请求参数使用DTO对象封装，实现`Serializable`接口
|
||
- 添加请求对象：`XxxAddReq`，包含业务字段（不包含ID）
|
||
- 更新请求对象：`XxxUpdateReq`，包含ID和业务字段
|
||
- 分页请求对象：`XxxPageReq`，包含查询条件和时间范围字段`gmtCreateRange`/`gmtModifiedRange`（`Instant[]`类型）
|
||
- 响应对象：`XxxResp`，继承`BaseEntity`，包含关联信息
|
||
- 敏感字段使用`@Mask`注解脱敏（如手机号、邮箱、密码）
|
||
- 实体类与DTO之间通过MapStruct转换器进行转换
|
||
- 不同业务场景使用不同的DTO对象，避免复用
|
||
|
||
### 4. 数据访问规范
|
||
|
||
#### 4.1 表名规范
|
||
- 表名全部小写，单词间用下划线分隔，如`sys_user`
|
||
- 表名前缀与模块对应，如`sys_`前缀对应sys模块
|
||
|
||
#### 4.2 字段名规范
|
||
- 字段名全部小写，单词间用下划线分隔，如`dept_id`
|
||
- 主键字段统一命名为`id`，类型为`Long`
|
||
- 创建时间字段为`gmt_create`（由BaseEntity提供）
|
||
- 更新时间字段为`gmt_modified`（由BaseEntity提供）
|
||
- 创建人字段为`create_by`
|
||
- 更新人字段为`update_by`
|
||
|
||
#### 4.3 实体类规范
|
||
- 实体类继承`BaseEntity`基类
|
||
- 使用Lombok注解：`@Data`、`@NoArgsConstructor`、`@AllArgsConstructor`、`@EqualsAndHashCode(callSuper = true)`
|
||
- 使用MyBatis Plus注解标注表名和字段：
|
||
- `@TableName("表名")`标注表名
|
||
- `@TableId(value = "id", type = IdType.ASSIGN_ID)`标注主键
|
||
- `@TableField(value = "字段名")`标注字段映射
|
||
- 字段添加`@Schema(description = "...")`注解描述
|
||
- 主键策略统一使用`IdType.ASSIGN_ID`
|
||
|
||
#### 4.4 Mapper规范
|
||
- Mapper接口按需继承`BaseMapper<Entity>`（MyBatis Plus），并非所有Mapper都需要继承
|
||
- 使用`@Mapper`注解
|
||
- 复杂查询使用MyBatis XML映射文件，放置在`resources/mapper/`目录下
|
||
- XML中使用`LambdaQueryWrapper`或动态SQL（`<where>`、`<if>`、`<foreach>`）
|
||
- 使用`QueryUtils.getPage()`和`QueryUtils.addTimeRange()`工具方法处理分页和时间范围
|
||
|
||
#### 4.5 BaseService规范
|
||
- BaseService类继承`ServiceImpl<Mapper, Entity>`
|
||
- 使用`@Component`注解
|
||
- 用于封装通用数据访问方法和复杂查询逻辑
|
||
- 命名格式：`{业务名}BaseService`，如`SysUserBaseService`
|
||
|
||
### 5. 接口设计规范
|
||
|
||
#### 5.1 Controller规范
|
||
- 使用`@RestController`和`@RequestMapping("/模块/资源")`注解
|
||
- 使用`@Tag(name = "...")`描述模块功能
|
||
- 使用`@Operation(summary = "...")`描述每个接口
|
||
- 方法命名遵循RESTful风格：`page`、`getById`、`add`、`update`、`delById`
|
||
- 分页接口：`@PostMapping("page")` + `@RequestBody @Valid PageReq<XxxPageReq>`
|
||
- 单条查询：`@GetMapping("base/{id}")` + `@PathVariable Long id`
|
||
- 添加：`@PostMapping("base")` + `@RequestBody @Valid XxxAddReq`
|
||
- 更新：`@PutMapping("base")` + `@RequestBody @Valid XxxUpdateReq`
|
||
- 删除：`@DeleteMapping("base")` + `@RequestBody @Valid IdListReq`
|
||
- 路径参数验证使用`@NotNull`、`@Min`、`@NotEmpty`等注解
|
||
- 请求体验证使用`@Valid`注解
|
||
|
||
#### 5.2 API接口定义
|
||
- 所有对外暴露的API接口定义在`api`模块中
|
||
- 接口定义为Java interface，不包含具体实现
|
||
- 接口方法返回值统一使用`Result<T>`封装
|
||
- 参数验证注解直接标注在接口方法参数上
|
||
|
||
#### 5.3 Service规范
|
||
- Service接口定义业务方法签名
|
||
- ServiceImpl使用`@Service`和`@Primary`注解
|
||
- 通过`@RequiredArgsConstructor`注入依赖（BaseService、Convert等）
|
||
- 写操作添加`@Transactional(rollbackFor = Exception.class)`
|
||
- 查询条件使用`LambdaQueryWrapper`构建
|
||
- 分页查询使用`PageReq<XxxPageReq>`接收参数，`PageResp<XxxResp>`返回结果
|
||
|
||
### 6. 配置管理规范
|
||
|
||
#### 6.1 配置文件
|
||
- 使用YAML格式配置文件
|
||
- 主配置文件为`application.yml`
|
||
- 通过`spring.profiles.active`管理多环境配置（如`boot-base`、`boot-db`、`app-sys`等）
|
||
|
||
#### 6.2 启动类规范
|
||
- 单体部署启动类放在`xtools-app-standalone`模块中
|
||
- 微服务启动类放在`{module}-boot`模块中
|
||
- 启动类格式为`{Module}Application`
|
||
- 添加`@SpringBootApplication`注解
|
||
|
||
### 7. 文档规范
|
||
|
||
#### 7.1 JavaDoc规范
|
||
- 所有public类和方法都必须添加JavaDoc注释
|
||
- 类注释格式：
|
||
```java
|
||
/**
|
||
* <p>Title : 类名</p>
|
||
* <p>Description : 类描述</p>
|
||
* <p>Company : org.xujun</p>
|
||
*
|
||
* @author : 作者
|
||
* @version : 1.0.0
|
||
* @date : 日期
|
||
*/
|
||
```
|
||
- 方法注释包含功能说明、`@param`参数说明、`@return`返回值说明
|
||
|
||
#### 7.2 Swagger/OpenAPI注解规范
|
||
- 控制器类添加`@Tag(name = "模块描述")`注解
|
||
- 控制器方法添加`@Operation(summary = "接口描述")`注解
|
||
- DTO字段添加`@Schema(description = "字段描述", example = "示例值")`注解
|
||
- 路径参数添加`@Schema(description = "...", example = "...")`注解
|
||
|
||
### 8. 智能体工作流程
|
||
基于上述规范，代码生成智能体需要遵循以下工作流程：
|
||
|
||
#### 8.1 新增业务模块
|
||
1. **API定义**：在`api`模块中定义服务接口（`XxxApi`），方法返回`Result<T>`
|
||
2. **实体创建**：在`biz/model/entity/`中创建继承`BaseEntity`的实体类
|
||
3. **Mapper创建**：在`biz/mapper/`中创建继承`BaseMapper<Entity>`的Mapper接口
|
||
4. **BaseService创建**：在`biz/service/base/`中创建继承`ServiceImpl<Mapper, Entity>`的BaseService
|
||
5. **DTO设计**：创建`XxxAddReq`、`XxxUpdateReq`、`XxxPageReq`、`XxxResp`
|
||
6. **Convert实现**：在`biz/convert/`中使用MapStruct实现对象转换
|
||
7. **Service实现**：在`biz/service/`中定义接口，在`biz/service/impl/`中实现业务逻辑
|
||
8. **Controller实现**：在`biz/controller/`中实现控制器，注入Service
|
||
|
||
#### 8.2 代码生成检查清单
|
||
- [ ] 实体类继承`BaseEntity`，使用`IdType.ASSIGN_ID`主键策略
|
||
- [ ] 需要CRUD操作的Mapper继承`BaseMapper<Entity>`，使用`@Mapper`注解
|
||
- [ ] BaseService继承`ServiceImpl<Mapper, Entity>`，使用`@Component`注解
|
||
- [ ] Service接口定义返回`Result<T>`的完整CRUD方法
|
||
- [ ] ServiceImpl使用`@Service`、`@RequiredArgsConstructor`注解；实现API接口时需添加`@Primary`注解
|
||
- [ ] Convert使用`@Mapper(componentModel = "spring")`注解
|
||
- [ ] Controller使用`@RestController`、`@Tag`、`@Operation`注解
|
||
- [ ] 所有DTO字段添加`@Schema`注解
|
||
- [ ] 写操作方法添加`@Transactional(rollbackFor = Exception.class)`
|
||
- [ ] 请求参数使用`@Valid`验证
|
||
- [ ] 分页查询使用`PageReq<XxxPageReq>`和`PageResp<XxxResp>`
|
||
- [ ] 删除操作使用`IdListReq`封装ID集合
|
||
- [ ] JavaDoc注释完整
|