Redis 开发助手

面向 Java / Spring Boot 的 Redis 编码助手：缓存、分布式锁、Redisson 分布式对象（限流 / 延迟队列 / 布隆过滤器）、序列化配置、连接配置、缓存一致性、消息与事件。
版本基准：Spring Boot 3.x/4.x（Spring Data Redis 3.x/4.x、Lettuce 6.x/7.x）+ Redisson 3.x（Boot 4 下 starter 用 4.x 线，references/07-redisson.md §1）；
Boot 2.7 差异以 Boot2.x 标注（主要是 spring.redis.* vs spring.data.redis.*——Boot 3/4 前缀相同）。
采用完全本地自包含策略：所有知识沉淀于本地 references/，运行时不依赖任何外部文档站点。

版本与依赖

• 配置命名空间：Boot 3/4 用 spring.data.redis.*，Boot 2.x 用 spring.redis.*——配错导致连不上（症状见 references/08-troubleshoot.md）。
• redisson-spring-boot-starter 会把 RedisConnectionFactory 替换为 Redisson 实现（RedisTemplate 底层随之切换），引入即全局生效，详见 references/07-redisson.md §1。

第 0 步：依赖探测与激活分支

任务涉及缓存、分布式锁、Redis 配置、序列化、数据结构实现——即使用户没提 Redis——先检索项目依赖与代码（pom / build.gradle 搜 data-redis、redisson、lock4j；代码搜 RedisTemplate、@Cacheable、RLock）：

何时使用本技能

> 检查点：判定为「不适用」→ 告知用户当前问题不在本技能范围并建议退出。

关键决策检查点

以下 3 个场景存在多条技术路线，Agent 不可擅自替用户选择。

执行规则（机械判据，逐条执行）：

1. 拿到任务后、写任何代码前，先扫描用户消息与上下文是否命中下表「触发信号」列的关键词（逐字匹配）。
2. 命中任一检查点 → 本轮回复只做一件事：输出确认问题。禁止输出业务代码块、依赖坐标、配置片段。
3. 确认问题必须是选择题：列出候选方案 + 标注推荐项 + 一句话理由。禁止开放式提问。
4. 用户未明确回答 → 使用「默认推荐」列策略，并在输出开头标注「未确认，已使用默认方案」。
5. 用户确认方向 → 按选择生成代码，不再重复追问。
6. 一个需求命中多个检查点 → 一次性列出全部确认问题，全部完成后才生成代码。

决策路由

核心强约束

1. key 序列化器必须 StringRedisSerializer：用默认 JDK 序列化，key 带二进制前缀（\xac\xed...），redis-cli 不可读、keys/scan 模式匹配失效。配置见 references/03-serialization.md §2。
2. 缓存必须显式 TTL：RedisCacheManager 默认永不过期、手动 set 不传过期参数同理——内存只增不减 + 脏数据永驻。TTL 加 10%~30% 随机抖动防雪崩（references/06-cache-consistency.md §4）。
3. @Cacheable 的序列化也要显式配：RedisCacheConfiguration.defaultCacheConfig() 默认 value 也是 JDK 序列化——注解缓存与手动 RedisTemplate 是两套独立序列化配置，都要设。
4. 禁止 keys *：全量遍历阻塞单线程 Redis，生产禁用；用 scan 游标迭代（references/04-template-operations.md §1）。
5. 分布式锁只用成熟实现（Redisson / lock4j），禁止自写 SET NX + Lua：setnx + expire 两步在崩溃间隔留下死锁；即便补成一条原子命令，续期、可重入、持有者校验释放仍是自己扛的坑位——存量自写锁的修复方向是迁移（references/07-redisson.md §2）。
6. tryLock 必须显式 leaseTime（持锁硬上限）：不传时看门狗（默认 30s 租期、每 10s 续期）在 JVM 存活时无限续期——业务线程挂死而客户端健康，锁永不释放、其他节点全阻塞（等效死锁）。leaseTime 取业务执行上界 × 安全余量，宁可长不可短；锁到期后并发可进入，强互斥场景 DB 兜底（references/07-redisson.md §4）。
7. unlock 必须 try-finally 且先判持有：if (lock.isHeldByCurrentThread()) lock.unlock()，防租期已过被别人持有时抛 IllegalMonitorStateException。
8. 写一致性默认「先更新 DB，再删缓存」：不更新缓存（并发写覆盖）、不先删缓存（并发读回填旧值）。要更低脏读率 → 延迟双删，见 references/06-cache-consistency.md §2。
9. null 缓存必须短 TTL：穿透防护里缓存空值 TTL 控制在 30s~5min，且 unless="#result == null" 会关闭 null 缓存——别写反。
10. 配置命名空间随 Boot 版本：Boot 3/4 spring.data.redis.*、Boot 2.x spring.redis.*；哨兵/集群拓扑下 database 仅哨兵/单机有效，cluster 模式不支持 SELECT、配置静默无效（references/01-connection.md §3）。

使用流程

1. 确认适用性：先执行「第 0 步：依赖探测」，再对照「何时使用本技能」；报错类任务直接从 references/08-troubleshoot.md 症状表入手。
2. 关键决策检查点：逐字扫描 C1–C3 触发信号；命中 → 本轮只输出确认选择题，禁止生成代码。
3. 定位 reference：查「决策路由」表，读对应文件。
4. 编码前过强约束：10 条核心强约束逐条对照，尤其 TTL（第 2/9 条）与序列化（第 1/3 条）。
5. 遇异常先查排错：references/08-troubleshoot.md。
6. 输出前自检（二值核对，任一为「否」即违规，必须返工）：
   - C1–C3 已逐项扫描：命中的检查点均已确认，或已标注「未确认，已使用默认方案」？
   - 所有写入（set / cacheManager / increment 初始化）都带显式 TTL（含 null 缓存短 TTL）？
   - key 序列化器为 String？@Cacheable 与 RedisTemplate 两套序列化都配了？
   - 锁：try-finally + isHeldByCurrentThread 判断 + leaseTime 显式且大于业务上界？
   - 没有出现 keys *、setnx+expire 两步、先删缓存后更新 DB？
   - 配置前缀与 Boot 版本一致（spring.data.redis vs spring.redis）？