ai-engineering-init 1.7.0 → 1.8.0

package/.cursor/skills/utils-toolkit/SKILL.md

@@ -1,328 +1,319 @@
 ---
 name: utils-toolkit
 description: |
-  后端工具类使用指南。包含 MapstructUtils、StringUtils、StreamUtils、TreeBuildUtils、DateUtils、RedisUtils 等核心工具类。
+  后端工具类使用指南。包含对象转换、字符串处理、集合操作、树结构构建、日期时间、JSON、参数校验等通用工具类选型与使用规范。
 
   触发场景：
   - 对象转换（BO/VO/Entity）
   - 字符串处理、集合流操作
   - 树结构构建
-  - Redis 缓存操作
-  - Excel 导入导出
+  - JSON 序列化/反序列化
+  - 日期时间处理
+  - 参数校验
 
-  触发词：工具类、MapstructUtils、StringUtils、StreamUtils、TreeBuildUtils、DateUtils、RedisUtils、ExcelUtil、JsonUtils、LoginHelper、convert、对象转换、集合操作、树结构、缓存
+  触发词：工具类、对象转换、BeanUtils、StringUtils、集合操作、树结构、DateUtils、JsonUtils、convert、字符串处理、日期时间
 
   注意：
-  - 对象转换必须使用 MapstructUtils.convert()，禁止使用 BeanUtils。
-  - 本项目是纯后端项目，无前端工具类。
+  - 对象转换工具需要根据项目实际选型统一使用，禁止混用多种方案。
+  - 本指南为通用 Java 后端工具类指南，适配各类 Spring Boot 项目。
 ---
 
 # 后端工具类大全
 
 ## 快速索引
 
-| 功能 | 工具类 | 包路径 | 常用方法 |
-|------|--------|--------|---------|
-| **对象转换** | `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()` |
-| 参数校验 | `ValidatorUtils` | `o.d.common.core.utils` | `validate()` |
-| 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()` |
-
-> **包路径说明**: `o.d` = `org.dromara`
+| 功能 | 推荐方案 | 备选方案 | 常用方法 |
+|------|---------|---------|---------|
+| **对象转换** | `[你的对象转换工具]` | MapStruct / BeanUtils / ModelMapper | `convert()` / `copyProperties()` |
+| 字符串 | Hutool `StrUtil` | Apache Commons `StringUtils` / Guava `Strings` | `isBlank()`, `format()` |
+| 集合/流 | Hutool `CollUtil` + Java Stream | Guava `Collections2` | `isEmpty()`, `filter()`, `toList()` |
+| 树结构 | Hutool `TreeUtil` | 自定义递归构建 | `build()` |
+| 日期时间 | `java.time` API | Hutool `DateUtil` | `LocalDateTime.now()`, `format()` |
+| 参数校验 | Jakarta Validation | Hutool `Validator` | `@NotNull`, `@NotBlank` |
+| JSON | Jackson `ObjectMapper` | Gson / Hutool `JSONUtil` | `toJsonString()`, `parseObject()` |
+| 业务异常 | `[你的异常类]` | 自定义 RuntimeException | `throw new [YourException]()` |
+| 登录用户 | `[你的用户上下文工具]` | SecurityContextHolder / 自定义 ThreadLocal | `getUserId()`, `getUsername()` |
+| Spring容器 | `ApplicationContext` | 自定义 `SpringUtils` | `getBean()` |
 
 ---
 
-## 1. 对象转换 - MapstructUtils（必须使用！）
+## 1. 对象转换
 
-> **强制规范**: 禁止使用 `BeanUtils.copyProperties()`，必须使用 `MapstructUtils.convert()`
+### 选型对比
 
-```java
-import org.dromara.common.core.utils.MapstructUtils;
+| 方案 | 性能 | 易用性 | 特点 |
+|------|------|--------|------|
+| **MapStruct** | 极高（编译期生成） | 中（需定义接口） | 类型安全、零反射 |
+| **Hutool BeanUtil** | 中（反射） | 高（一行调用） | 简单场景首选 |
+| **Spring BeanUtils** | 中（反射） | 高 | Spring 内置，无额外依赖 |
+| **ModelMapper** | 低 | 高（约定优于配置） | 深度映射、复杂场景 |
 
-// 单个对象转换
-XxxVo vo = MapstructUtils.convert(entity, XxxVo.class);
+### 通用用法
 
-// 集合转换
-List<XxxVo> voList = MapstructUtils.convert(entityList, XxxVo.class);
+```java
+// 方案 A: Hutool BeanUtil（简单场景推荐）
+import cn.hutool.core.bean.BeanUtil;
+
+XxxVo vo = BeanUtil.copyProperties(entity, XxxVo.class);
+List<XxxVo> voList = BeanUtil.copyToList(entityList, XxxVo.class);
+
+// 方案 B: MapStruct（高性能场景推荐）
+// 1. 定义 Mapper 接口
+@Mapper(componentModel = "spring")
+public interface XxxConverter {
+    XxxVo toVo(XxxEntity entity);
+    List<XxxVo> toVoList(List<XxxEntity> entities);
+}
 
-// 转换到已有对象（合并属性）
-XxxVo vo = MapstructUtils.convert(source, existingVo);
+// 2. 注入使用
+@Resource
+private XxxConverter xxxConverter;
+XxxVo vo = xxxConverter.toVo(entity);
 ```
 
-**配合 @AutoMapper 注解**:
+---
+
+## 2. 字符串操作
+
+### Hutool StrUtil
 
 ```java
-@AutoMapper(target = Xxx.class, reverseConvertGenerate = false)
-public class XxxBo extends BaseEntity { }
+import cn.hutool.core.util.StrUtil;
 
-@AutoMapper(target = Xxx.class)
-public class XxxVo implements Serializable { }
-```
+// 判空
+StrUtil.isBlank(str);       // null / "" / " " -> true
+StrUtil.isNotBlank(str);
 
----
+// 格式化（占位符 {}）
+StrUtil.format("用户 {} 不存在", userId);
 
-## 2. 字符串操作 - StringUtils
+// 分割/拼接
+List<String> list = StrUtil.split("1,2,3", ',');
+String joined = String.join(",", list);
+```
 
-```java
-import org.dromara.common.core.utils.StringUtils;
+### Apache Commons StringUtils
 
-// 格式化（占位符 {}）—— 项目特有
-StringUtils.format("用户 {} 不存在", userId);
+```java
+import org.apache.commons.lang3.StringUtils;
 
-// 字符串分割/拼接 —— 项目特有
-List<String> list = StringUtils.splitList("1,2,3");
-List<Long> ids = StringUtils.splitTo("1,2,3", Convert::toLong);
-String str = StringUtils.joinComma(list);
+StringUtils.isBlank(str);
+StringUtils.substringBefore(str, "-");
+StringUtils.leftPad("5", 3, '0');   // "005"
+```
 
-// 驼峰转换
-StringUtils.toCamelCase("user_name");           // "userName"
-StringUtils.toUnderScoreCase("userName");       // "user_name"
+### Guava Strings
 
-// Ant 风格路径匹配
-StringUtils.isMatch("/api/**", "/api/user/list");
-StringUtils.matches("/api/user", Arrays.asList("/api/**", "/admin/**"));
+```java
+import com.google.common.base.Strings;
 
-// 左补零
-StringUtils.padl(5, 3);  // "005"
+Strings.isNullOrEmpty(str);
+Strings.padStart("5", 3, '0');   // "005"
 ```
 
 ---
 
-## 3. 集合与流操作 - StreamUtils
+## 3. 集合与流操作
+
+### Hutool CollUtil
 
 ```java
-import org.dromara.common.core.utils.StreamUtils;
+import cn.hutool.core.collection.CollUtil;
 
-// 过滤
-List<User> active = StreamUtils.filter(users, u -> "1".equals(u.getStatus()));
+CollUtil.isEmpty(list);       // null 或空 -> true
+CollUtil.isNotEmpty(list);
+```
 
-// 查找
-User user = StreamUtils.findFirstValue(users, u -> u.getId().equals(id));
+### Java Stream API
+
+```java
+// 过滤
+List<User> active = users.stream()
+    .filter(u -> "1".equals(u.getStatus()))
+    .toList();
 
 // 提取属性
-List<Long> ids = StreamUtils.toList(users, User::getId);
-Set<Long> deptIds = StreamUtils.toSet(users, User::getDeptId);
+List<Long> ids = users.stream()
+    .map(User::getId)
+    .toList();
+
+Set<Long> deptIds = users.stream()
+    .map(User::getDeptId)
+    .collect(Collectors.toSet());
 
 // 转 Map
-Map<Long, User> userMap = StreamUtils.toIdentityMap(users, User::getId);
-Map<Long, String> nameMap = StreamUtils.toMap(users, User::getId, User::getName);
+Map<Long, User> userMap = users.stream()
+    .collect(Collectors.toMap(User::getId, Function.identity()));
+
+Map<Long, String> nameMap = users.stream()
+    .collect(Collectors.toMap(User::getId, User::getName));
 
 // 分组
-Map<Long, List<User>> grouped = StreamUtils.groupByKey(users, User::getDeptId);
+Map<Long, List<User>> grouped = users.stream()
+    .collect(Collectors.groupingBy(User::getDeptId));
 
 // 拼接字符串
-String names = StreamUtils.join(users, User::getName);        // "张三,李四,王五"
-String names = StreamUtils.join(users, User::getName, "|");   // 自定义分隔符
-
-// 排序 / 合并 Map
-List<User> sorted = StreamUtils.sorted(users, Comparator.comparing(User::getCreateTime));
-Map<Long, String> merged = StreamUtils.merge(map1, map2, (v1, v2) -> v1 + v2);
+String names = users.stream()
+    .map(User::getName)
+    .collect(Collectors.joining(","));
 ```
 
 ---
 
-## 4. 树结构构建 - TreeBuildUtils
+## 4. 树结构构建
+
+### Hutool TreeUtil
 
 ```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());
+import cn.hutool.core.lang.tree.TreeUtil;
+import cn.hutool.core.lang.tree.TreeNodeConfig;
+
+List<Tree<Long>> tree = TreeUtil.build(list, 0L, (item, treeNode) -> {
+    treeNode.setId(item.getId());
+    treeNode.setParentId(item.getParentId());
+    treeNode.setName(item.getName());
+    treeNode.setWeight(item.getOrderNum());
+    treeNode.putExtra("icon", item.getIcon());
 });
+```
+
+### 自定义递归构建
 
-// 指定根节点 ID
-List<Tree<Long>> tree = TreeBuildUtils.build(list, 0L, (node, item) -> { ... });
+```java
+public List<TreeNode> buildTree(List<TreeNode> nodes, Long parentId) {
+    return nodes.stream()
+        .filter(n -> Objects.equals(n.getParentId(), parentId))
+        .peek(n -> n.setChildren(buildTree(nodes, n.getId())))
+        .sorted(Comparator.comparingInt(TreeNode::getSort))
+        .toList();
+}
 ```
 
 ---
 
-## 5. 日期时间 - DateUtils
+## 5. 日期时间 - java.time API
 
 ```java
-import org.dromara.common.core.utils.DateUtils;
-import org.dromara.common.core.enums.FormatsType;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+import java.time.Duration;
+import java.time.temporal.ChronoUnit;
 
 // 获取当前时间
-String date = DateUtils.getDate();   // "2026-01-24"
-String time = DateUtils.getTime();   // "2026-01-24 15:30:00"
+LocalDateTime now = LocalDateTime.now();
+LocalDate today = LocalDate.now();
 
-// 格式化 / 解析
-DateUtils.formatDateTime(date);
-DateUtils.parseDateToStr(FormatsType.YYYY_MM_DD_HH_MM, date);
-Date date = DateUtils.parseDateTime(FormatsType.YYYY_MM_DD_HH_MM_SS, "2026-01-24 15:30:00");
+// 格式化
+DateTimeFormatter fmt = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
+String formatted = now.format(fmt);
 
-// 时间差
-long days = DateUtils.difference(start, end, TimeUnit.DAYS);
-String diff = DateUtils.getDatePoor(endDate, startDate);  // "3天 2小时 30分钟"
-
-// 日期范围校验
-DateUtils.validateDateRange(startDate, endDate, 30, TimeUnit.DAYS);
+// 解析
+LocalDateTime parsed = LocalDateTime.parse("2026-01-24 15:30:00", fmt);
 
-// 友好时间（仿微信）
-DateUtils.formatFriendlyTime(date);  // "刚刚" / "5分钟前" / "昨天 14:30"
+// 时间差
+long days = ChronoUnit.DAYS.between(start, end);
+Duration duration = Duration.between(start, end);
+long hours = duration.toHours();
 
-// 类型转换
-Date date = DateUtils.toDate(localDateTime);
+// 日期加减
+LocalDateTime tomorrow = now.plusDays(1);
+LocalDateTime lastMonth = now.minusMonths(1);
 ```
 
-**FormatsType 枚举**: `YYYY_MM_DD` | `YYYY_MM_DD_HH_MM_SS` | `YYYY_MM_DD_HH_MM` | `YYYYMMDD` | `YYYYMMDDHHMMSS` | `HH_MM_SS`
-
----
-
-## 6. 参数校验 - ValidatorUtils
+### Hutool DateUtil（兼容旧 Date 类型）
 
 ```java
-import org.dromara.common.core.utils.ValidatorUtils;
-import org.dromara.common.core.validate.AddGroup;
-import org.dromara.common.core.validate.EditGroup;
+import cn.hutool.core.date.DateUtil;
 
-// Service 层手动校验
-ValidatorUtils.validate(bo, AddGroup.class);
+// 自动识别多种格式
+Date date = DateUtil.parse("2026-01-24 15:30:00");
+String formatted = DateUtil.formatDateTime(date);
 
-// Controller 层（推荐）
-@PostMapping
-public R<Void> add(@Validated(AddGroup.class) @RequestBody XxxBo bo) { }
-
-@PutMapping
-public R<Void> edit(@Validated(EditGroup.class) @RequestBody XxxBo bo) { }
+// 时间差
+long between = DateUtil.between(start, end, DateUnit.DAY);
 ```
 
-**BO 类校验注解**:
+---
+
+## 6. 参数校验
+
+### Jakarta Validation（JDK 17+ 推荐）
 
 ```java
-public class XxxBo extends BaseEntity {
-    @NotNull(message = "ID不能为空", groups = { EditGroup.class })
+import jakarta.validation.constraints.*;
+
+public class XxxDTO {
+    @NotNull(message = "ID不能为空", groups = {UpdateGroup.class})
     private Long id;
 
-    @NotBlank(message = "名称不能为空", groups = { AddGroup.class, EditGroup.class })
+    @NotBlank(message = "名称不能为空", groups = {InsertGroup.class, UpdateGroup.class})
     @Size(max = 100, message = "名称长度不能超过100个字符")
     private String name;
+
+    @Min(value = 0, message = "数量不能为负数")
+    private Integer quantity;
 }
 ```
 
----
-
-## 7. Redis 缓存 - RedisUtils
-
-> 详细 API 见 `references/redis-utils-api.md`
+### Controller 层使用
 
 ```java
-import org.dromara.common.redis.utils.RedisUtils;
-
-// 基本操作
-RedisUtils.setCacheObject("key", value);
-RedisUtils.setCacheObject("key", value, Duration.ofMinutes(30));
-RedisUtils.getCacheObject("key");
-RedisUtils.deleteObject("key");
-RedisUtils.hasKey("key");
-
-// 条件设置
-RedisUtils.setObjectIfAbsent("key", value, Duration.ofMinutes(5));
-
-// List / Set / Map 操作
-RedisUtils.setCacheList("listKey", dataList);
-RedisUtils.setCacheMap("mapKey", dataMap);
-RedisUtils.setCacheMapValue("mapKey", "field", value);
-
-// 原子操作
-long val = RedisUtils.incrAtomicValue("counter");
+@PostMapping("/add")
+public void add(@Validated(InsertGroup.class) @RequestBody XxxDTO dto) { }
 
-// 发布订阅
-RedisUtils.publish("channel", message);
-RedisUtils.subscribe("channel", Message.class, msg -> { });
-
-// 限流
-long remaining = RedisUtils.rateLimiter("api:user:list", RateType.OVERALL, 100, 60);
+@PutMapping("/update")
+public void edit(@Validated(UpdateGroup.class) @RequestBody XxxDTO dto) { }
 ```
 
 ---
 
-## 8. 登录用户 - 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();
-boolean isTenantAdmin = LoginHelper.isTenantAdmin();
-```
-
----
+## 7. JSON 操作
 
-## 9. 业务异常 - ServiceException
+### Jackson（Spring Boot 默认）
 
 ```java
-import org.dromara.common.core.exception.ServiceException;
-
-throw new ServiceException("用户不存在");
-throw new ServiceException("用户 {} 不存在", userId);
-throw new ServiceException("用户不存在", 500);  // 带错误码
-```
+import com.fasterxml.jackson.databind.ObjectMapper;
 
----
-
-## 10. Excel 导出 - ExcelUtil
+// 推荐封装为项目统一的 JsonUtils
+public class JsonUtils {
+    private static final ObjectMapper MAPPER = new ObjectMapper();
 
-```java
-import org.dromara.common.excel.utils.ExcelUtil;
+    public static String toJsonString(Object obj) {
+        return MAPPER.writeValueAsString(obj);
+    }
 
-// 导出
-@PostMapping("/export")
-public void export(XxxBo bo, HttpServletResponse response) {
-    List<XxxVo> list = xxxService.queryList(bo);
-    ExcelUtil.exportExcel(list, "数据导出", XxxVo.class, response);
-}
+    public static <T> T parseObject(String json, Class<T> clazz) {
+        return MAPPER.readValue(json, clazz);
+    }
 
-// 导入
-@PostMapping("/import")
-public R<Void> importData(@RequestPart("file") MultipartFile file) throws Exception {
-    List<XxxVo> list = ExcelUtil.importExcel(file.getInputStream(), XxxVo.class);
-    return R.ok();
+    public static <T> List<T> parseArray(String json, Class<T> clazz) {
+        return MAPPER.readValue(json,
+            MAPPER.getTypeFactory().constructCollectionType(List.class, clazz));
+    }
 }
 ```
 
-**VO 类 Excel 注解**:
+### Hutool JSONUtil
 
 ```java
-public class XxxVo implements Serializable {
-    @ExcelProperty(value = "ID")
-    private Long id;
+import cn.hutool.json.JSONUtil;
 
-    @ExcelProperty(value = "状态", converter = ExcelDictConvert.class)
-    @ExcelDictFormat(dictType = "sys_normal_disable")
-    private String status;
-}
+String json = JSONUtil.toJsonStr(obj);
+User user = JSONUtil.toBean(json, User.class);
 ```
 
 ---
 
-## 11. JSON 操作 - JsonUtils
+## 8. 对象判空
 
 ```java
-import org.dromara.common.json.utils.JsonUtils;
+import cn.hutool.core.util.ObjectUtil;
 
-String json = JsonUtils.toJsonString(obj);
-User user = JsonUtils.parseObject(json, User.class);
-List<User> list = JsonUtils.parseArray(json, User.class);
-Map<String, Object> map = JsonUtils.parseMap(json);
+ObjectUtil.isNull(obj);       // null -> true
+ObjectUtil.isNotNull(obj);
+ObjectUtil.defaultIfNull(obj, defaultValue);
 ```
 
 ---
@@ -331,18 +322,17 @@ Map<String, Object> map = JsonUtils.parseMap(json);
 
 | 需求 | 推荐工具 | 说明 |
 |------|---------|------|
-| BO/Entity/VO 转换 | `MapstructUtils.convert()` | **必须使用** |
-| 字符串判空 | `StringUtils.isBlank()` | 项目工具类 |
+| BO/Entity/VO 转换 | `[你的对象转换工具]` | 项目统一选型 |
+| 字符串判空 | `StrUtil.isBlank()` | Hutool |
 | 集合判空 | `CollUtil.isEmpty()` | Hutool |
 | 对象判空 | `ObjectUtil.isNull()` | Hutool |
-| 提取集合属性 | `StreamUtils.toList()` | 项目工具类 |
-| 集合转 Map | `StreamUtils.toIdentityMap()` | 项目工具类 |
-| 构建树 | `TreeBuildUtils.build()` | 项目工具类 |
-| 日期格式化 | `DateUtils.formatDateTime()` | 项目工具类 |
-| 抛业务异常 | `throw new ServiceException()` | 项目异常类 |
-| 获取登录用户 | `LoginHelper.getUserId()` | 项目工具类 |
-| Redis 缓存 | `RedisUtils.setCacheObject()` | 项目工具类 |
-| Excel 导出 | `ExcelUtil.exportExcel()` | 项目工具类 |
+| 提取集合属性 | `Stream.map().toList()` | Java Stream |
+| 集合转 Map | `Collectors.toMap()` | Java Stream |
+| 构建树 | `TreeUtil.build()` | Hutool |
+| 日期格式化 | `LocalDateTime.format()` | java.time |
+| 抛业务异常 | `throw new [你的异常类]()` | 项目自定义 |
+| 获取登录用户 | `[你的用户上下文工具]` | 项目自定义 |
+| Excel 导出 | EasyExcel / Apache POI | 按需选型 |
 | 生成 ID | `IdUtil.getSnowflakeNextId()` | Hutool |
 
 ---
@@ -350,13 +340,15 @@ Map<String, Object> map = JsonUtils.parseMap(json);
 ## 禁止事项
 
 ```java
-// ❌ 禁止使用 BeanUtils
-BeanUtils.copyProperties(source, target);
-
 // ❌ 禁止使用 Map 传递业务数据
 public Map<String, Object> getXxx() { ... }
+// ✅ 正确：使用 VO/DTO
+public XxxVO getXxx() { ... }
+
+// ❌ 禁止频繁创建 ObjectMapper
+ObjectMapper mapper = new ObjectMapper();
+// ✅ 正确：使用单例或项目统一封装的 JsonUtils
 
-// ❌ 禁止手写 stream 转换（应使用 StreamUtils）
-list.stream().map(User::getId).collect(Collectors.toList());  // 不推荐
-StreamUtils.toList(list, User::getId);  // ✅ 推荐
+// ❌ 禁止混用多种对象转换工具
+// ✅ 正确：项目统一选型，保持一致
 ```