@llryiop/avatar-boot-cli 1.0.0 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-redis/SKILL.md

@@ -1,586 +1,62 @@
 ---
 name: avatar-boot-starter-redis
-description: 当涉及 Redis、缓存、Redisson、分布式锁 相关功能时使用此技能 - 为 Spring Boot 3.5.3 应用提供基于 Redisson 3.40.2 的 Redis 缓存与分布式锁能力，包含自动配置、连接池管理、Spring Cache 集成。
+description: Avatar Boot Redis 模块使用指南。当用户询问 Redis 缓存操作、分布式锁、限流器、布隆过滤器、String/Hash/Set/ZSet 数据结构操作，或需要接入 avatar-boot-starter-redis 时触发。
 ---
 
-Avatar Boot 的 Redis 集成模块，基于 Redisson 3.40.2 提供开箱即用的缓存、分布式锁和数据结构操作能力。
+# Avatar Boot Starter Redis 使用指南
 
-## 功能特性
+你是 Avatar Boot Redis 模块的使用顾问与开发助手。
 
-- ✅ **自动配置** - 基于 Spring Boot 自动配置机制，自动装配 RedisTemplate 和 Redisson 客户端
-- ✅ **Redisson 集成** - 内置 Redisson 3.40.2，提供分布式锁、信号量等高级功能
-- ✅ **Spring Cache 支持** - 无缝集成 Spring Cache 抽象，支持 @Cacheable、@CacheEvict、@CachePut
-- ✅ **连接池管理** - 基于 Lettuce 连接池，支持高并发场景
-- ✅ **序列化可配置** - 支持多种序列化方式，推荐 Jackson2JsonRedisSerializer
-- ✅ **完善的监控** - 集成 Micrometer 指标，便于监控 Redis 连接状态
+## 交互流程（必须遵守）
 
-## 快速开始
+**每次被触发时，先通过 AskUserQuestion 工具询问用户意图：**
 
-### 1. 添加依赖
+问题："您好！我是 Avatar Boot Redis 模块助手，请问您需要哪方面的帮助？"
+选项：
+1. **快速接入** - 添加依赖、@EnableRedis、配置连接
+2. **数据结构操作** - String/Hash/Set/ZSet 操作示例
+3. **缓存操作** - RedisCacheClient 使用、批量删除
+4. **分布式锁** - RedissonLockClient 加锁/解锁
+5. **限流与布隆过滤器** - 令牌桶/滑动窗口限流、布隆过滤器去重
 
-在项目的 `pom.xml` 中添加依赖：
+**根据用户选择，用 Read 工具按下方「文档读取路由」加载对应文档，然后给出具体指导。**
 
-```xml
-<dependency>
-    <groupId>com.iflytek.avatar.boot</groupId>
-    <artifactId>avatar-boot-starter-redis</artifactId>
-</dependency>
-```
-
-> 版本由 Avatar Boot BOM 统一管理，无需指定 version。
-
-### 2. 配置文件
-
-在 `application.yml` 中添加 Redis 连接配置：
-
-```yaml
-spring:
-  data:
-    redis:
-      host: localhost
-      port: 6379
-      password: your-password  # 无密码可省略
-      database: 0
-      timeout: 3000ms
-      lettuce:
-        pool:
-          max-active: 16    # 最大连接数（默认 8）
-          max-idle: 8       # 最大空闲连接数（默认 8）
-          min-idle: 2       # 最小空闲连接数（默认 0）
-          max-wait: 3000ms  # 获取连接最大等待时间
-```
-
-### 3. 基本使用
-
-注入 `StringRedisTemplate` 或 `RedisTemplate` 即可操作 Redis：
-
-```java
-package com.example.service;
-
-import lombok.RequiredArgsConstructor;
-import lombok.extern.slf4j.Slf4j;
-import org.springframework.data.redis.core.StringRedisTemplate;
-import org.springframework.stereotype.Service;
-
-import java.util.concurrent.TimeUnit;
-
-@Slf4j
-@Service
-@RequiredArgsConstructor
-public class CacheService {
-
-    private final StringRedisTemplate stringRedisTemplate;
-
-    /**
-     * 设置缓存（必须设置过期时间）
-     */
-    public void setCache(String key, String value, long timeout, TimeUnit unit) {
-        stringRedisTemplate.opsForValue().set(key, value, timeout, unit);
-    }
-
-    /**
-     * 获取缓存
-     */
-    public String getCache(String key) {
-        return stringRedisTemplate.opsForValue().get(key);
-    }
-
-    /**
-     * 删除缓存
-     */
-    public Boolean deleteCache(String key) {
-        return stringRedisTemplate.delete(key);
-    }
-}
-```
-
-## Redisson 配置
-
-### 单节点模式
-
-通过 `application.yml` 配置 Redisson：
-
-```yaml
-spring:
-  data:
-    redis:
-      host: localhost
-      port: 6379
-      password: your-password
-      redisson:
-        config: |
-          singleServerConfig:
-            address: "redis://localhost:6379"
-            password: "your-password"
-            connectionMinimumIdleSize: 4
-            connectionPoolSize: 16
-            idleConnectionTimeout: 10000
-            connectTimeout: 10000
-            timeout: 3000
-            retryAttempts: 3
-            retryInterval: 1500
-```
-
-### 集群模式
-
-```yaml
-spring:
-  data:
-    redis:
-      redisson:
-        config: |
-          clusterServersConfig:
-            nodeAddresses:
-              - "redis://node1:6379"
-              - "redis://node2:6379"
-              - "redis://node3:6379"
-            password: "your-password"
-            masterConnectionMinimumIdleSize: 4
-            masterConnectionPoolSize: 16
-            slaveConnectionMinimumIdleSize: 4
-            slaveConnectionPoolSize: 16
-```
-
-也可以通过独立的 `redisson.yaml` 文件配置：
-
-```yaml
-# resources/redisson.yaml
-singleServerConfig:
-  address: "redis://${REDIS_HOST:localhost}:${REDIS_PORT:6379}"
-  password: "${REDIS_PASSWORD:}"
-  connectionMinimumIdleSize: 4
-  connectionPoolSize: 16
-```
-
-然后在 `application.yml` 中引用：
-
-```yaml
-spring:
-  data:
-    redis:
-      redisson:
-        file: classpath:redisson.yaml
-```
-
-## RedisTemplate 使用示例
-
-### 自定义 RedisTemplate 序列化
-
-```java
-package com.example.config;
-
-import com.fasterxml.jackson.annotation.JsonAutoDetect;
-import com.fasterxml.jackson.annotation.PropertyAccessor;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.databind.jsontype.impl.LaissezFaireSubTypeValidator;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-import org.springframework.data.redis.connection.RedisConnectionFactory;
-import org.springframework.data.redis.core.RedisTemplate;
-import org.springframework.data.redis.serializer.Jackson2JsonRedisSerializer;
-import org.springframework.data.redis.serializer.StringRedisSerializer;
-
-@Configuration
-public class RedisConfig {
-
-    @Bean
-    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
-        RedisTemplate<String, Object> template = new RedisTemplate<>();
-        template.setConnectionFactory(factory);
-
-        // Key 使用 String 序列化
-        StringRedisSerializer stringSerializer = new StringRedisSerializer();
-        template.setKeySerializer(stringSerializer);
-        template.setHashKeySerializer(stringSerializer);
-
-        // Value 使用 Jackson 序列化
-        ObjectMapper om = new ObjectMapper();
-        om.setVisibility(PropertyAccessor.ALL, JsonAutoDetect.Visibility.ANY);
-        om.activateDefaultTyping(LaissezFaireSubTypeValidator.instance,
-                ObjectMapper.DefaultTyping.NON_FINAL);
-        Jackson2JsonRedisSerializer<Object> jacksonSerializer =
-                new Jackson2JsonRedisSerializer<>(om, Object.class);
-
-        template.setValueSerializer(jacksonSerializer);
-        template.setHashValueSerializer(jacksonSerializer);
-        template.afterPropertiesSet();
-        return template;
-    }
-}
-```
-
-### 操作各种数据结构
-
-```java
-@Service
-@RequiredArgsConstructor
-public class RedisDataService {
-
-    private final RedisTemplate<String, Object> redisTemplate;
-
-    // String 操作
-    public void stringOps() {
-        redisTemplate.opsForValue().set("avatar:user:123", userObj, 30, TimeUnit.MINUTES);
-        Object user = redisTemplate.opsForValue().get("avatar:user:123");
-    }
-
-    // Hash 操作
-    public void hashOps() {
-        redisTemplate.opsForHash().put("avatar:user:profile:123", "name", "张三");
-        redisTemplate.opsForHash().put("avatar:user:profile:123", "age", 25);
-        Object name = redisTemplate.opsForHash().get("avatar:user:profile:123", "name");
-    }
-
-    // List 操作
-    public void listOps() {
-        redisTemplate.opsForList().rightPush("avatar:queue:tasks", task);
-        Object task = redisTemplate.opsForList().leftPop("avatar:queue:tasks");
-    }
-
-    // Set 操作
-    public void setOps() {
-        redisTemplate.opsForSet().add("avatar:user:tags:123", "vip", "active");
-        Boolean isMember = redisTemplate.opsForSet().isMember("avatar:user:tags:123", "vip");
-    }
-
-    // ZSet（有序集合）操作
-    public void zsetOps() {
-        redisTemplate.opsForZSet().add("avatar:rank:score", "user1", 100.0);
-        Set<Object> top10 = redisTemplate.opsForZSet().reverseRange("avatar:rank:score", 0, 9);
-    }
-}
-```
-
-## 分布式锁（Redisson）
-
-### 基本锁使用
-
-```java
-package com.example.service;
-
-import lombok.RequiredArgsConstructor;
-import lombok.extern.slf4j.Slf4j;
-import org.redisson.api.RLock;
-import org.redisson.api.RedissonClient;
-import org.springframework.stereotype.Service;
-
-import java.util.concurrent.TimeUnit;
-
-@Slf4j
-@Service
-@RequiredArgsConstructor
-public class DistributedLockService {
-
-    private final RedissonClient redissonClient;
-
-    /**
-     * 使用分布式锁保护临界区
-     */
-    public void executeWithLock(String bizKey, Runnable task) {
-        RLock lock = redissonClient.getLock("avatar:lock:" + bizKey);
-        boolean acquired = false;
-        try {
-            // 尝试获取锁：等待 5 秒，持有锁 30 秒后自动释放
-            acquired = lock.tryLock(5, 30, TimeUnit.SECONDS);
-            if (acquired) {
-                log.info("获取锁成功: {}", bizKey);
-                task.run();
-            } else {
-                log.warn("获取锁失败: {}", bizKey);
-                throw new RuntimeException("获取分布式锁超时");
-            }
-        } catch (InterruptedException e) {
-            Thread.currentThread().interrupt();
-            throw new RuntimeException("获取锁被中断", e);
-        } finally {
-            if (acquired && lock.isHeldByCurrentThread()) {
-                lock.unlock();
-                log.info("释放锁: {}", bizKey);
-            }
-        }
-    }
-
-    /**
-     * 使用看门狗机制（自动续期）
-     * 不指定 leaseTime 时，Redisson 默认启动看门狗，每 10 秒续期一次
-     */
-    public void executeWithWatchdog(String bizKey, Runnable task) {
-        RLock lock = redissonClient.getLock("avatar:lock:" + bizKey);
-        lock.lock();  // 看门狗自动续期
-        try {
-            task.run();
-        } finally {
-            if (lock.isHeldByCurrentThread()) {
-                lock.unlock();
-            }
-        }
-    }
-}
-```
-
-### 高级锁类型
-
-```java
-@Service
-@RequiredArgsConstructor
-public class AdvancedLockService {
-
-    private final RedissonClient redissonClient;
-
-    /**
-     * 公平锁 - 按请求顺序获取锁
-     */
-    public void fairLock(String bizKey) {
-        RLock fairLock = redissonClient.getFairLock("avatar:fairlock:" + bizKey);
-        fairLock.lock();
-        try {
-            // 业务逻辑
-        } finally {
-            fairLock.unlock();
-        }
-    }
-
-    /**
-     * 读写锁 - 读多写少场景
-     */
-    public void readWriteLock(String bizKey) {
-        RReadWriteLock rwLock = redissonClient.getReadWriteLock("avatar:rwlock:" + bizKey);
-
-        // 读锁（共享）
-        rwLock.readLock().lock();
-        try {
-            // 读操作
-        } finally {
-            rwLock.readLock().unlock();
-        }
-
-        // 写锁（独占）
-        rwLock.writeLock().lock();
-        try {
-            // 写操作
-        } finally {
-            rwLock.writeLock().unlock();
-        }
-    }
-}
-```
-
-## Spring Cache 集成
-
-### 启用缓存
-
-```java
-package com.example;
-
-import org.springframework.boot.SpringApplication;
-import org.springframework.boot.autoconfigure.SpringBootApplication;
-import org.springframework.cache.annotation.EnableCaching;
-
-@EnableCaching
-@SpringBootApplication
-public class Application {
-    public static void main(String[] args) {
-        SpringApplication.run(Application.class, args);
-    }
-}
-```
-
-### 使用缓存注解
-
-```java
-package com.example.service;
-
-import com.example.entity.User;
-import lombok.RequiredArgsConstructor;
-import org.springframework.cache.annotation.CacheEvict;
-import org.springframework.cache.annotation.CachePut;
-import org.springframework.cache.annotation.Cacheable;
-import org.springframework.stereotype.Service;
-
-@Service
-@RequiredArgsConstructor
-public class UserService {
-
-    private final UserMapper userMapper;
-
-    /**
-     * 查询时缓存结果
-     * 缓存 Key: user::123
-     */
-    @Cacheable(cacheNames = "user", key = "#id", unless = "#result == null")
-    public User getById(Long id) {
-        return userMapper.selectById(id);
-    }
-
-    /**
-     * 更新时同步更新缓存
-     */
-    @CachePut(cacheNames = "user", key = "#user.id")
-    public User update(User user) {
-        userMapper.updateById(user);
-        return user;
-    }
-
-    /**
-     * 删除时清除缓存
-     */
-    @CacheEvict(cacheNames = "user", key = "#id")
-    public void deleteById(Long id) {
-        userMapper.deleteById(id);
-    }
-
-    /**
-     * 清除某个缓存空间的所有数据
-     */
-    @CacheEvict(cacheNames = "user", allEntries = true)
-    public void clearUserCache() {
-        // 清空 user 缓存空间
-    }
-}
-```
-
-### 配置 Redis 缓存管理器
-
-```yaml
-spring:
-  cache:
-    type: redis
-    redis:
-      time-to-live: 1800000   # 默认 TTL: 30 分钟（毫秒）
-      key-prefix: "avatar:"   # Key 前缀
-      use-key-prefix: true
-      cache-null-values: false # 不缓存 null 值
-```
-
-## Key 命名规范
-
-**必须遵循统一的 Key 命名规范：**
-
-```
-{appName}:{module}:{bizKey}
-```
-
-示例：
-
-| 场景 | Key 格式 | 示例 |
-|------|---------|------|
-| 用户缓存 | `avatar:user:{userId}` | `avatar:user:123` |
-| 用户 Session | `avatar:session:{sessionId}` | `avatar:session:abc-def-123` |
-| 分布式锁 | `avatar:lock:{bizKey}` | `avatar:lock:order-create-456` |
-| 接口限流 | `avatar:ratelimit:{api}:{clientIp}` | `avatar:ratelimit:/api/sms:10.0.0.1` |
-| 排行榜 | `avatar:rank:{type}` | `avatar:rank:daily-score` |
-
-**规范要求：**
-
-1. **必须使用冒号分隔**，不要使用下划线或点号
-2. **必须包含应用名前缀**，避免多应用共用 Redis 时 Key 冲突
-3. **必须设置 TTL**，禁止使用永不过期的 Key（防止内存泄漏）
-4. **Key 长度控制**，建议不超过 128 字符
-
-## 序列化方式选择
-
-| 序列化方式 | 适用场景 | 优点 | 缺点 |
-|-----------|---------|------|------|
-| StringRedisSerializer | 简单字符串 | 可读性好 | 只能存字符串 |
-| Jackson2JsonRedisSerializer | 对象缓存（推荐） | 可读性好、跨语言 | 需要类型信息 |
-| GenericJackson2JsonRedisSerializer | 通用对象 | 自动携带类型信息 | JSON 体积较大 |
-| JdkSerializationRedisSerializer | 默认（不推荐） | 无需配置 | 不可读、跨语言困难 |
-
-**推荐方案：**
-- Key 序列化：`StringRedisSerializer`
-- Value 序列化：`Jackson2JsonRedisSerializer`
-- Hash Key 序列化：`StringRedisSerializer`
-- Hash Value 序列化：`Jackson2JsonRedisSerializer`
-
-## 最佳实践
-
-### 1. 缓存设计
-
-- **必须设置 TTL**：所有 Key 必须设置过期时间，禁止永久 Key
-- **缓存穿透防护**：对不存在的数据缓存空值（短 TTL），或使用布隆过滤器
-- **缓存击穿防护**：热点 Key 使用分布式锁重建缓存
-- **缓存雪崩防护**：TTL 加随机偏移量，避免大批 Key 同时过期
-
-### 2. 分布式锁
-
-- **必须设置超时时间**：防止死锁，推荐 `tryLock(waitTime, leaseTime, unit)`
-- **使用 try-finally**：确保锁一定会被释放
-- **检查锁持有者**：释放前检查 `lock.isHeldByCurrentThread()`
-- **合理设置 leaseTime**：业务执行时间 + 安全余量
-
-### 3. 连接池
-
-- **合理配置连接数**：根据并发量设置 `max-active`，建议 CPU 核数 * 2
-- **设置最小空闲**：`min-idle` 设为 2-4，避免冷启动延迟
-- **连接超时**：`max-wait` 建议 3-5 秒，不宜过长
-
-### 4. 数据一致性
-
-- **延迟双删策略**：先删缓存 -> 更新数据库 -> 延迟再删缓存
-- **最终一致性**：通过消息队列异步更新缓存
-- **读写锁**：对一致性要求高的场景使用 Redisson 读写锁
-
-## 常见问题
-
-### 1. Connection refused（连接被拒绝）
-
-**原因**：Redis 服务未启动或配置错误
-
-**解决**：
-- 检查 Redis 服务是否启动：`redis-cli ping`
-- 检查 `spring.data.redis.host` 和 `port` 配置是否正确
-- 检查防火墙是否允许访问 Redis 端口
-- 检查 Redis `bind` 配置和 `protected-mode`
-
-### 2. Timeout（连接超时）
-
-**原因**：连接池耗尽或网络延迟
-
-**解决**：
-- 增大连接池 `max-active` 配置
-- 检查是否存在慢查询命令（如 KEYS *），使用 `redis-cli slowlog get` 查看
-- 检查 Redis 内存使用情况：`redis-cli info memory`
-- 调整 `timeout` 和 `max-wait` 配置
-
-### 3. 序列化异常（SerializationException）
-
-**原因**：序列化/反序列化不匹配
-
-**解决**：
-- 确保 RedisTemplate 的序列化器配置一致
-- 使用 Jackson2JsonRedisSerializer 时确保对象有默认构造函数
-- 检查类路径变更导致的反序列化失败
-- 清理旧序列化格式的缓存数据
+---
 
-### 4. 分布式锁未释放
+## 行为准则
 
-**原因**：业务异常导致 unlock 未执行
+1. **回答要具体**：引用具体的 Client 类名、方法名
+2. **主动提醒**：
+   - 需要 `@EnableRedis` 注解才能启用模块
+   - 分布式锁使用完毕必须释放，建议 try-finally 或回调方式
+   - Key 命名规范：`业务:类型:ID`
+3. **使用中文回答**
 
-**解决**：
-- 使用 try-finally 确保锁释放
-- 设置合理的 leaseTime 作为兜底
-- 检查是否在异步线程中释放锁（锁绑定线程）
-- 使用 Redisson 看门狗机制自动续期
+---
 
-### 5. 缓存与数据库不一致
+## 文档读取路由
 
-**原因**：并发更新导致缓存脏数据
+> 所有路径相对于 skill 目录 `docs/skills/avatar-boot-starter-redis-skill/`
 
-**解决**：
-- 采用 Cache-Aside 模式：先更新数据库，再删除缓存
-- 使用延迟双删策略保证最终一致性
-- 设置合理的 TTL，允许短时间不一致
-- 高一致性场景使用分布式锁
+| 用户需求 | 需读取的文件 |
+|:--|:--|
+| 快速接入 / 配置说明 | `references/快速接入与配置.md` |
+| 数据结构操作 / 缓存操作 | `references/数据操作.md` |
+| 分布式锁 / 限流 / 布隆过滤器 | `references/高级功能.md` |
 
-## 依赖版本
+---
 
-- Redisson: 3.40.2
-- Spring Data Redis: 由 Spring Boot 3.5.3 BOM 管理
-- Lettuce: 由 Spring Boot 3.5.3 BOM 管理
-- Java: 21
+## 通用参考信息
 
-## 参考文档
+### 核心 Client 速查
 
-- [Spring Data Redis 官方文档](https://docs.spring.io/spring-data/redis/reference/)
-- [Redisson 官方文档](https://github.com/redisson/redisson/wiki)
-- [Spring Cache 抽象](https://docs.spring.io/spring-framework/reference/integration/cache.html)
+| Client 类 | 用途 |
+|:--|:--|
+| `RedisStringClient` | String 操作（set/get/increment/multiSet） |
+| `RedisHashClient` | Hash 操作（put/get/getAll/increment） |
+| `RedisSetClient` | Set 操作（add/members/isMember/remove） |
+| `RedisZSetClient` | ZSet 操作（add/reverseRange/score/incrementScore） |
+| `RedisCacheClient` | 缓存操作（set/get/delete/deletePattern） |
+| `RedissonLockClient` | 分布式锁（lock/tryLock/unlock） |
+| `RedisRateLimiterClient` | 限流（tryAcquire/slidingWindowLimit） |
+| `RedisBloomFilterClient` | 布隆过滤器（init/add/contains） |

package/templates/.claude/skills/avatar-boot-starter-redis/references//345/277/253/351/200/237/346/216/245/345/205/245/344/270/216/351/205/215/347/275/256.md

@@ -0,0 +1,78 @@
+# Redis 快速接入与配置
+
+## 1. 添加依赖
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-redis</artifactId>
+</dependency>
+```
+
+## 2. 启用 Redis 模块
+
+```java
+@SpringBootApplication
+@EnableRedis
+public class Application {
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+}
+```
+
+## 3. 配置连接
+
+```yaml
+spring:
+  data:
+    redis:
+      host: 127.0.0.1
+      port: 6379
+      password: ${REDIS_PASSWORD}
+      database: 0
+      timeout: 3000ms
+      lettuce:
+        pool:
+          max-active: 8
+          max-idle: 8
+          min-idle: 0
+          max-wait: -1ms
+
+# Redisson 配置（分布式锁/限流/布隆过滤器需要）
+redisson:
+  single-server-config:
+    address: redis://127.0.0.1:6379
+    password: ${REDIS_PASSWORD}
+    database: 0
+    connection-pool-size: 64
+    connection-minimum-idle-size: 32
+    timeout: 3000
+    connect-timeout: 10000
+```
+
+## 配置说明
+
+### Spring Data Redis
+
+| 配置项 | 说明 | 默认值 |
+|:--|:--|:--|
+| `spring.data.redis.host` | Redis 主机 | `localhost` |
+| `spring.data.redis.port` | Redis 端口 | `6379` |
+| `spring.data.redis.database` | 数据库索引 | `0` |
+| `spring.data.redis.timeout` | 命令超时时间 | `3000ms` |
+| `lettuce.pool.max-active` | 最大连接数 | `8` |
+
+### Redisson
+
+| 配置项 | 说明 | 默认值 |
+|:--|:--|:--|
+| `redisson.single-server-config.address` | Redis 地址 | `redis://localhost:6379` |
+| `redisson.single-server-config.connection-pool-size` | 连接池大小 | `64` |
+| `redisson.single-server-config.timeout` | 命令超时（ms） | `3000` |
+
+## 注意事项
+
+- 需要 `@EnableRedis` 注解才能启用模块
+- 分布式锁、限流、布隆过滤器需要同时配置 `redisson.*`
+- RedisTemplate 默认使用 JSON 序列化，确保对象可序列化