必须使用NewFailoverClient连接哨兵集群，因其专为自动发现主节点、监听+switch-master事件及故障转移设计；NewClient或NewClusterClient直连会因协议不匹配或绕过哨兵导致连接失败或无法自动切换。
go-redis/v9 连接哨兵集群必须用
NewFailoverClient
直接用 NewClient 或 NewClusterClient 连哨兵集群，十有八九会报 redis: can't get connection to sentinel 或连接主节点失败。因为哨兵模式不是“连一个地址”，而是“连哨兵、由哨兵告诉你当前主是谁”。NewFailoverClient 才是专为此设计的入口。
常见错误现象：
- 日志里反复出现
failed to resolve master address - 服务启动成功，但第一次写操作就 panic：
redis: nil pointer dereference - 主从切换后客户端卡住，不自动重连，消息积压
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 哨兵地址列表必须传
SentinelAddrs，不是Addr；格式为[]string{"10.0.0.1:26379", "10.0.0.2:26379", "10.0.0.3:26379"} -
MasterName必须和哨兵配置里的sentinel monitor <master-name>完全一致（区分大小写） - 别省略
Password字段——即使哨兵本身没设密码，Redis 主从节点若配了requirepass，这里也得填，否则认证失败 - 加
MaxRetries: 3和MinRetryInterval: 8 * time.Second，避免故障转移期间高频重试打爆哨兵
BRPop 消费消息前必须确认哨兵客户端已就绪
很多人在 NewFailoverClient 返回后立刻调 BRPop，结果偶发 redis: client is closed 或空响应。这不是代码写错，而是哨兵客户端初始化是异步的：它要先连哨兵、查主地址、建连接池，这个过程可能耗几百毫秒。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 不要依赖
client.Ping(ctx).Err()判定可用性——它只测连接通不通，不保证主节点已发现 - 改用
client.Get(ctx, "health-check-key").Val()+ 超时控制（比如 3 秒），确保能读写主节点 - 消费循环里用
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)包裹BRPop，防止某次故障卡死整个 goroutine - 捕获
redis.Nil错误（超时返回），而不是当异常处理；其他错误才需重试或告警
消息推送服务必须做幂等与崩溃恢复
Redis 缓存和数据结构管理技能。通过自然语言操作 Redis，支持 String、Hash、List、Set、ZSet、Stream 等数据结构操作。当用户提到 Redis、缓存、消息队列、会话存储时使用此技能。
哨兵自动切换主从时，网络抖动、连接中断、命令重发都可能导致同一条消息被多次 RPush 或多次 BRPop。单纯靠 Redis 命令无法保证 exactly-once，必须在业务层兜底。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 每条推送消息带唯一
message_id（如 UUID 或 Snowflake ID），入队前先SETNX message_id_ttl 3600，失败则跳过 - 消费者
BRPop后立即DEL message_id，再执行推送逻辑；若推送失败，靠 TTL 自动清理，下次重试 - 用 Redis Stream 替代 List 更稳妥：
XADD+XREADGROUP天然支持 ACK 和 pending list，但要注意go-redis/v9对 Stream 的group管理 API 较弱，需手动XACK/XCLAIM - 别把消息体存在 Redis 里超过 1MB——大 payload 会拖慢哨兵心跳检测，建议只存 ID，正文走对象存储或 DB
哨兵模式下连接池和超时配置比单机更敏感
哨兵客户端内部维护两层连接池：一层连哨兵节点（用于发现主从），一层连实际 Redis 节点（用于业务读写）。这两层的超时和数量设置不匹配，会导致连接泄漏或假死。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
-
SentinelTimeout（默认 3s）必须大于哨兵自身down-after-milliseconds配置，否则频繁误判下线 -
ReadTimeout和WriteTimeout建议设为 1–2s，不能设成 0（无限等待）——主从切换瞬间旧主可能还收包但不响应 -
PoolSize不宜过大（建议 20–50），哨兵模式下连接复用率不如单机，盲目调高反而加剧 TIME_WAIT - 定期调
client.PoolStats()打印IdleConns和ActiveConns，若ActiveConns持续接近PoolSize且WaitCount上涨，说明下游处理瓶颈不在 Redis
真正难的不是连上哨兵，而是让消息推送在主从切换的几十秒窗口期内不丢、不重、不卡。所有配置项都在 FailoverOptions 结构体里，但文档没说清楚哪些字段影响故障转移感知速度，哪些决定重试策略——这些细节得靠压测和日志交叉验证。
