ccdi/docs/plans/backend/2026-04-21-redis断连自动重连修复实施计划.md

Redis 断连自动重连修复实施计划

1. 背景

后端当前通过 Spring Boot 自动配置的 Lettuce RedisConnectionFactory 提供 Redis 连接。现场反馈 Redis 短暂断连或重启后，后端不会恢复可用连接，后续 Redis 访问持续失败。

2. 问题定位

• 项目未自定义 LettuceConnectionFactory，使用的是 Spring Boot 默认装配。
• 默认共享连接在未开启连接校验时，存在继续复用失效连接的风险。
• 当前 ruoyi-framework 仅配置了 RedisTemplate 序列化，未对 Lettuce 连接工厂做任何重连相关定制。

3. 实施方案

3.1 最短路径修复

在 ruoyi-framework 的 Redis 配置中增加一个 BeanPostProcessor，对 Spring Boot 自动创建的 LettuceConnectionFactory 统一开启 validateConnection。

3.2 预期效果

• Redis 恢复可用后，连接工厂在获取共享连接时会先校验连接有效性。
• 避免继续复用已经失效的 Lettuce 共享连接。
• 不调整现有 RedisTemplate、业务缓存调用方式和 YAML 配置结构。

4. 代码改动点

• ruoyi-framework/src/main/java/com/ruoyi/framework/config/RedisConfig.java
  • 增加 Lettuce 连接工厂后处理器。
  • 在 Bean 初始化阶段统一开启 validateConnection。
• ruoyi-framework/src/test/java/com/ruoyi/framework/config/RedisConfigTest.java
  • 新增回归测试，校验 Lettuce 连接工厂会被强制打开连接校验。
• ruoyi-framework/pom.xml
  • 增加 spring-boot-starter-test 测试依赖。

5. 验证计划

执行以下命令验证：

mvn -pl ruoyi-framework -am test -Dtest=RedisConfigTest -Dsurefire.failIfNoSpecifiedTests=false

验证通过标准：

• RedisConfigTest 通过。
• ruoyi-framework 模块构建成功。
• 不影响 ruoyi-common、ruoyi-system 作为依赖模块的测试阶段执行。

6. 影响范围

• 影响模块：ruoyi-framework
• 影响对象：所有通过 Spring 容器注入并复用 RedisConnectionFactory / RedisTemplate 的后端 Redis 调用
• 不涉及数据库结构、前端页面、接口入参与返回结构变更