ai-engineering-init 1.3.3 → 1.4.0

package/.claude/skills/redis-cache/SKILL.md

@@ -9,16 +9,14 @@ description: |
   - 实现分布式锁
   - 实现接口限流
   - Redis发布订阅
-  - 缓存穿透/雪崩/击穿问题
   - 缓存key设计和命名
-  - 缓存过期时间设置
   - 缓存清理和刷新
 
-  触发词：Redis、缓存、Cache、@Cacheable、@CacheEvict、@CachePut、RedisUtils、CacheUtils、分布式锁、RLock、限流、RateLimiter、发布订阅、缓存穿透、缓存雪崩、缓存击穿、缓存key、缓存过期、缓存清理
+  触发词：Redis、缓存、Cache、@Cacheable、@CacheEvict、@CachePut、RedisUtils、CacheUtils、分布式锁、RLock、限流、RateLimiter、发布订阅、缓存key、缓存过期
 
   核心警告：
   - @Cacheable返回值不能使用不可变集合（List.of()、Set.of()、Map.of()）
-  - 分布式锁必须在finally中释放
+  - 分布式锁必须在finally中释放，且需注入RedissonClient（RedisUtils无getLock）
   - keys()和deleteKeys()会忽略租户隔离
 ---
 
@@ -34,7 +32,7 @@ description: |
 | 集合缓存 | `RedisUtils.setCacheList/Set/Map()` | List/Set/Map 操作 |
 | Spring Cache | `CacheUtils.get/put/evict()` | Spring Cache 封装 |
 | 缓存注解 | `@Cacheable/@CachePut/@CacheEvict` | 声明式缓存 |
-| 分布式锁 | Redisson 原生 | 需自行注入 RedissonClient |
+| 分布式锁 | `redissonClient.getLock()` | 需注入 RedissonClient |
 | 限流控制 | `RedisUtils.rateLimiter()` | 基于 Redisson |
 | 原子操作 | `RedisUtils.incrAtomicValue()` | 原子递增/递减 |
 | 发布订阅 | `RedisUtils.publish/subscribe()` | 消息通信 |
@@ -50,126 +48,51 @@ import org.dromara.common.redis.utils.RedisUtils;
 ### 1.1 基础缓存操作
 
 ```java
-// 永不过期
-RedisUtils.setCacheObject("user:123", userObj);
+RedisUtils.setCacheObject("user:123", userObj);                              // 永不过期
+RedisUtils.setCacheObject("user:123", userObj, Duration.ofMinutes(30));      // 带过期时间
+RedisUtils.setCacheObject("user:123", userObj, true);                        // 保留原有TTL（Redis 6.0+）
+boolean ok = RedisUtils.setObjectIfAbsent("user:123", userObj, Duration.ofMinutes(30));  // 不存在时设置
+boolean ok = RedisUtils.setObjectIfExists("user:123", userObj, Duration.ofMinutes(30));  // 存在时设置
 
-// 设置过期时间
-RedisUtils.setCacheObject("user:123", userObj, Duration.ofMinutes(30));
-
-// 保留原有TTL（需要Redis 6.0+）
-RedisUtils.setCacheObject("user:123", userObj, true);
-
-// 仅当key不存在时设置
-boolean success = RedisUtils.setObjectIfAbsent("user:123", userObj, Duration.ofMinutes(30));
-
-// 仅当key存在时设置
-boolean success = RedisUtils.setObjectIfExists("user:123", userObj, Duration.ofMinutes(30));
-
-// 获取缓存
-User user = RedisUtils.getCacheObject("user:123");
-
-// 获取剩余存活时间（毫秒）
-long ttl = RedisUtils.getTimeToLive("user:123");
-// 返回值：-1表示永不过期，-2表示key不存在
-
-// 删除单个缓存
-boolean deleted = RedisUtils.deleteObject("user:123");
-
-// 批量删除
-RedisUtils.deleteObject(Arrays.asList("user:123", "user:456"));
-
-// 检查缓存是否存在
-boolean exists = RedisUtils.isExistsObject("user:123");
-
-// 设置过期时间
-RedisUtils.expire("user:123", Duration.ofMinutes(30));
+User user = RedisUtils.getCacheObject("user:123");          // 获取
+long ttl = RedisUtils.getTimeToLive("user:123");            // TTL毫秒（-1永不过期，-2不存在）
+boolean deleted = RedisUtils.deleteObject("user:123");      // 删除
+RedisUtils.deleteObject(Arrays.asList("user:123", "user:456"));  // 批量删除
+boolean exists = RedisUtils.isExistsObject("user:123");     // 是否存在
+RedisUtils.expire("user:123", Duration.ofMinutes(30));      // 设置过期
 ```
 
 ### 1.2 集合操作
 
-#### List 操作
-
 ```java
-// 缓存List数据
-List<String> dataList = new ArrayList<>();
-dataList.add("item1");
-dataList.add("item2");
+// List
 RedisUtils.setCacheList("myList", dataList);
-
-// 向List追加单个数据
 RedisUtils.addCacheList("myList", "item3");
-
-// 获取完整List
 List<String> result = RedisUtils.getCacheList("myList");
-
-// 获取指定范围数据
 List<String> range = RedisUtils.getCacheListRange("myList", 0, 10);
-```
 
-#### Set 操作
-
-```java
-// 缓存Set数据
-Set<String> dataSet = new HashSet<>();
-dataSet.add("value1");
-dataSet.add("value2");
+// Set
 RedisUtils.setCacheSet("mySet", dataSet);
-
-// 向Set追加单个数据
 boolean added = RedisUtils.addCacheSet("mySet", "value3");
-
-// 获取Set数据
 Set<String> result = RedisUtils.getCacheSet("mySet");
-```
-
-#### Map 操作
 
-```java
-// 缓存Map数据
-Map<String, Object> dataMap = new HashMap<>();
-dataMap.put("key1", "value1");
-dataMap.put("key2", "value2");
+// Map
 RedisUtils.setCacheMap("myMap", dataMap);
-
-// 设置Map中的单个值
 RedisUtils.setCacheMapValue("myMap", "key3", "value3");
-
-// 获取Map中的单个值
 String value = RedisUtils.getCacheMapValue("myMap", "key1");
-
-// 获取完整Map
 Map<String, Object> result = RedisUtils.getCacheMap("myMap");
-
-// 获取Map的所有key
 Set<String> keys = RedisUtils.getCacheMapKeySet("myMap");
-
-// 删除Map中的单个值
-Object deleted = RedisUtils.delCacheMapValue("myMap", "key1");
-
-// 批量删除Map中的多个值
+RedisUtils.delCacheMapValue("myMap", "key1");
 RedisUtils.delMultiCacheMapValue("myMap", new HashSet<>(Arrays.asList("key1", "key2")));
-
-// 获取Map中的多个值
-Map<String, Object> values = RedisUtils.getMultiCacheMapValue("myMap",
-    new HashSet<>(Arrays.asList("key1", "key2")));
+Map<String, Object> values = RedisUtils.getMultiCacheMapValue("myMap", keySet);
 ```
 
 ### 1.3 发布订阅
 
 ```java
-// 发布消息到指定频道
 RedisUtils.publish("notification:channel", messageObj);
-
-// 发布消息并自定义处理
-RedisUtils.publish("notification:channel", messageObj, msg -> {
-    log.info("消息已发布: {}", msg);
-});
-
-// 订阅频道接收消息
-RedisUtils.subscribe("notification:channel", MessageDTO.class, msg -> {
-    log.info("收到消息: {}", msg);
-    // 处理消息逻辑
-});
+RedisUtils.publish("notification:channel", messageObj, msg -> { log.info("已发布: {}", msg); });
+RedisUtils.subscribe("notification:channel", MessageDTO.class, msg -> { /* 处理消息 */ });
 ```
 
 ### 1.4 限流控制
@@ -177,259 +100,95 @@ RedisUtils.subscribe("notification:channel", MessageDTO.class, msg -> {
 ```java
 import org.redisson.api.RateType;
 
-// 限流控制（默认无超时）
-// 允许每10秒内最多100个请求
-long remaining = RedisUtils.rateLimiter("api:limit:user:123",
-    RateType.OVERALL, 100, 10);
+// 每10秒最多100个请求
+long remaining = RedisUtils.rateLimiter("api:limit:user:123", RateType.OVERALL, 100, 10);
 if (remaining == -1) {
-    throw new ServiceException("请求过于频繁，请稍后再试");
+    throw new ServiceException("请求过于频繁");
 }
 
-// 限流控制（带超时）
-// 允许每10秒内最多100个请求，超时时间5秒
-long remaining = RedisUtils.rateLimiter("api:limit:user:123",
-    RateType.OVERALL, 100, 10, 5);
+// 带超时版本（5秒超时）
+long remaining = RedisUtils.rateLimiter("api:limit:user:123", RateType.OVERALL, 100, 10, 5);
 ```
 
 ### 1.5 原子操作
 
 ```java
-// 设置原子长整型值
 RedisUtils.setAtomicValue("counter:view", 0L);
-
-// 获取原子长整型值
 long value = RedisUtils.getAtomicValue("counter:view");
-
-// 原子递增
-long newValue = RedisUtils.incrAtomicValue("counter:view");
-
-// 原子递减
-long newValue = RedisUtils.decrAtomicValue("counter:view");
+long newVal = RedisUtils.incrAtomicValue("counter:view");
+long newVal = RedisUtils.decrAtomicValue("counter:view");
 ```
 
 ### 1.6 Key 操作
 
 ```java
-// 获取匹配模式的所有key（注意：会忽略租户隔离）
+// ⚠️ keys() 和 deleteKeys() 会忽略租户隔离
 Collection<String> keys = RedisUtils.keys("user:*");
 
-// 通过扫描参数获取key列表
-KeysScanOptions options = KeysScanOptions.defaults()
-    .pattern("user:*")
-    .chunkSize(1000)
-    .limit(100);
+KeysScanOptions options = KeysScanOptions.defaults().pattern("user:*").chunkSize(1000).limit(100);
 Collection<String> keys = RedisUtils.keys(options);
 
-// 按模式批量删除key（注意：会忽略租户隔离）
 RedisUtils.deleteKeys("temp:*");
-
-// 检查key是否存在
 Boolean exists = RedisUtils.hasKey("user:123");
 ```
 
-### 1.7 分布式锁（需自行注入 RedissonClient）
-
-> ⚠️ **注意**：`RedisUtils` 不提供 `getLock()` 方法，需要直接注入 `RedissonClient` 使用。
-
-```java
-import org.redisson.api.RLock;
-import org.redisson.api.RedissonClient;
-
-@Service
-@RequiredArgsConstructor
-public class OrderServiceImpl implements IOrderService {
-
-    private final RedissonClient redissonClient;  // 直接注入
-
-    public void processOrder(Long orderId) {
-        // 获取锁对象
-        RLock lock = redissonClient.getLock("lock:order:" + orderId);
-
-        try {
-            // 尝试加锁，最多等待10秒，锁定30秒后自动释放
-            boolean locked = lock.tryLock(10, 30, TimeUnit.SECONDS);
-            if (locked) {
-                try {
-                    // 执行业务逻辑
-                    doProcess(orderId);
-                } finally {
-                    // 释放锁（必须在finally中！）
-                    lock.unlock();
-                }
-            } else {
-                throw new ServiceException("获取锁失败，请稍后重试");
-            }
-        } catch (InterruptedException e) {
-            Thread.currentThread().interrupt();
-            throw new ServiceException("获取锁被中断");
-        }
-    }
-}
-```
-
-### 1.8 监听机制
+### 1.7 监听机制
 
-```java
-import org.redisson.api.listener.ExpiredObjectListener;
-import org.redisson.api.listener.DeletedObjectListener;
-
-// 注册过期监听器（需要开启Redis的notify-keyspace-events配置）
-RedisUtils.addObjectListener("user:123", (ExpiredObjectListener) name -> {
-    log.info("缓存已过期: {}", name);
-});
-
-// 注册删除监听器
-RedisUtils.addObjectListener("user:123", (DeletedObjectListener) name -> {
-    log.info("缓存已删除: {}", name);
-});
-
-// 注册List/Set/Map监听器（同样使用具体子接口）
-RedisUtils.addListListener("myList", (ExpiredObjectListener) name -> { ... });
-RedisUtils.addSetListener("mySet", (DeletedObjectListener) name -> { ... });
-RedisUtils.addMapListener("myMap", (ExpiredObjectListener) name -> { ... });
-```
+详见 [references/listeners.md](references/listeners.md)
 
 ---
 
 ## 二、CacheUtils 工具类
 
-CacheUtils 提供了统一的 Spring Cache 操作接口。
-
 ```java
 import org.dromara.common.redis.utils.CacheUtils;
-```
-
-### 2.1 基本操作
-
-```java
-// 保存缓存值
-CacheUtils.put("userCache", "user:123", userObj);
 
-// 获取缓存值
-User user = CacheUtils.get("userCache", "user:123");
-
-// 删除指定缓存项
-CacheUtils.evict("userCache", "user:123");
-
-// 清空指定缓存组的所有数据
-CacheUtils.clear("userCache");
-```
-
-### 2.2 使用场景
-
-```java
-@Service
-public class UserServiceImpl implements IUserService {
-
-    public User getUserById(Long userId) {
-        // 先从缓存获取
-        User user = CacheUtils.get(CacheNames.SYS_USER_NAME, userId);
-        if (user != null) {
-            return user;
-        }
-
-        // 缓存未命中，从数据库查询
-        user = userMapper.selectById(userId);
-
-        // 存入缓存
-        if (user != null) {
-            CacheUtils.put(CacheNames.SYS_USER_NAME, userId, user);
-        }
-
-        return user;
-    }
-
-    public void updateUser(User user) {
-        // 更新数据库
-        userMapper.updateById(user);
-
-        // 清除缓存
-        CacheUtils.evict(CacheNames.SYS_USER_NAME, user.getUserId());
-    }
-}
+CacheUtils.put("userCache", "user:123", userObj);       // 保存
+User user = CacheUtils.get("userCache", "user:123");     // 获取
+CacheUtils.evict("userCache", "user:123");               // 删除
+CacheUtils.clear("userCache");                           // 清空整组
 ```
 
 ---
 
 ## 三、CacheNames 缓存名称常量
 
-> 位置：`ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/constant/CacheNames.java`
+> 位置：`ruoyi-common/ruoyi-common-core/.../constant/CacheNames.java`
 
-### 3.1 命名格式
+### 命名格式
 
 ```
 cacheNames#ttl#maxIdleTime#maxSize#local
-
-- ttl: 过期时间（0表示不过期，默认0）
-- maxIdleTime: 最大空闲时间（LRU清理，0表示不检测，默认0）
-- maxSize: 最大长度（LRU清理，0表示无限，默认0）
+- ttl: 过期时间（0=不过期，默认0）
+- maxIdleTime: 最大空闲时间（0=不检测，默认0）
+- maxSize: 最大条数（0=无限，默认0）
 - local: 本地缓存（1开启，0关闭，默认1）
 ```
 
-### 3.2 格式示例
-
 ```java
-// 60秒过期
-"test#60s"
-
-// 不过期，60秒空闲清理
-"test#0#60s"
-
-// 不过期，1分钟空闲清理，最大1000条
-"test#0#1m#1000"
-
-// 1小时过期，不检测空闲，最大500条
-"test#1h#0#500"
-
-// 1小时过期，不检测空闲，最大500条，关闭本地缓存
-"test#1h#0#500#0"
+"test#60s"                // 60秒过期
+"test#0#60s"              // 不过期，60秒空闲清理
+"test#0#1m#1000"          // 不过期，1分钟空闲，最大1000条
+"test#1h#0#500#0"         // 1小时过期，最大500条，关闭本地缓存
 ```
 
-### 3.3 已定义常量
+### 已定义常量
 
 ```java
 public interface CacheNames {
-
-    /** 演示案例：60秒过期，10分钟空闲，最大20条 */
     String DEMO_CACHE = "demo:cache#60s#10m#20";
-
-    /** 系统配置 */
     String SYS_CONFIG = "sys_config";
-
-    /** 数据字典 */
     String SYS_DICT = "sys_dict";
-
-    /** 数据字典类型 */
     String SYS_DICT_TYPE = "sys_dict_type";
-
-    /** 租户（30天过期，全局Key） */
     String SYS_TENANT = GlobalConstants.GLOBAL_REDIS_KEY + "sys_tenant#30d";
-
-    /** 客户端（30天过期，全局Key） */
     String SYS_CLIENT = GlobalConstants.GLOBAL_REDIS_KEY + "sys_client#30d";
-
-    /** 用户账户（30天过期） */
     String SYS_USER_NAME = "sys_user_name#30d";
-
-    /** 用户名称（30天过期） */
     String SYS_NICKNAME = "sys_nickname#30d";
-
-    /** 部门（30天过期） */
     String SYS_DEPT = "sys_dept#30d";
-
-    /** OSS内容（30天过期） */
     String SYS_OSS = "sys_oss#30d";
-
-    /** 角色自定义权限（30天过期） */
     String SYS_ROLE_CUSTOM = "sys_role_custom#30d";
-
-    /** 部门及以下权限（30天过期） */
     String SYS_DEPT_AND_CHILD = "sys_dept_and_child#30d";
-
-    /** OSS配置（全局Key） */
     String SYS_OSS_CONFIG = GlobalConstants.GLOBAL_REDIS_KEY + "sys_oss_config";
-
-    /** 在线用户 */
     String ONLINE_TOKEN = "online_tokens";
 }
 ```
@@ -438,14 +197,9 @@ public interface CacheNames {
 
 ## 四、缓存注解使用规范
 
-### 4.1 @Cacheable - 查询缓存
+### @Cacheable - 查询缓存
 
 ```java
-import org.springframework.cache.annotation.Cacheable;
-
-/**
- * 根据字典类型查询字典数据
- */
 @Cacheable(cacheNames = CacheNames.SYS_DICT, key = "#dictType")
 @Override
 public List<SysDictDataVo> listDictDataByType(String dictType) {
@@ -454,112 +208,65 @@ public List<SysDictDataVo> listDictDataByType(String dictType) {
     }
     List<SysDictData> dictDataList = dictDataMapper.selectByType(dictType);
     if (CollUtil.isEmpty(dictDataList)) {
-        return Collections.emptyList();
+        return Collections.emptyList();  // 返回空列表防止缓存穿透
     }
     return MapstructUtils.convert(dictDataList, SysDictDataVo.class);
 }
 ```
 
-### 4.2 @CachePut - 更新缓存
+### @CachePut / @CacheEvict
 
 ```java
-import org.springframework.cache.annotation.CachePut;
-
-/**
- * 新增字典类型
- */
 @CachePut(cacheNames = CacheNames.SYS_DICT, key = "#bo.dictType")
-@Override
-public List<SysDictDataVo> insertDictType(SysDictTypeBo bo) {
-    SysDictType dictType = MapstructUtils.convert(bo, SysDictType.class);
-    boolean success = dictTypeMapper.insert(dictType) > 0;
-    if (success) {
-        // 新增类型下无数据，返回空列表防止缓存穿透
-        return Collections.emptyList();
-    }
-    throw new ServiceException("新增字典类型失败");
-}
-```
+public List<SysDictDataVo> insertDictType(SysDictTypeBo bo) { ... }
 
-### 4.3 @CacheEvict - 清除缓存
-
-```java
-import org.springframework.cache.annotation.CacheEvict;
-
-// 清除单个缓存
 @CacheEvict(cacheNames = CacheNames.SYS_DICT, key = "#dictType")
-public void deleteDictType(String dictType) {
-    dictTypeMapper.deleteByDictType(dictType);
-}
+public void deleteDictType(String dictType) { ... }
 
-// 清除整个缓存组
 @CacheEvict(cacheNames = CacheNames.SYS_DICT, allEntries = true)
-public void clearAllDictCache() {
-    // 清空所有字典缓存
-}
+public void clearAllDictCache() { ... }
 ```
 
-### 4.4 ⚠️ 重要：返回值不能使用不可变集合
+### 返回值禁止使用不可变集合
 
 ```java
-// ❌ 错误：使用 List.of() 会导致缓存序列化失败
-@Cacheable(cacheNames = CacheNames.SYS_DICT, key = "#dictType")
-public List<SysDictDataVo> listDictDataByType(String dictType) {
-    return List.of(data1, data2);  // ❌ 禁止！
-}
-
-// ❌ 错误：使用 Set.of()
-@Cacheable(cacheNames = CacheNames.SYS_USER_NAME, key = "#userId")
-public Set<String> getUserRoles(Long userId) {
-    return Set.of("admin", "user");  // ❌ 禁止！
-}
-
-// ❌ 错误：使用 Map.of()
-@Cacheable(cacheNames = CacheNames.SYS_CONFIG, key = "#configKey")
-public Map<String, Object> getConfig(String configKey) {
-    return Map.of("key1", "value1");  // ❌ 禁止！
-}
+// ❌ 禁止！@Cacheable 返回值序列化失败
+return List.of(data1, data2);
+return Set.of("admin", "user");
+return Map.of("key1", "value1");
 
 // ✅ 正确：使用可变集合
-@Cacheable(cacheNames = CacheNames.SYS_DICT, key = "#dictType")
-public List<SysDictDataVo> listDictDataByType(String dictType) {
-    List<SysDictDataVo> result = new ArrayList<>();
-    result.add(data1);
-    result.add(data2);
-    return result;  // ✅ 正确
-}
+List<SysDictDataVo> result = new ArrayList<>();
+result.add(data1);
+return result;
 ```
 
 ---
 
-## 五、分布式锁最佳实践
-
-> ⚠️ **重要**：`RedisUtils` 不提供分布式锁方法，需要直接注入 `RedissonClient` 使用。
+## 五、分布式锁
 
-### 5.1 防止重复提交
+> RedisUtils **不提供** `getLock()`，需直接注入 `RedissonClient`。
 
 ```java
 @Service
 @RequiredArgsConstructor
 public class OrderServiceImpl implements IOrderService {
 
-    private final RedissonClient redissonClient;  // 直接注入
-    private final OrderMapper orderMapper;
+    private final RedissonClient redissonClient;
 
     public void submitOrder(OrderBo orderBo) {
         String lockKey = "lock:submit:order:" + LoginHelper.getUserId();
-        RLock lock = redissonClient.getLock(lockKey);  // ✅ 使用 redissonClient
+        RLock lock = redissonClient.getLock(lockKey);
 
         try {
             boolean locked = lock.tryLock(3, 10, TimeUnit.SECONDS);
             if (!locked) {
                 throw new ServiceException("请勿重复提交订单");
             }
-
             try {
                 orderMapper.insert(orderBo);
             } finally {
-                lock.unlock();
+                lock.unlock();  // 必须在 finally 中释放
             }
         } catch (InterruptedException e) {
             Thread.currentThread().interrupt();
@@ -569,271 +276,58 @@ public class OrderServiceImpl implements IOrderService {
 }
 ```
 
-### 5.2 库存扣减
-
-```java
-@Service
-@RequiredArgsConstructor
-public class GoodsServiceImpl implements IGoodsService {
-
-    private final RedissonClient redissonClient;  // 直接注入
-    private final GoodsMapper goodsMapper;
-
-    public void deductStock(Long goodsId, Integer quantity) {
-        String lockKey = "lock:stock:" + goodsId;
-        RLock lock = redissonClient.getLock(lockKey);  // ✅ 使用 redissonClient
-
-        try {
-            boolean locked = lock.tryLock(5, 30, TimeUnit.SECONDS);
-            if (!locked) {
-                throw new ServiceException("系统繁忙，请稍后重试");
-            }
-
-            try {
-                Goods goods = goodsMapper.selectById(goodsId);
-                if (goods.getStock() < quantity) {
-                    throw new ServiceException("库存不足");
-                }
-                goods.setStock(goods.getStock() - quantity);
-                goodsMapper.updateById(goods);
-            } finally {
-                lock.unlock();
-            }
-        } catch (InterruptedException e) {
-            Thread.currentThread().interrupt();
-            throw new ServiceException("库存扣减被中断");
-        }
-    }
-}
-```
-
-### 5.3 分布式锁规范
-
-1. **锁的粒度要细**：锁的范围越小越好，避免锁住不必要的代码
-2. **设置合理的超时时间**：根据业务执行时间设置，避免死锁
-3. **必须在 finally 中释放锁**：确保锁一定会被释放
-4. **处理 InterruptedException**：正确处理中断异常
-5. **锁 key 要有业务含义**：便于排查问题
-
 ---
 
 ## 六、缓存 Key 命名规范
 
-### 6.1 命名格式
-
-```
-{业务模块}:{功能}:{具体标识}
 ```
+格式：{业务模块}:{功能}:{具体标识}
 
-### 6.2 命名示例
-
-```java
-// 用户缓存
-"user:info:123"              // 用户信息
-"user:roles:123"             // 用户角色
-"user:permissions:123"       // 用户权限
-
-// 字典缓存
-"dict:data:sys_user_sex"     // 字典数据
-"dict:type:sys_user_sex"     // 字典类型
-
-// 订单缓存
-"order:info:20240101001"     // 订单信息
-"order:status:20240101001"   // 订单状态
-
-// 分布式锁
-"lock:order:20240101001"     // 订单锁
-"lock:stock:123"             // 库存锁
-"lock:submit:order:456"      // 提交锁
-
-// 限流
-"limit:api:user:123"         // 用户API限流
-"limit:sms:18888888888"      // 短信限流
+示例：
+user:info:123              user:roles:123            user:permissions:123
+dict:data:sys_user_sex     order:info:20240101001    order:status:20240101001
+lock:order:20240101001     lock:stock:123            lock:submit:order:456
+limit:api:user:123         limit:sms:18888888888
 ```
 
 ---
 
-## 七、常见问题解决方案
-
-### 7.1 缓存穿透
-
-**问题**：查询一个不存在的数据，缓存和数据库都没有，导致每次请求都打到数据库。
+## 七、租户隔离注意
 
 ```java
-@Cacheable(cacheNames = CacheNames.SYS_DICT, key = "#dictType")
-public List<SysDictDataVo> listDictDataByType(String dictType) {
-    List<SysDictData> dictDataList = dictDataMapper.selectByType(dictType);
-    if (CollUtil.isEmpty(dictDataList)) {
-        // 返回空列表而不是null，防止缓存穿透
-        return Collections.emptyList();
-    }
-    return MapstructUtils.convert(dictDataList, SysDictDataVo.class);
-}
-```
-
-### 7.2 缓存雪崩
-
-**问题**：大量缓存同时过期，导致请求全部打到数据库。
-
-```java
-// 设置随机过期时间，避免同时过期
-long baseTime = 30 * 60; // 30分钟
-long randomTime = ThreadLocalRandom.current().nextLong(5 * 60); // 随机0-5分钟
-Duration duration = Duration.ofSeconds(baseTime + randomTime);
-RedisUtils.setCacheObject("user:info:" + userId, userInfo, duration);
-```
-
-### 7.3 缓存击穿
-
-**问题**：热点数据过期瞬间，大量请求同时打到数据库。
-
-```java
-@Service
-@RequiredArgsConstructor
-public class UserServiceImpl implements IUserService {
-
-    private final RedissonClient redissonClient;  // 直接注入
-    private final UserMapper userMapper;
-
-    public User getUserById(Long userId) {
-        String cacheKey = "user:info:" + userId;
-
-        // 先从缓存获取
-        User user = RedisUtils.getCacheObject(cacheKey);
-        if (user != null) {
-            return user;
-        }
-
-        // 缓存未命中，使用分布式锁
-        String lockKey = "lock:user:" + userId;
-        RLock lock = redissonClient.getLock(lockKey);  // ✅ 使用 redissonClient
-
-        try {
-            boolean locked = lock.tryLock(3, 10, TimeUnit.SECONDS);
-            if (locked) {
-                try {
-                    // 双重检查
-                    user = RedisUtils.getCacheObject(cacheKey);
-                    if (user != null) {
-                        return user;
-                    }
-
-                    // 从数据库查询
-                    user = userMapper.selectById(userId);
-
-                    // 存入缓存
-                    if (user != null) {
-                        RedisUtils.setCacheObject(cacheKey, user, Duration.ofMinutes(30));
-                    }
-
-                    return user;
-                } finally {
-                    lock.unlock();
-                }
-            }
-        } catch (InterruptedException e) {
-            Thread.currentThread().interrupt();
-        }
-
-        // 获取锁失败，直接查询数据库
-        return userMapper.selectById(userId);
-    }
-}
-```
-
-### 7.4 缓存与数据库一致性
-
-```java
-// 方案1：先更新数据库，再删除缓存（推荐）
-@Transactional(rollbackFor = Exception.class)
-public void updateUser(UserBo userBo) {
-    User user = MapstructUtils.convert(userBo, User.class);
-    userMapper.updateById(user);
-
-    // 删除缓存
-    RedisUtils.deleteObject("user:info:" + user.getUserId());
-}
-
-// 方案2：使用 @CachePut 更新缓存
-@CachePut(cacheNames = CacheNames.SYS_USER_NAME, key = "#result.userId")
-@Transactional(rollbackFor = Exception.class)
-public UserVo updateUser(UserBo userBo) {
-    User user = MapstructUtils.convert(userBo, User.class);
-    userMapper.updateById(user);
-
-    User updatedUser = userMapper.selectById(user.getUserId());
-    return MapstructUtils.convert(updatedUser, UserVo.class);
-}
-```
-
-### 7.5 租户隔离问题
-
-**问题**：`RedisUtils.keys()` 和 `RedisUtils.deleteKeys()` 会忽略租户隔离。
-
-```java
-// 手动拼接租户ID
+// ⚠️ keys() 和 deleteKeys() 会忽略租户隔离，需手动拼接
 String tenantId = LoginHelper.getTenantId();
-String pattern = tenantId + ":user:*";
-Collection<String> keys = RedisUtils.keys(pattern);
+Collection<String> keys = RedisUtils.keys(tenantId + ":user:*");
 
-// 或者使用 CacheUtils，它会自动处理租户隔离
+// CacheUtils 会自动处理租户隔离
 CacheUtils.clear(CacheNames.SYS_USER_NAME);
 ```
 
 ---
 
-## 八、核心文件位置
+## 八、注意事项速查
 
-| 文件 | 位置 |
-|------|------|
-| RedisUtils | `ruoyi-common/ruoyi-common-redis/src/main/java/org/dromara/common/redis/utils/RedisUtils.java` |
-| CacheUtils | `ruoyi-common/ruoyi-common-redis/src/main/java/org/dromara/common/redis/utils/CacheUtils.java` |
-| CacheNames | `ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/constant/CacheNames.java` |
-| GlobalConstants | `ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/constant/GlobalConstants.java` |
+1. **@Cacheable 返回值不能使用不可变集合**（List.of()、Set.of()、Map.of()）
+2. **分布式锁必须在 finally 中释放**
+3. **keys() 和 deleteKeys() 会忽略租户隔离**
+4. **返回空列表而不是 null**，防止缓存穿透
+5. **设置随机过期时间偏移**，避免缓存雪崩
+6. **热点数据用分布式锁 + 双重检查**，防止缓存击穿
 
 ---
 
-## 九、快速参考
+## 九、核心文件位置
 
-### 9.1 常用操作速查
-
-```java
-// 基础缓存
-RedisUtils.setCacheObject(key, value);                          // 存储
-RedisUtils.setCacheObject(key, value, Duration.ofMinutes(30));  // 存储并设置过期时间
-Object value = RedisUtils.getCacheObject(key);                  // 获取
-RedisUtils.deleteObject(key);                                   // 删除
-boolean exists = RedisUtils.isExistsObject(key);                // 检查是否存在
-
-// 分布式锁（需注入 RedissonClient，RedisUtils 不提供 getLock）
-RLock lock = redissonClient.getLock(lockKey);
-boolean locked = lock.tryLock(10, 30, TimeUnit.SECONDS);
-lock.unlock();  // 必须在 finally 中释放
-
-// 限流
-long remaining = RedisUtils.rateLimiter(key, RateType.OVERALL, 100, 10);
-
-// 缓存注解
-@Cacheable(cacheNames = CacheNames.SYS_DICT, key = "#dictType")  // 查询缓存
-@CachePut(cacheNames = CacheNames.SYS_DICT, key = "#bo.dictType") // 更新缓存
-@CacheEvict(cacheNames = CacheNames.SYS_DICT, key = "#dictType")  // 清除缓存
-```
-
-### 9.2 注意事项
-
-1. ⚠️ **@Cacheable 返回值不能使用不可变集合**（List.of()、Set.of()、Map.of()）
-2. ⚠️ **分布式锁必须在 finally 中释放**
-3. ⚠️ **keys() 和 deleteKeys() 会忽略租户隔离**，需要手动拼接租户ID
-4. ⚠️ **缓存 key 要有业务含义**，便于排查问题
-5. ⚠️ **设置合理的过期时间**，避免缓存雪崩
-6. ⚠️ **返回空列表而不是 null**，防止缓存穿透
+| 文件 | 位置 |
+|------|------|
+| RedisUtils | `ruoyi-common/ruoyi-common-redis/.../utils/RedisUtils.java` |
+| CacheUtils | `ruoyi-common/ruoyi-common-redis/.../utils/CacheUtils.java` |
+| CacheNames | `ruoyi-common/ruoyi-common-core/.../constant/CacheNames.java` |
+| GlobalConstants | `ruoyi-common/ruoyi-common-core/.../constant/GlobalConstants.java` |
 
 ---
 
 ## 多项目适配说明
 
-
-## 注意事项
-
 - 如果需要 leniu-tengyun-core 项目的 Redis 开发规范，请使用 `leniu-redis-cache` skill
 - leniu-tengyun-core 的 RedisUtil 工具类方法名与 RuoYi-Vue-Plus 的 RedisUtils 不同