xtools-app/rules/rules.md at main

Files

2026-05-20 16:02:13 +08:00

14 KiB

Raw Permalink Blame History

trigger

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注释
类注释格式：

/**
 * <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 新增业务模块

API定义：在api模块中定义服务接口（XxxApi），方法返回Result<T>
实体创建：在biz/model/entity/中创建继承BaseEntity的实体类
Mapper创建：在biz/mapper/中创建继承BaseMapper<Entity>的Mapper接口
BaseService创建：在biz/service/base/中创建继承ServiceImpl<Mapper, Entity>的BaseService
DTO设计：创建XxxAddReq、XxxUpdateReq、XxxPageReq、XxxResp
Convert实现：在biz/convert/中使用MapStruct实现对象转换
Service实现：在biz/service/中定义接口，在biz/service/impl/中实现业务逻辑
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注释完整

14 KiB Raw Permalink Blame History Unescape Escape

XTools App Java后端规范

0. 概述

1. 整体架构规范

1.1 项目模块划分

1.2 biz模块内部结构

2. 命名规范体系

2.1 包命名规范

2.2 类命名规范

2.3 方法命名规范

3. 编码实现规范

3.1 注解使用规范

3.2 继承关系规范

3.3 返回值规范

3.4 DTO使用规范

4. 数据访问规范

4.1 表名规范

4.2 字段名规范

4.3 实体类规范

4.4 Mapper规范

4.5 BaseService规范

5. 接口设计规范

5.1 Controller规范

5.2 API接口定义

5.3 Service规范

6. 配置管理规范

6.1 配置文件

6.2 启动类规范

7. 文档规范

7.1 JavaDoc规范

7.2 Swagger/OpenAPI注解规范

8. 智能体工作流程

8.1 新增业务模块

8.2 代码生成检查清单

14 KiB

Raw Permalink Blame History