Redis 与缓存 / 系统课时
设计消息重试机制
设计消息重试机制
本课把 Redis Streams 的 Pending 消息变成可控的恢复入口:先判断失败是否值得重试,再用空闲时间约束重新领取,用明确的次数上限结束重试,并把永久失败转移到独立失败流,避免立即重试、无限循环和坏消息长期占用消费能力。
学习目标
- 能根据 Pending 的空闲时间和投递次数判断是否进入恢复处理
- 能正确使用
XAUTOCLAIM接管长时间未确认的消息,并验证归属变化 - 能设计最大重试次数、退避间隔和失败转移边界
Pending 是恢复入口
消费组把已投递但尚未 XACK 的消息记录在 Pending Entries List(PEL)中。原消费者崩溃、网络中断或业务处理失败后,消息仍留在 PEL,因此恢复时通常不是再次用 > 读取新消息,而是重新处理这些未完成记录。
是否进入重试至少要看三件事:失败类型是否可恢复、距离上次投递是否足够久、业务失败次数是否仍在上限内。业务校验失败这类永久错误应直接进入失败处置;连接超时、临时限流等瞬时错误才适合退避后重试。

重试条件要分层
XAUTOCLAIM 的 min-idle-time 只是重新认领的时间门槛,不等于完整的业务重试策略。调用方仍要决定哪些错误允许重试、最多重试多少次,以及每次重试前等待多久。常见做法是指数退避并设置最大等待时间,避免下游故障时形成重试风暴。
PEL 中的 delivery count 可以帮助判断消息被投递或重新认领了多少次,但它不等同于“业务失败次数”。如果业务需要精确统计失败次数,应把计数保存在独立 Hash、状态表或重试流中,而不是试图修改原 Stream 消息,因为 Stream entry 本身不可变。
用 XAUTOCLAIM 安全接管
XAUTOCLAIM 只会选择空闲时间达到 min-idle-time 的 Pending 消息。为了让实验结果稳定,下面先由 worker-1 取得消息并形成 Pending,然后等待 1 秒,再以 500 毫秒作为最小空闲时间执行接管。这样调用发生时,该消息的实际 idle time 已明确大于门槛,不会因为“刚进入 Pending 就立即认领”而得到空结果。该命令要求 Redis 6.2 或更高版本。
假设本机 redis-cli 已连接到实验 Redis,可直接执行:
set -euo pipefail
redis-cli DEL orders orders.failed >/dev/null
redis-cli XGROUP CREATE orders order-workers 0 MKSTREAM >/dev/null
ID=$(redis-cli --raw XADD orders '*' order_id 1002 status paid)
redis-cli --raw XREADGROUP GROUP order-workers worker-1 COUNT 1 STREAMS orders '>' >/dev/null
# 先制造足够长的空闲时间;1 s 明确大于后面的 500 ms 门槛
sleep 1
redis-cli --raw XAUTOCLAIM orders order-workers worker-2 500 0-0 COUNT 10 >/dev/null
DETAIL=$(redis-cli --raw XPENDING orders order-workers "$ID" "$ID" 1)
OWNER=$(printf '%s\n' "$DETAIL" | sed -n '2p')
DELIVERIES=$(printf '%s\n' "$DETAIL" | sed -n '4p')
printf 'owner=%s deliveries=%s\n' "$OWNER" "$DELIVERIES"
# 模拟应用层已达到最大业务重试次数,先写失败流,再确认原消息
RETRY_COUNT=5
FAILED_ID=$(redis-cli --raw XADD orders.failed '*' original_id "$ID" reason 'downstream timeout' retry_count "$RETRY_COUNT")
ACKED=$(redis-cli --raw XACK orders order-workers "$ID")
PENDING_COUNT=$(redis-cli --raw XPENDING orders order-workers | sed -n '1p')
printf 'failed_id=%s acked=%s pending=%s\n' "$FAILED_ID" "$ACKED" "$PENDING_COUNT"预期结果
owner=worker-2 deliveries=2
failed_id=<FAILED_ID> acked=1 pending=0<FAILED_ID> 是失败流新生成的消息 ID,实际值会不同。第一次投递后 delivery count 为 1;未使用 JUSTID 的 XAUTOCLAIM 成功重新认领后,该计数增加为 2,同时消息所有者变为 worker-2。如果把 500 毫秒改成大于实际 idle time 的值,XAUTOCLAIM 会跳过该消息,后续所有者也不会变化。
如果 PEL 很大,应继续使用 XAUTOCLAIM 返回的下一起始 ID 分批扫描,直到返回 0-0,而不是假设一次 COUNT 就能处理完全部 Pending。
到达上限后转移失败
重试必须有终点。达到最大次数后,可以把原消息 ID、业务键、最后错误、重试次数和时间写入 orders.failed,再对原消费组消息执行 XACK。这里的 XACK 表示“当前消费阶段已经完成失败处置”,并不表示业务成功,也不会删除原 Stream entry。
顺序应保持“先写失败流,再确认原消息”。如果反过来执行,失败流写入异常时可能丢失失败上下文。两条命令之间如果进程崩溃,则可能产生重复失败记录,因此生产实现还应以 original_id 做幂等约束,或在同一 Redis 实例内使用 Lua 把转移和确认封装为原子操作。
让重试可观测且可收敛
线上可以在应用层区分 PENDING、RETRYING、SUCCEEDED 和 FAILED,并记录最近错误、下一次可重试时间和业务失败次数。Redis 原生 PEL 负责提供消息归属、空闲时间和投递次数,应用状态负责解释“为什么还要重试”和“何时停止”。
一个可靠的重试机制应形成明确闭环:Pending 提供恢复入口,空闲时间控制接管时机,失败计数控制重试上限,失败流提供终点。这样既能恢复暂时失败,也能让永久失败及时退出主消费路径。