--- 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 pageReq)` - 单条查询：`getById(Long id)` - 添加：`add(XxxAddReq req)` - 更新：`update(XxxUpdateReq req)` - 删除：`delById(List idList)` - 批量查询：`getListByIds(IdListReq req)` - 转换方法：`addReqToEntity()`、`updateReqToEntity()`、`entityToResp()`、`entityToRespList()` ### 3. 编码实现规范 #### 3.1 注解使用规范 - 控制器类使用`@RestController`注解 - 服务实现类使用`@Service`和`@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`（MyBatis Plus），使用`@Component`注解 - ServiceImpl类实现Service接口，注入BaseService和Convert进行业务操作 - Controller类通过构造器注入Service接口 - API接口定义为Java interface，方法返回`Result` - 实体类继承`BaseEntity`（来自`xtools.boot.api.model.entity.BaseEntity`） - 响应类继承`BaseEntity`（来自`xtools.boot.api.model.entity.BaseEntity`） #### 3.3 返回值规范 - 所有对外接口统一返回`Result`封装对象 - 分页查询返回`Result>`封装对象 - 分页请求参数使用`PageReq`封装 - 删除请求使用`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`（MyBatis Plus） - 使用`@Mapper`注解 - 复杂查询使用MyBatis XML映射文件，放置在`resources/mapper/`目录下 - XML中使用`LambdaQueryWrapper`或动态SQL（``、``、``） - 使用`QueryUtils.getPage()`和`QueryUtils.addTimeRange()`工具方法处理分页和时间范围 #### 4.5 BaseService规范 - BaseService类继承`ServiceImpl` - 使用`@Component`注解 - 用于封装通用数据访问方法和复杂查询逻辑 - 命名格式：`{业务名}BaseService`，如`SysUserBaseService` ### 5. 接口设计规范 #### 5.1 Controller规范 - 使用`@RestController`和`@RequestMapping("/模块/资源")`注解 - 使用`@Tag(name = "...")`描述模块功能 - 使用`@Operation(summary = "...")`描述每个接口 - 方法命名遵循RESTful风格：`page`、`getById`、`add`、`update`、`delById` - 分页接口：`@PostMapping("page")` + `@RequestBody @Valid PageReq` - 单条查询：`@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`封装 - 参数验证注解直接标注在接口方法参数上 #### 5.3 Service规范 - Service接口定义业务方法签名 - ServiceImpl使用`@Service`和`@Primary`注解 - 通过`@RequiredArgsConstructor`注入依赖（BaseService、Convert等） - 写操作添加`@Transactional(rollbackFor = Exception.class)` - 查询条件使用`LambdaQueryWrapper`构建 - 分页查询使用`PageReq`接收参数，`PageResp`返回结果 ### 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 /** *

Title : 类名

*

Description : 类描述

*

Company : org.xujun

* * @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` 2. **实体创建**：在`biz/model/entity/`中创建继承`BaseEntity`的实体类 3. **Mapper创建**：在`biz/mapper/`中创建继承`BaseMapper`的Mapper接口 4. **BaseService创建**：在`biz/service/base/`中创建继承`ServiceImpl`的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`主键策略 - [ ] Mapper继承`BaseMapper`，使用`@Mapper`注解 - [ ] BaseService继承`ServiceImpl`，使用`@Component`注解 - [ ] Service接口定义返回`Result`的完整CRUD方法 - [ ] ServiceImpl使用`@Service`、`@Primary`、`@RequiredArgsConstructor`注解 - [ ] Convert使用`@Mapper(componentModel = "spring")`注解 - [ ] Controller使用`@RestController`、`@Tag`、`@Operation`注解 - [ ] 所有DTO字段添加`@Schema`注解 - [ ] 写操作方法添加`@Transactional(rollbackFor = Exception.class)` - [ ] 请求参数使用`@Valid`验证 - [ ] 分页查询使用`PageReq`和`PageResp` - [ ] 删除操作使用`IdListReq`封装ID集合 - [ ] JavaDoc注释完整