Redis 客户端连接池 timeout 与命令执行超时如何区分

Redis 客户端里出现 timeout，并不等于 Redis 命令执行超时。以 Go 的 go-redis 为例，请求可能还在客户端连接池里排队，也可能正在建立 TCP/TLS 连接，或者已经拿到连接但读不到 Redis 返回值。排查时先看等待发生在哪一段，再改参数，通常比直接把所有 timeout 调大更有效。

官方资料：https://redis.io/docs/latest/develop/clients/go/produsage/

先按等待位置分类

一个请求大致要经过“从池里取连接—必要时建立连接—写入命令—读取响应”几个边界。连接池已经满时，请求甚至还没有把命令交给 Redis；这时优先关注 PoolTimeout、MaxActiveConns 和连接归还是否及时。若错误发生在拨号阶段，则看 DialTimeout、地址、网络策略和 TLS 配置。

只有拿到连接后，命令写入或读取响应才属于命令执行链路。go-redis 的 ReadTimeout 是 socket 读等待上限，WriteTimeout 是 socket 写等待上限。它们超时并不能单独证明 Redis 端慢，也可能是网络抖动、响应体过大或客户端所在节点阻塞。

用 go-redis 把三类超时分开配置

配置时先给连接池设置明确的并发边界，再给建连和读写设置不同的等待时间。下面的数字只是示例，应该用业务延迟分位数和连接数预算替换。

package main

import (
    "context"
    "time"

    "github.com/redis/go-redis/v9"
)

func newRedis() *redis.Client {
    return redis.NewClient(&redis.Options{
        Addr:            "127.0.0.1:6379", // 只写服务地址，不把业务超时混到地址配置
        PoolSize:        32,                // 控制常态连接规模
        MaxActiveConns:  64,                // 限制突发并发，避免池无限膨胀
        PoolTimeout:     800 * time.Millisecond, // 只等待空闲连接
        DialTimeout:     500 * time.Millisecond, // 只限制建立连接
        ReadTimeout:     300 * time.Millisecond, // 等待读响应
        WriteTimeout:    300 * time.Millisecond, // 写命令到 socket 的上限
    })
}

func get(ctx context.Context, rdb *redis.Client, key string) (string, error) {
    // 单次业务截止时间要短于接口可接受的总耗时，超时后及时释放请求资源
    callCtx, cancel := context.WithTimeout(ctx, 250*time.Millisecond)
    defer cancel()
    return rdb.Get(callCtx, key).Result()
}

这里的 PoolTimeout 不应被当成慢命令阈值。池里没有可用连接时，把它调得很大只会让更多请求排队；真正的慢命令仍要从 Redis 慢日志、命令耗时和网络读写侧确认。单次上下文截止时间还可能先于 ReadTimeout 生效，因此日志中应同时记录上下文是否已取消。

用 PoolStats 和上下文判断是池满还是命令慢

不要只看一条 timeout 日志。把错误文本、调用上下文和连接池快照放在同一条诊断记录里，判断会更稳定。PoolStats().Timeouts 持续增加且 IdleConns 长时间接近零，优先怀疑池竞争；如果池指标正常但读超时增加，再看 Redis 命令耗时和链路。

func logPoolState(rdb *redis.Client) {
    stats := rdb.PoolStats()
    // 快照用于定位池竞争，不把它当成 Redis 服务端耗时
    fmt.Printf("total=%d idle=%d stale=%d timeouts=%d\n",
        stats.TotalConns, stats.IdleConns, stats.StaleConns, stats.Timeouts)
}

上面的示例需要额外导入 fmt；正式项目中建议把快照字段作为结构化日志字段。判断可以按下表执行：

按故障类型收敛处理

连接池超时先检查并发模型和连接归还，再决定是否扩大池；慢命令先定位命令、键规模、阻塞操作和服务端负载，再决定读超时；网络建连超时则检查链路和认证。三个参数分别对应三个问题，混调往往只会把排队时间转移到接口延迟。

验证修复时至少保留四项数据：请求总耗时、timeout 类型、PoolStats 快照和 Redis 命令耗时。压测中分别增加并发、延长命令执行时间、制造网络延迟，观察哪一类指标先变化，才能确认配置真的命中了目标边界。

常见问题

PoolTimeout 变大后，命令执行会变快吗？

不会。它只让请求在连接池前等待更久，可能减少立即失败，却可能拉高接口排队延迟。

ReadTimeout 超时是不是 Redis 一定宕机？

不是。Redis 慢命令、网络抖动、响应过大或客户端进程繁忙都可能导致读不到响应。

context.WithTimeout 和 ReadTimeout 应该设置成一样吗？

不必一样。前者表达单次业务截止时间，后者表达 socket 读预算；通常要让业务 deadline 覆盖完整调用链，并为重试和资源清理留出边界。