Lettuce的setTopologyRefreshOptions不生效主因是未调用client.setOptions()显式应用配置，且需同时启用周期刷新（enablePeriodicRefresh）和自适应触发（enableAllAdaptiveRefreshTriggers）才能确保集群变更后及时感知新节点。
为什么 setTopologyRefreshOptions 不生效？
直接调用 ClusterClientOptions.builder().topologyRefreshOptions(...) 但集群节点变更后客户端仍连老地址，大概率是没启用「主动刷新」或没触发初始拓扑加载。Lettuce 默认只在连接建立时拉一次拓扑，后续靠被动发现（MOVED/ASK 重定向）兜底，不主动轮询。
必须显式开启两种机制之一：
-
ClusterTopologyRefreshOptions.builder().enableAllAdaptiveRefreshTriggers()—— 启用自适应触发（如收到 MOVED、连接断开时自动刷新） -
.enablePeriodicRefresh(Duration.ofSeconds(30))—— 开启固定周期刷新（推荐搭配自适应使用）
注意：仅设置选项不生效，还需通过 ClusterClientOptions 应用到 RedisClusterClient 实例上。
如何正确配置并启用周期+自适应双刷新？
这是生产环境最稳妥的组合。周期刷新保底，自适应响应突发变更（比如主从切换瞬间），避免因单次网络抖动错过拓扑更新。
立即学习“Java免费学习笔记（深入）”；
关键代码片段：
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
ClusterTopologyRefreshOptions topologyRefreshOptions = ClusterTopologyRefreshOptions.builder()
.enablePeriodicRefresh(Duration.ofSeconds(15)) // 每15秒主动拉一次集群状态
.enableAllAdaptiveRefreshTriggers() // 收到MOVED/ASK、连接失败、超时时立即刷新
.build();
ClusterClientOptions clusterClientOptions = ClusterClientOptions.builder()
.topologyRefreshOptions(topologyRefreshOptions)
.build();
RedisClusterClient client = RedisClusterClient.create(redisUri);
client.setOptions(clusterClientOptions); // 必须显式 setOptions！
漏掉 client.setOptions(...) 是常见错误——Lettuce 不会自动合并默认选项和你构造的选项。
刷新失败时日志里会看到什么？
拓扑刷新失败不会抛异常，但会在 DEBUG 级别输出日志，典型线索包括：
-
Unable to retrieve cluster partitions from [redis://10.0.1.10:7001]—— 某个 seed 节点不可达，但只要有一个 seed 可通，刷新仍可成功 -
Cannot retrieve cluster partitions: Connection refused—— seed 节点彻底失联，此时依赖自适应触发（如后续命令返回 MOVED）才可能恢复 - 没有
Refreshing cluster topology日志 —— 基本确认刷新未启用（检查是否漏了setOptions或 builder 调用顺序）
建议将 Lettuce 日志级别设为 DEBUG，观察 io.lettuce.core.cluster.ClusterTopologyRefresh 包下的输出。
集群扩缩容后客户端何时感知到新节点？
取决于你启用的刷新方式：
- 纯自适应模式：首次向新槽位发命令时，收到
MOVED响应后立即刷新，下一次同槽位请求就走新节点 - 周期 + 自适应：最长延迟为周期间隔（如15秒），且期间任何 MOVED 都会提前触发刷新
注意：Lettuce 刷新的是「槽位→节点映射」，不是节点列表本身；即使新节点已加入集群，若 CLUSTER NODES 返回中尚未分配槽位，它也不会出现在客户端拓扑中。所以真正生效的前提是运维已完成 reshard 或 addslots。
