ai-engineering-init 1.3.4 → 1.4.1

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

@@ -5,15 +5,12 @@ description: |
 
   触发场景：
   - 对象转换（BO/VO/Entity）
-  - 字符串处理
-  - 集合流操作
+  - 字符串处理、集合流操作
   - 树结构构建
-  - 日期时间处理
   - Redis 缓存操作
   - Excel 导入导出
-  - JSON 序列化
 
-  触发词：工具类、MapstructUtils、StringUtils、StreamUtils、TreeBuildUtils、DateUtils、RedisUtils、ExcelUtil、JsonUtils、LoginHelper、CollUtil、ObjectUtil、IdUtil、convert、对象转换、集合操作、树结构、缓存
+  触发词：工具类、MapstructUtils、StringUtils、StreamUtils、TreeBuildUtils、DateUtils、RedisUtils、ExcelUtil、JsonUtils、LoginHelper、convert、对象转换、集合操作、树结构、缓存
 
   注意：
   - 对象转换必须使用 MapstructUtils.convert()，禁止使用 BeanUtils。
@@ -22,8 +19,6 @@ description: |
 
 # 后端工具类大全
 
-> 本项目是纯后端项目，本文档专注于 Java 后端工具类。
-
 ## 快速索引
 
 | 功能 | 工具类 | 包路径 | 常用方法 |
@@ -40,9 +35,6 @@ description: |
 | 登录用户 | `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`
 
@@ -50,42 +42,29 @@ description: |
 
 ## 1. 对象转换 - MapstructUtils（必须使用！）
 
-> ⚠️ **强制规范**: 禁止使用 `BeanUtils.copyProperties()`，必须使用 `MapstructUtils.convert()`
+> **强制规范**: 禁止使用 `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);
 
-// ✅ 转换到已有对象（合并属性）
+// 转换到已有对象（合并属性）
 XxxVo vo = MapstructUtils.convert(source, existingVo);
-
-// ✅ Map 转 Bean
-Xxx entity = MapstructUtils.convert(map, Xxx.class);
-
-// ❌ 禁止使用 BeanUtils
-// BeanUtils.copyProperties(source, target);  // 禁止！
 ```
 
 **配合 @AutoMapper 注解**:
 
 ```java
-// 在 BO 类上声明映射关系
 @AutoMapper(target = Xxx.class, reverseConvertGenerate = false)
-public class XxxBo extends BaseEntity {
-    // ...
-}
+public class XxxBo extends BaseEntity { }
 
-// 在 VO 类上声明映射关系
 @AutoMapper(target = Xxx.class)
-public class XxxVo implements Serializable {
-    // ...
-}
+public class XxxVo implements Serializable { }
 ```
 
 ---
@@ -95,40 +74,24 @@ public class XxxVo implements Serializable {
 ```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<String> list = StringUtils.splitList("1|2|3", "|");      // 自定义分隔符
-List<Long> ids = StringUtils.splitTo("1,2,3", Convert::toLong); // 转换类型
 
-// 字符串拼接
-String str = StringUtils.joinComma(list);       // "1,2,3"
-String str = StringUtils.joinComma(array);      // 数组版本
+// 字符串分割/拼接 —— 项目特有
+List<String> list = StringUtils.splitList("1,2,3");
+List<Long> ids = StringUtils.splitTo("1,2,3", Convert::toLong);
+String str = StringUtils.joinComma(list);
 
 // 驼峰转换
 StringUtils.toCamelCase("user_name");           // "userName"
 StringUtils.toUnderScoreCase("userName");       // "user_name"
-StringUtils.convertToCamelCase("user_name");    // "UserName" (首字母大写)
 
-// 截取
-StringUtils.substring(str, 0, 10);
-
-// 路径匹配（Ant 风格）
-StringUtils.isMatch("/api/**", "/api/user/list");  // true
+// Ant 风格路径匹配
+StringUtils.isMatch("/api/**", "/api/user/list");
 StringUtils.matches("/api/user", Arrays.asList("/api/**", "/admin/**"));
 
 // 左补零
-StringUtils.padl(5, 3);     // "005"
-StringUtils.padl("ab", 5, '0');  // "000ab"
+StringUtils.padl(5, 3);  // "005"
 ```
 
 ---
@@ -139,40 +102,28 @@ StringUtils.padl("ab", 5, '0');  // "000ab"
 import org.dromara.common.core.utils.StreamUtils;
 
 // 过滤
-List<User> activeUsers = StreamUtils.filter(users, u -> "1".equals(u.getStatus()));
+List<User> active = StreamUtils.filter(users, u -> "1".equals(u.getStatus()));
 
-// 查找第一个
-Optional<User> user = StreamUtils.findFirst(users, u -> u.getId().equals(id));
-User user = StreamUtils.findFirstValue(users, u -> u.getId().equals(id));  // 返回 null 而非 Optional
+// 查找
+User user = StreamUtils.findFirstValue(users, u -> u.getId().equals(id));
 
-// 提取属性为 List
+// 提取属性
 List<Long> ids = StreamUtils.toList(users, User::getId);
-
-// 提取属性为 Set
 Set<Long> deptIds = StreamUtils.toSet(users, User::getDeptId);
 
-// 转为 Map（value 是元素本身）
+// 转 Map
 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);
-
-// 双层分组
-Map<Long, Map<String, List<User>>> map = StreamUtils.groupBy2Key(
-    users, User::getDeptId, User::getStatus
-);
+Map<Long, List<User>> grouped = StreamUtils.groupByKey(users, User::getDeptId);
 
 // 拼接字符串
-String names = StreamUtils.join(users, User::getName);           // "张三,李四,王五"
-String names = StreamUtils.join(users, User::getName, "|");      // "张三|李四|王五"
+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
 Map<Long, String> merged = StreamUtils.merge(map1, map2, (v1, v2) -> v1 + v2);
 ```
 
@@ -184,36 +135,16 @@ Map<Long, String> merged = StreamUtils.merge(map1, map2, (v1, v2) -> v1 + v2);
 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.setWeight(item.getOrderNum());
     node.putExtra("icon", item.getIcon());
-    node.putExtra("path", item.getPath());
 });
 
 // 指定根节点 ID
-List<Tree<Long>> tree = TreeBuildUtils.build(list, 0L, (node, item) -> {
-    // ...
-});
-
-// 多根节点树
-List<Tree<Long>> tree = TreeBuildUtils.buildMultiRoot(
-    list,
-    Item::getId,
-    Item::getParentId,
-    (node, item) -> {
-        node.setId(item.getId());
-        node.setParentId(item.getParentId());
-        node.setName(item.getName());
-    }
-);
-
-// 获取叶子节点
-List<Tree<Long>> leaves = TreeBuildUtils.getLeafNodes(tree);
+List<Tree<Long>> tree = TreeBuildUtils.build(list, 0L, (node, item) -> { ... });
 ```
 
 ---
@@ -225,51 +156,29 @@ import org.dromara.common.core.utils.DateUtils;
 import org.dromara.common.core.enums.FormatsType;
 
 // 获取当前时间
-Date now = DateUtils.getNowDate();
-String date = DateUtils.getDate();      // "2026-01-24"
-String time = DateUtils.getTime();      // "2026-01-24 15:30:00"
+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"
+// 格式化 / 解析
+DateUtils.formatDateTime(date);
 DateUtils.parseDateToStr(FormatsType.YYYY_MM_DD_HH_MM, date);
-
-// 解析
-Date date = DateUtils.parseDate("2026-01-24");
 Date date = DateUtils.parseDateTime(FormatsType.YYYY_MM_DD_HH_MM_SS, "2026-01-24 15:30:00");
 
 // 时间差
 long days = DateUtils.difference(start, end, TimeUnit.DAYS);
 String diff = DateUtils.getDatePoor(endDate, startDate);  // "3天 2小时 30分钟"
-String diff = DateUtils.getTimeDifference(endDate, startDate);  // 智能省略0值
 
 // 日期范围校验
-DateUtils.validateDateRange(startDate, endDate, 30, TimeUnit.DAYS);  // 最大30天
+DateUtils.validateDateRange(startDate, endDate, 30, TimeUnit.DAYS);
 
 // 友好时间（仿微信）
-DateUtils.formatFriendlyTime(date);  // "刚刚" / "5分钟前" / "昨天 14:30" / "周三 10:00"
-
-// 时间段
-DateUtils.getTodayHour(date);  // "凌晨" / "上午" / "中午" / "下午" / "晚上"
+DateUtils.formatFriendlyTime(date);  // "刚刚" / "5分钟前" / "昨天 14:30"
 
 // 类型转换
 Date date = DateUtils.toDate(localDateTime);
-Date date = DateUtils.toDate(localDate);
-
-// 路径格式
-DateUtils.datePath();  // "2026/01/24"
 ```
 
-**FormatsType 枚举**:
-
-| 枚举值 | 格式 |
-|-------|------|
-| `YYYY_MM_DD` | yyyy-MM-dd |
-| `YYYY_MM_DD_HH_MM_SS` | yyyy-MM-dd HH:mm:ss |
-| `YYYY_MM_DD_HH_MM` | yyyy-MM-dd HH:mm |
-| `YYYYMMDD` | yyyyMMdd |
-| `YYYYMMDDHHMMSS` | yyyyMMddHHmmss |
-| `HH_MM_SS` | HH:mm:ss |
+**FormatsType 枚举**: `YYYY_MM_DD` | `YYYY_MM_DD_HH_MM_SS` | `YYYY_MM_DD_HH_MM` | `YYYYMMDD` | `YYYYMMDDHHMMSS` | `HH_MM_SS`
 
 ---
 
@@ -280,43 +189,27 @@ import org.dromara.common.core.utils.ValidatorUtils;
 import org.dromara.common.core.validate.AddGroup;
 import org.dromara.common.core.validate.EditGroup;
 
-// 手动校验（在 Service 层使用）
+// Service 层手动校验
 ValidatorUtils.validate(bo, AddGroup.class);
-ValidatorUtils.validate(bo, EditGroup.class);
 
-// Controller 层使用 @Validated（推荐）
+// Controller 层（推荐）
 @PostMapping
-public R<Void> add(@Validated(AddGroup.class) @RequestBody XxxBo bo) {
-    // ...
-}
+public R<Void> add(@Validated(AddGroup.class) @RequestBody XxxBo bo) { }
 
 @PutMapping
-public R<Void> edit(@Validated(EditGroup.class) @RequestBody XxxBo bo) {
-    // ...
-}
+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;
-
-    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
-    private String phone;
-
-    @Min(value = 0, message = "数量不能小于0")
-    @Max(value = 9999, message = "数量不能大于9999")
-    private Integer count;
 }
 ```
 
@@ -324,59 +217,35 @@ public class XxxBo extends BaseEntity {
 
 ## 7. Redis 缓存 - RedisUtils
 
+> 详细 API 见 `references/redis-utils-api.md`
+
 ```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.setCacheObject("key", value);
+RedisUtils.setCacheObject("key", value, Duration.ofMinutes(30));
 RedisUtils.getCacheObject("key");
 RedisUtils.deleteObject("key");
 RedisUtils.hasKey("key");
-RedisUtils.expire("key", 3600);  // 设置过期时间（秒）
 
 // 条件设置
-RedisUtils.setObjectIfAbsent("key", value, Duration.ofMinutes(5));  // 不存在才设置
-RedisUtils.setObjectIfExists("key", value, Duration.ofMinutes(5));  // 存在才设置
+RedisUtils.setObjectIfAbsent("key", value, Duration.ofMinutes(5));
 
-// List 操作
+// List / Set / Map 操作
 RedisUtils.setCacheList("listKey", dataList);
-RedisUtils.addCacheList("listKey", item);
-List<T> list = RedisUtils.getCacheList("listKey");
-List<T> range = RedisUtils.getCacheListRange("listKey", 0, 10);
-
-// Set 操作
-RedisUtils.setCacheSet("setKey", dataSet);
-RedisUtils.addCacheSet("setKey", item);
-Set<T> set = RedisUtils.getCacheSet("setKey");
-
-// Map/Hash 操作
 RedisUtils.setCacheMap("mapKey", dataMap);
 RedisUtils.setCacheMapValue("mapKey", "field", value);
-T value = RedisUtils.getCacheMapValue("mapKey", "field");
-Map<String, T> map = RedisUtils.getCacheMap("mapKey");
-RedisUtils.delCacheMapValue("mapKey", "field");
 
 // 原子操作
-RedisUtils.setAtomicValue("counter", 0);
-long val = RedisUtils.incrAtomicValue("counter");  // +1
-long val = RedisUtils.decrAtomicValue("counter");  // -1
-long val = RedisUtils.getAtomicValue("counter");
-
-// 批量操作
-Collection<String> keys = RedisUtils.keys("user:*");
-RedisUtils.deleteKeys("temp:*");
+long val = RedisUtils.incrAtomicValue("counter");
 
 // 发布订阅
 RedisUtils.publish("channel", message);
-RedisUtils.subscribe("channel", Message.class, msg -> {
-    // 处理消息
-});
+RedisUtils.subscribe("channel", Message.class, msg -> { });
 
 // 限流
 long remaining = RedisUtils.rateLimiter("api:user:list", RateType.OVERALL, 100, 60);
-// 每60秒最多100次，返回剩余次数，-1表示被限流
 ```
 
 ---
@@ -386,23 +255,14 @@ long remaining = RedisUtils.rateLimiter("api:user:list", RateType.OVERALL, 100,
 ```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 isSuperAdmin = LoginHelper.isSuperAdmin(userId);
-
-// 判断是否租户管理员
 boolean isTenantAdmin = LoginHelper.isTenantAdmin();
-boolean isTenantAdmin = LoginHelper.isTenantAdmin(rolePermission);
 ```
 
 ---
@@ -412,17 +272,9 @@ boolean isTenantAdmin = LoginHelper.isTenantAdmin(rolePermission);
 ```java
 import org.dromara.common.core.exception.ServiceException;
 
-// 抛出业务异常
 throw new ServiceException("用户不存在");
 throw new ServiceException("用户 {} 不存在", userId);
-
-// 条件判断
-if (user == null) {
-    throw new ServiceException("用户不存在");
-}
-
-// 带错误码
-throw new ServiceException("用户不存在", 500);
+throw new ServiceException("用户不存在", 500);  // 带错误码
 ```
 
 ---
@@ -432,7 +284,7 @@ throw new ServiceException("用户不存在", 500);
 ```java
 import org.dromara.common.excel.utils.ExcelUtil;
 
-// Controller 中导出
+// 导出
 @PostMapping("/export")
 public void export(XxxBo bo, HttpServletResponse response) {
     List<XxxVo> list = xxxService.queryList(bo);
@@ -443,7 +295,6 @@ public void export(XxxBo bo, HttpServletResponse response) {
 @PostMapping("/import")
 public R<Void> importData(@RequestPart("file") MultipartFile file) throws Exception {
     List<XxxVo> list = ExcelUtil.importExcel(file.getInputStream(), XxxVo.class);
-    // 处理导入数据
     return R.ok();
 }
 ```
@@ -452,19 +303,12 @@ public R<Void> importData(@RequestPart("file") MultipartFile file) throws Except
 
 ```java
 public class XxxVo implements Serializable {
-
     @ExcelProperty(value = "ID")
     private Long id;
 
-    @ExcelProperty(value = "名称")
-    private String name;
-
     @ExcelProperty(value = "状态", converter = ExcelDictConvert.class)
     @ExcelDictFormat(dictType = "sys_normal_disable")
     private String status;
-
-    @ExcelProperty(value = "创建时间")
-    private Date createTime;
 }
 ```
 
@@ -475,92 +319,24 @@ public class XxxVo implements Serializable {
 ```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);
 ```
 
 ---
 
-## 12. Hutool 常用工具
-
-```java
-import cn.hutool.core.collection.CollUtil;
-import cn.hutool.core.util.ObjectUtil;
-import cn.hutool.core.util.StrUtil;
-import cn.hutool.core.util.IdUtil;
-import cn.hutool.crypto.SecureUtil;
-
-// 集合判空
-CollUtil.isEmpty(list);
-CollUtil.isNotEmpty(list);
-CollUtil.newArrayList(1, 2, 3);
-CollUtil.newHashSet("a", "b");
-
-// 对象判空
-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
-String uuid = IdUtil.randomUUID();    // 标准 UUID
-String nanoId = IdUtil.nanoId();      // NanoID
-
-// 加密
-String md5 = SecureUtil.md5("password");
-String sha256 = SecureUtil.sha256("password");
-
-// Base64
-import cn.hutool.core.codec.Base64;
-String encoded = Base64.encode("data");
-String decoded = Base64.decodeStr(encoded);
-```
-
----
-
-## 常用正则表达式
-
-```java
-// 手机号
-String phoneReg = "^1[3-9]\\d{9}$";
-
-// 邮箱
-String emailReg = "^[\\w-]+(\\.[\\w-]+)*@[\\w-]+(\\.[\\w-]+)+$";
-
-// 身份证
-String idCardReg = "^[1-9]\\d{5}(19|20)\\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])\\d{3}[\\dXx]$";
-
-// URL
-String urlReg = "^https?://.+";
-
-// 中文
-String chineseReg = "^[\\u4e00-\\u9fa5]+$";
-```
-
----
-
 ## 工具类选择速查
 
 | 需求 | 推荐工具 | 说明 |
 |------|---------|------|
-| BO ↔ Entity ↔ VO 转换 | `MapstructUtils.convert()` | **必须使用** |
-| 字符串判空 | `StringUtils.isBlank()` | 推荐项目工具类 |
+| 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()` | 项目异常类 |
@@ -568,7 +344,6 @@ String chineseReg = "^[\\u4e00-\\u9fa5]+$";
 | Redis 缓存 | `RedisUtils.setCacheObject()` | 项目工具类 |
 | Excel 导出 | `ExcelUtil.exportExcel()` | 项目工具类 |
 | 生成 ID | `IdUtil.getSnowflakeNextId()` | Hutool |
-| MD5/SHA | `SecureUtil.md5()` | Hutool |
 
 ---
 
@@ -576,18 +351,12 @@ String chineseReg = "^[\\u4e00-\\u9fa5]+$";
 
 ```java
 // ❌ 禁止使用 BeanUtils
-BeanUtils.copyProperties(source, target);  // 禁止！
+BeanUtils.copyProperties(source, target);
 
 // ❌ 禁止使用 Map 传递业务数据
-public Map<String, Object> getXxx() { ... }  // 禁止！
+public Map<String, Object> getXxx() { ... }
 
 // ❌ 禁止手写 stream 转换（应使用 StreamUtils）
 list.stream().map(User::getId).collect(Collectors.toList());  // 不推荐
 StreamUtils.toList(list, User::getId);  // ✅ 推荐
-
-// ❌ 禁止使用完整类型引用
-public org.dromara.common.core.domain.R<XxxVo> getXxx()  // 禁止！
-// ✅ 正确：先 import，再使用短类名
-import org.dromara.common.core.domain.R;
-public R<XxxVo> getXxx()
 ```

package/.codex/skills/utils-toolkit/references/redis-utils-api.md

@@ -0,0 +1,56 @@
+# RedisUtils 完整 API
+
+```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");
+RedisUtils.expire("key", 3600);  // 设置过期时间（秒）
+
+// ========== 条件设置 ==========
+RedisUtils.setObjectIfAbsent("key", value, Duration.ofMinutes(5));  // 不存在才设置
+RedisUtils.setObjectIfExists("key", value, Duration.ofMinutes(5));  // 存在才设置
+
+// ========== List 操作 ==========
+RedisUtils.setCacheList("listKey", dataList);
+RedisUtils.addCacheList("listKey", item);
+List<T> list = RedisUtils.getCacheList("listKey");
+List<T> range = RedisUtils.getCacheListRange("listKey", 0, 10);
+
+// ========== Set 操作 ==========
+RedisUtils.setCacheSet("setKey", dataSet);
+RedisUtils.addCacheSet("setKey", item);
+Set<T> set = RedisUtils.getCacheSet("setKey");
+
+// ========== Map/Hash 操作 ==========
+RedisUtils.setCacheMap("mapKey", dataMap);
+RedisUtils.setCacheMapValue("mapKey", "field", value);
+T value = RedisUtils.getCacheMapValue("mapKey", "field");
+Map<String, T> map = RedisUtils.getCacheMap("mapKey");
+RedisUtils.delCacheMapValue("mapKey", "field");
+
+// ========== 原子操作 ==========
+RedisUtils.setAtomicValue("counter", 0);
+long val = RedisUtils.incrAtomicValue("counter");  // +1
+long val = RedisUtils.decrAtomicValue("counter");  // -1
+long val = RedisUtils.getAtomicValue("counter");
+
+// ========== 批量操作 ==========
+Collection<String> keys = RedisUtils.keys("user:*");
+RedisUtils.deleteKeys("temp:*");
+
+// ========== 发布订阅 ==========
+RedisUtils.publish("channel", message);
+RedisUtils.subscribe("channel", Message.class, msg -> {
+    // 处理消息
+});
+
+// ========== 限流 ==========
+long remaining = RedisUtils.rateLimiter("api:user:list", RateType.OVERALL, 100, 60);
+// 每60秒最多100次，返回剩余次数，-1表示被限流
+```