ai-engineering-init 1.1.0

package/.claude/docs//345/267/245/345/205/267/347/261/273/344/275/277/347/224/250/346/214/207/345/215/227.md

@@ -0,0 +1,463 @@
+# 工具类使用指南
+
+> **重要提示**: 本项目是 RuoYi-Vue-Plus **纯后端项目**，采用**三层架构**。
+> 优先使用项目工具类，禁止重复造轮子。
+
+最后更新: 2026-02-09
+
+---
+
+## 🚨 核心规范
+
+### 禁止事项
+
+```java
+// ❌ 禁止使用 BeanUtils（必须使用 MapstructUtils）
+BeanUtils.copyProperties(source, target);  // 禁止！
+
+// ❌ 禁止使用 Map 传递业务数据
+public Map<String, Object> getXxx() { ... }  // 禁止！必须用 VO
+
+// ❌ 禁止使用完整类型引用
+public org.dromara.common.core.domain.R<XxxVo> getXxx()  // 禁止！
+// ✅ 正确：先 import，再使用短类名
+import org.dromara.common.core.domain.R;
+public R<XxxVo> getXxx()
+```
+
+### 工具类优先级
+
+```
+项目工具类 > Hutool > Apache Commons > 自己实现
+```
+
+---
+
+## 📋 快速索引
+
+| 功能 | 工具类 | 包路径 | 常用方法 |
+|------|--------|--------|---------|
+| **对象转换** | `MapstructUtils` | `o.d.common.core.utils` | `convert()` |
+| 字符串 | `StringUtils` | `o.d.common.core.utils` | `isBlank()`, `format()` |
+| 集合/流 | `StreamUtils` | `o.d.common.core.utils` | `filter()`, `toList()`, `toMap()` |
+| 树结构 | `TreeBuildUtils` | `o.d.common.core.utils` | `build()` |
+| 日期时间 | `DateUtils` | `o.d.common.core.utils` | `getTime()`, `formatDateTime()` |
+| Redis缓存 | `RedisUtils` | `o.d.common.redis.utils` | `setCacheObject()`, `getCacheObject()` |
+| Excel导出 | `ExcelUtil` | `o.d.common.excel.utils` | `exportExcel()` |
+| JSON | `JsonUtils` | `o.d.common.json.utils` | `toJsonString()`, `parseObject()` |
+| 登录用户 | `LoginHelper` | `o.d.common.satoken.utils` | `getUserId()`, `getUsername()` |
+| 业务异常 | `ServiceException` | `o.d.common.core.exception` | `throw new ServiceException()` |
+| Spring容器 | `SpringUtils` | `o.d.common.core.utils` | `getBean()` |
+| Hutool集合 | `CollUtil` | `cn.hutool.core.collection` | `isEmpty()`, `newArrayList()` |
+| Hutool对象 | `ObjectUtil` | `cn.hutool.core.util` | `isNull()`, `isEmpty()` |
+| ID生成 | `IdUtil` | `cn.hutool.core.util` | `getSnowflakeNextId()` |
+
+> **包路径说明**: `o.d` = `org.dromara`
+
+---
+
+## 1. 对象转换 - MapstructUtils（必须使用！）
+
+> ⚠️ **强制规范**: 禁止使用 `BeanUtils.copyProperties()`，必须使用 `MapstructUtils.convert()`
+
+```java
+import org.dromara.common.core.utils.MapstructUtils;
+
+// ✅ 单个对象转换
+XxxVo vo = MapstructUtils.convert(entity, XxxVo.class);
+Xxx entity = MapstructUtils.convert(bo, Xxx.class);
+
+// ✅ 集合转换
+List<XxxVo> voList = MapstructUtils.convert(entityList, XxxVo.class);
+
+// ❌ 禁止使用 BeanUtils
+// BeanUtils.copyProperties(source, target);  // 禁止！
+```
+
+**配合 @AutoMapper 注解**:
+
+```java
+// 在 BO 类上声明映射关系（单数，不是 @AutoMappers）
+@AutoMapper(target = Xxx.class, reverseConvertGenerate = false)
+public class XxxBo extends BaseEntity {
+    // ...
+}
+
+// 在 VO 类上声明映射关系
+@AutoMapper(target = Xxx.class)
+public class XxxVo implements Serializable {
+    // ...
+}
+```
+
+---
+
+## 2. 字符串操作 - StringUtils
+
+```java
+import org.dromara.common.core.utils.StringUtils;
+
+// 判空（推荐）
+StringUtils.isBlank(str);      // null / "" / 空白 都返回 true
+StringUtils.isNotBlank(str);
+StringUtils.isEmpty(str);      // null / "" 返回 true
+StringUtils.isNotEmpty(str);
+
+// 格式化（占位符 {}）
+StringUtils.format("用户 {} 不存在", userId);
+// 输出: "用户 123 不存在"
+
+// 字符串分割
+List<String> list = StringUtils.splitList("1,2,3");           // ["1", "2", "3"]
+List<Long> ids = StringUtils.splitTo("1,2,3", Convert::toLong); // 转换类型
+
+// 驼峰转换
+StringUtils.toCamelCase("user_name");           // "userName"
+StringUtils.toUnderScoreCase("userName");       // "user_name"
+```
+
+---
+
+## 3. 集合与流操作 - StreamUtils
+
+```java
+import org.dromara.common.core.utils.StreamUtils;
+
+// 过滤
+List<User> activeUsers = StreamUtils.filter(users, u -> "1".equals(u.getStatus()));
+
+// 提取属性为 List
+List<Long> ids = StreamUtils.toList(users, User::getId);
+
+// 提取属性为 Set
+Set<Long> deptIds = StreamUtils.toSet(users, User::getDeptId);
+
+// 转为 Map（value 是元素本身）
+Map<Long, User> userMap = StreamUtils.toIdentityMap(users, User::getId);
+
+// 转为 Map（自定义 key 和 value）
+Map<Long, String> nameMap = StreamUtils.toMap(users, User::getId, User::getName);
+
+// 分组
+Map<Long, List<User>> deptUserMap = StreamUtils.groupByKey(users, User::getDeptId);
+
+// 拼接字符串
+String names = StreamUtils.join(users, User::getName);           // "张三,李四,王五"
+String names = StreamUtils.join(users, User::getName, "|");      // "张三|李四|王五"
+```
+
+---
+
+## 4. 树结构构建 - TreeBuildUtils
+
+```java
+import org.dromara.common.core.utils.TreeBuildUtils;
+import cn.hutool.core.lang.tree.Tree;
+
+// 构建树（自动检测根节点）
+List<Tree<Long>> tree = TreeBuildUtils.build(list, (node, item) -> {
+    node.setId(item.getId());
+    node.setParentId(item.getParentId());
+    node.setName(item.getName());
+    node.setWeight(item.getOrderNum());  // 排序
+    // 扩展属性
+    node.putExtra("icon", item.getIcon());
+    node.putExtra("path", item.getPath());
+});
+
+// 指定根节点 ID
+List<Tree<Long>> tree = TreeBuildUtils.build(list, 0L, (node, item) -> {
+    // ...
+});
+```
+
+---
+
+## 5. 日期时间 - DateUtils
+
+```java
+import org.dromara.common.core.utils.DateUtils;
+
+// 获取当前时间
+Date now = DateUtils.getNowDate();
+String date = DateUtils.getDate();      // "2026-01-24"
+String time = DateUtils.getTime();      // "2026-01-24 15:30:00"
+
+// 格式化
+DateUtils.formatDate(date);             // "2026-01-24"
+DateUtils.formatDateTime(date);         // "2026-01-24 15:30:00"
+
+// 解析
+Date date = DateUtils.parseDate("2026-01-24");
+
+// 路径格式
+DateUtils.datePath();  // "2026/01/24"
+```
+
+---
+
+## 6. Redis 缓存 - RedisUtils
+
+```java
+import org.dromara.common.redis.utils.RedisUtils;
+import java.time.Duration;
+
+// 基本操作
+RedisUtils.setCacheObject("key", value);                        // 永久
+RedisUtils.setCacheObject("key", value, Duration.ofMinutes(30)); // 30分钟过期
+RedisUtils.getCacheObject("key");
+RedisUtils.deleteObject("key");
+RedisUtils.hasKey("key");
+
+// List 操作
+RedisUtils.setCacheList("listKey", dataList);
+List<T> list = RedisUtils.getCacheList("listKey");
+
+// Map/Hash 操作
+RedisUtils.setCacheMap("mapKey", dataMap);
+RedisUtils.setCacheMapValue("mapKey", "field", value);
+T value = RedisUtils.getCacheMapValue("mapKey", "field");
+
+// 原子操作
+RedisUtils.setAtomicValue("counter", 0);
+long val = RedisUtils.incrAtomicValue("counter");  // +1
+long val = RedisUtils.decrAtomicValue("counter");  // -1
+```
+
+---
+
+## 7. 登录用户 - LoginHelper
+
+```java
+import org.dromara.common.satoken.utils.LoginHelper;
+
+// 获取当前登录用户信息
+Long userId = LoginHelper.getUserId();
+String username = LoginHelper.getUsername();
+Long deptId = LoginHelper.getDeptId();
+String tenantId = LoginHelper.getTenantId();
+LoginUser loginUser = LoginHelper.getLoginUser();
+
+// 判断登录状态
+boolean isLogin = LoginHelper.isLogin();
+
+// 判断是否超级管理员
+boolean isSuperAdmin = LoginHelper.isSuperAdmin();
+```
+
+---
+
+## 8. 业务异常 - ServiceException
+
+```java
+import org.dromara.common.core.exception.ServiceException;
+
+// 抛出业务异常
+throw new ServiceException("用户不存在");
+throw new ServiceException("用户 {} 不存在", userId);
+
+// 条件判断
+if (user == null) {
+    throw new ServiceException("用户不存在");
+}
+```
+
+---
+
+## 9. Excel 导出 - ExcelUtil
+
+```java
+import org.dromara.common.excel.utils.ExcelUtil;
+
+// Controller 中导出
+@PostMapping("/export")
+public void export(XxxBo bo, HttpServletResponse response) {
+    List<XxxVo> list = xxxService.queryList(bo);
+    ExcelUtil.exportExcel(list, "数据导出", XxxVo.class, response);
+}
+```
+
+**VO 类 Excel 注解**:
+
+```java
+@Data
+@ExcelIgnoreUnannotated
+public class XxxVo implements Serializable {
+
+    @ExcelProperty(value = "ID")
+    private Long id;
+
+    @ExcelProperty(value = "名称")
+    private String name;
+
+    @ExcelProperty(value = "状态")
+    @ExcelDictFormat(dictType = "sys_normal_disable")
+    private String status;
+
+    @ExcelProperty(value = "创建时间")
+    private Date createTime;
+}
+```
+
+---
+
+## 10. JSON 操作 - JsonUtils
+
+```java
+import org.dromara.common.json.utils.JsonUtils;
+
+// 对象转 JSON
+String json = JsonUtils.toJsonString(obj);
+
+// JSON 转对象
+User user = JsonUtils.parseObject(json, User.class);
+
+// JSON 转 List
+List<User> list = JsonUtils.parseArray(json, User.class);
+
+// JSON 转 Map
+Map<String, Object> map = JsonUtils.parseMap(json);
+```
+
+---
+
+## 11. Hutool 常用工具
+
+```java
+import cn.hutool.core.collection.CollUtil;
+import cn.hutool.core.util.ObjectUtil;
+import cn.hutool.core.util.IdUtil;
+
+// 集合判空
+CollUtil.isEmpty(list);
+CollUtil.isNotEmpty(list);
+CollUtil.newArrayList(1, 2, 3);
+
+// 对象判空
+ObjectUtil.isNull(obj);
+ObjectUtil.isNotNull(obj);
+ObjectUtil.isEmpty(obj);      // null / 空字符串 / 空集合
+ObjectUtil.defaultIfNull(obj, defaultValue);
+
+// ID 生成
+long snowflakeId = IdUtil.getSnowflakeNextId();  // 雪花ID（推荐）
+String uuid = IdUtil.simpleUUID();    // 无横线 UUID
+```
+
+---
+
+## 12. 参数校验 - ValidatorUtils
+
+```java
+import org.dromara.common.core.utils.ValidatorUtils;
+import org.dromara.common.core.validate.AddGroup;
+import org.dromara.common.core.validate.EditGroup;
+
+// Controller 层使用 @Validated（推荐）
+@PostMapping
+public R<Void> add(@Validated(AddGroup.class) @RequestBody XxxBo bo) {
+    // ...
+}
+
+@PutMapping
+public R<Void> edit(@Validated(EditGroup.class) @RequestBody XxxBo bo) {
+    // ...
+}
+```
+
+**BO 类校验注解**:
+
+```java
+public class XxxBo extends BaseEntity {
+
+    @NotNull(message = "ID不能为空", groups = { EditGroup.class })
+    private Long id;
+
+    @NotBlank(message = "名称不能为空", groups = { AddGroup.class, EditGroup.class })
+    @Size(max = 100, message = "名称长度不能超过100个字符")
+    private String name;
+
+    @Email(message = "邮箱格式不正确")
+    private String email;
+}
+```
+
+---
+
+## 📊 工具类选择速查
+
+| 需求 | 推荐工具 | 说明 |
+|------|---------|------|
+| BO ↔ Entity ↔ VO 转换 | `MapstructUtils.convert()` | **必须使用** |
+| 字符串判空 | `StringUtils.isBlank()` | 推荐项目工具类 |
+| 集合判空 | `CollUtil.isEmpty()` | Hutool |
+| 对象判空 | `ObjectUtil.isNull()` | Hutool |
+| 提取集合属性 | `StreamUtils.toList()` | 项目工具类 |
+| 集合转 Map | `StreamUtils.toIdentityMap()` | 项目工具类 |
+| 分组 | `StreamUtils.groupByKey()` | 项目工具类 |
+| 构建树 | `TreeBuildUtils.build()` | 项目工具类 |
+| 日期格式化 | `DateUtils.formatDateTime()` | 项目工具类 |
+| 抛业务异常 | `throw new ServiceException()` | 项目异常类 |
+| 获取登录用户 | `LoginHelper.getUserId()` | 项目工具类 |
+| Redis 缓存 | `RedisUtils.setCacheObject()` | 项目工具类 |
+| Excel 导出 | `ExcelUtil.exportExcel()` | 项目工具类 |
+| 生成 ID | `IdUtil.getSnowflakeNextId()` | Hutool |
+
+---
+
+## ✅ 在 Service 中的典型用法
+
+```java
+@Service
+@RequiredArgsConstructor
+public class XxxServiceImpl implements IXxxService {
+
+    private final XxxMapper baseMapper;
+
+    @Override
+    public Boolean insertByBo(XxxBo bo) {
+        // 业务校验
+        if (isNameExists(bo.getXxxName())) {
+            throw new ServiceException("名称已存在");
+        }
+
+        // 对象转换（必须使用 MapstructUtils）
+        Xxx entity = MapstructUtils.convert(bo, Xxx.class);
+
+        return baseMapper.insert(entity) > 0;
+    }
+
+    @Override
+    public List<XxxVo> queryList(XxxBo bo) {
+        LambdaQueryWrapper<Xxx> lqw = buildQueryWrapper(bo);
+        return baseMapper.selectVoList(lqw);
+    }
+
+    private LambdaQueryWrapper<Xxx> buildQueryWrapper(XxxBo bo) {
+        LambdaQueryWrapper<Xxx> lqw = Wrappers.lambdaQuery();
+        // 字符串判空使用 StringUtils.isNotBlank
+        lqw.like(StringUtils.isNotBlank(bo.getXxxName()), Xxx::getXxxName, bo.getXxxName());
+        lqw.eq(StringUtils.isNotBlank(bo.getStatus()), Xxx::getStatus, bo.getStatus());
+        return lqw;
+    }
+
+    private boolean isNameExists(String name) {
+        return baseMapper.exists(Wrappers.<Xxx>lambdaQuery()
+            .eq(Xxx::getXxxName, name));
+    }
+}
+```
+
+---
+
+## 🎯 总结
+
+**核心原则**：
+
+- ✅ **对象转换必须使用 `MapstructUtils.convert()`**（禁止 BeanUtils）
+- ✅ 字符串判空使用 `StringUtils.isBlank()`
+- ✅ 集合操作使用 `StreamUtils`
+- ✅ 树结构使用 `TreeBuildUtils`
+- ✅ 业务异常使用 `ServiceException`
+- ✅ 登录用户使用 `LoginHelper`
+- ✅ 缓存操作使用 `RedisUtils`