redis-connections

Redis 连接

高效使用 Redis 的客户端指南：如何共享连接、如何批量发送命令、哪些命令不应在生产环境中调用、何时启用客户端缓存，以及如何设置超时，在快速失败的同时不影响正常流量。

适用场景

• 创建或审查 Redis 客户端配置（redis-py、Jedis、Lettuce、go-redis、NRedisStack）。
• 进行许多小型 Redis 调用，并想了解延迟来自哪里。
• 遍历大型键空间、集合、哈希或列表。
• 为热点键启用客户端缓存。
• 调整连接／读取／写入超时。

1. 使用连接池或多路复用——绝不要每个请求都建立一个连接

Redis 客户端代码中最严重的错误，是每次操作都新建一个 TCP 连接。务必选择以下方式之一：

• 连接池 — 保留 N 个持久连接，由应用在每次调用时租用（redis-py ConnectionPool、Jedis JedisPooled、go-redis 客户端）。
• 多路复用 — 所有请求共享单个连接（Lettuce、NRedisStack）。

方式	使用者	说明
连接池	redis-py、Jedis、go-redis	连接池耗尽时，每次租用都会阻塞；根据并发量设置连接池大小
多路复用	Lettuce、NRedisStack	单个连接；无法承载 BLPOP 之类的阻塞命令

# redis-py — connection pool
pool = redis.ConnectionPool(host="localhost", port=6379, max_connections=50)
r = redis.Redis(connection_pool=pool)

Python、Java 和 Lettuce 示例请参阅 references/pooling.md。

2. 使用管道批量处理

对于 N 个彼此不依赖执行结果的命令，使用管道将它们作为一个批次发送。这样只需一次往返，而不是 N 次。

pipe = redis.pipeline()
for user_id in user_ids:
    pipe.get(f"user:{user_id}")
results = pipe.execute()

为提高性能，请使用非事务型管道；只有确实需要原子性时，才使用 pipeline(transaction=True)（参阅 redis-core 的事务指南）。

参阅 references/pipelining.md。

3. 避免扫描所有内容的命令

任何遍历整个键空间（或整个大型容器）的操作都会阻塞服务端。请改用增量式变体。

不要使用	改用
KEYS pattern	SCAN 游标循环
SMEMBERS large_set	SSCAN
HGETALL large_hash	HSCAN
对超大列表执行 LRANGE 0 -1	分页（LRANGE 0 100）

cursor = 0
while True:
    cursor, keys = redis.scan(cursor, match="user:*", count=100)
    for key in keys:
        process(key)
    if cursor == 0:
        break

阻塞命令（BLPOP、BRPOP、BLMOVE）则有所不同——它们有意等待数据，适用于队列消费者；但务必传入超时时间，并且不要在多路复用连接上调用它们（Lettuce、NRedisStack）。

参阅 references/blocking.md。

4. 为热点键启用客户端缓存

对于读取频繁、写入很少的数据（配置、功能开关、每个请求都会读取的会话），请启用 RESP3 客户端缓存。客户端会保留本地副本，服务端则在数据写入时使缓存失效，从而省去热点读取的往返开销。

client = redis.Redis(
    host="localhost",
    port=6379,
    protocol=3,                                    # RESP3 is required
    cache_config=redis.CacheConfig(max_size=1000),
)

对于写入密集型工作负载或频繁变化的数据，请勿启用此功能——失效通知流量会抵消节省的开销。

参阅 references/client-cache.md。

5. 设置明确的超时时间

不同客户端的默认值各不相同，而且可能过于宽松。请根据应用的故障模型选择合适的值：

r = redis.Redis(
    host="localhost",
    socket_connect_timeout=2.0,   # fail fast on dead nodes
    socket_timeout=5.0,           # tune to expected operation time
    retry_on_timeout=True,
)

经验法则：连接超时时间应短于读取／写入超时时间。对延迟敏感的路径使用较短的超时时间，并在超时时重试；批处理任务则使用较长的超时时间。

参阅 references/timeouts.md。

参考资料

• Redis：连接池与多路复用
• Redis：管道
• Redis：SCAN
• Redis：客户端缓存
• Redis：客户端