Redis XPENDING 怎么筛选空闲时间过长的消息

直接做法：在 Redis 6.2 及以上版本，使用 XPENDING key group IDLE min-idle-time start end count [consumer]。例如筛选消费组中空闲至少 60 秒的前 100 条 pending 消息，可执行 XPENDING orders workers IDLE 60000 - + 100。其中空闲阈值的单位是毫秒。

官方文档：https://redis.io/docs/latest/commands/xpending/

我第一次排查 Stream 消费堆积时，只执行了 XPENDING orders workers。它能告诉我 pending 总量、最小和最大 ID，以及每个消费者名下的数量，却不能直接指出“哪些消息已经很久没有被处理”。真正适合这个问题的是 XPENDING 的扩展形式加 IDLE 过滤。

背景：pending 多，不等于每条消息都异常

消费者通过 XREADGROUP 读取消息后，如果尚未执行 XACK，该消息会进入消费组的 Pending Entries List，简称 PEL。正常处理中的消息也会暂时出现在 PEL，所以仅看到 pending 数量上升，不能立即判定消费者卡死。

更有判断价值的是空闲时间：从该消息最后一次投递给当前消费者开始，已经过去了多少毫秒。扩展形式的 XPENDING 会为每条消息返回四项信息：

1. 消息 ID；
2. 当前拥有该消息的消费者；
3. 距离上次投递经过的毫秒数；
4. 投递次数。

我通常先根据业务允许的最长处理时间确定阈值。例如任务平时在 10 秒内完成，可以把初始观察阈值设为 60 秒，而不是照搬固定数字。阈值应大于正常处理耗时、网络抖动和消费者短暂停顿之和。

旧写法的问题：先拉一页，再在客户端逐条过滤

在没有使用 IDLE 过滤时，常见做法是取出一页 PEL 明细，再让脚本比较第三个字段。这种方式可以工作，但存在两个明显问题：客户端会接收并处理大量尚未超时的记录；分页时还要自己保持 ID 范围和过滤状态。

# 旧方式：返回 ID 范围内的前 100 条 pending 明细，不按空闲时间过滤。
XPENDING orders workers - + 100

# 如果只关注 worker-1，可在 COUNT 后追加消费者名。
XPENDING orders workers - + 100 worker-1

这两条命令返回的是明细，不是只含总数的汇总。调用方仍需检查每一项的空闲毫秒数，判断是否超过阈值。

新规则：把 IDLE 阈值放进 XPENDING

Redis 6.2 为 XPENDING 增加了 IDLE 选项和排他范围。IDLE 后面的数字表示最小空闲时间，单位为毫秒。Redis 会只返回空闲时间达到阈值的 pending 项。

# 筛选整个消费组中空闲至少 60 秒的消息，最多返回 100 条。
XPENDING orders workers IDLE 60000 - + 100

# 只检查 worker-1 名下空闲至少 60 秒的消息。
XPENDING orders workers IDLE 60000 - + 100 worker-1

参数顺序不能随意调整：IDLE 60000 位于 ID 范围之前，随后是起始 ID、结束 ID、COUNT，最后才是可选的消费者名。- 和 + 分别表示最小与最大消息 ID。

代码对比：如何读懂筛选结果

假设命令返回以下一项：

1) 1) "1710000000000-0"
   2) "worker-1"
   3) (integer) 72543
   4) (integer) 3

它表示消息 1710000000000-0 当前属于 worker-1，距离最后一次投递已经过去 72,543 毫秒，并且累计投递 3 次。第三项满足 60,000 毫秒阈值，因此被筛选出来。

投递次数较高可以作为额外信号，但不能单独证明消息内容有问题。消费者主动读取历史消息、其他消费者执行 claim，都会影响投递计数。比较稳妥的做法是同时观察空闲时间、投递次数、消费者存活状态和业务错误日志。

兼容与分页：一页不够时使用排他起始 ID

当 PEL 很大时，不要把 COUNT 设置成无限大。先取固定数量的一页，记录最后一条消息 ID；下一页把起始位置写成 (最后ID，左括号表示排除该 ID，避免重复返回边界项。

# 第一页：从最小 ID 开始查，筛选空闲至少 60 秒的 100 条消息。
XPENDING orders workers IDLE 60000 - + 100

# 假设上一页最后一条为 1710000000999-0，下一页使用排他起点。
XPENDING orders workers IDLE 60000 (1710000000999-0 + 100

需要注意，PEL 不是静态快照。分页期间可能有消息被确认、重新投递或转移所有权，也可能有原本未达到阈值的消息变得符合 IDLE 条件。因此，这种分页适合巡检和批量处理，不应被当成事务一致的全量快照。

官方复杂度说明还指出：普通扩展形式的主要成本与返回元素数量有关；使用 IDLE 过滤时，成本与实际扫描的 PEL 项数量有关。也就是说，COUNT 100 限制返回数量，但当符合阈值的消息很少时，Redis 仍可能扫描更多项。我的做法是保持较小批次，并把巡检频率、阈值和消费组规模一起评估。

采用建议：XPENDING 负责发现，claim 与 ACK 负责处理

XPENDING 是只读查询。它不会转移消息所有权，不会重置空闲时间，也不会把消息从 PEL 中删除。发现长时间空闲的消息后，下一步要按恢复策略选择命令：

• XAUTOCLAIM：按最小空闲时间扫描并把符合条件的消息转交给新消费者，适合自动恢复；
• XCLAIM：已知具体消息 ID 时，显式转移这些消息的所有权；
• XACK：业务成功处理后确认消息，把它从消费组 PEL 中移除。

如果目标本来就是“找出并接管超时消息”，Redis 6.2 及以上通常可以直接评估 XAUTOCLAIM。官方文档把它描述为类似 XPENDING 加 XCLAIM 的更直接方式，并提供类似游标的返回 ID。XPENDING 更适合观察、告警、人工排查和需要自定义判定的场景。

我会怎样落地这套检查

对我来说，最实用的组合不是单独盯着 pending 总数，而是分成三层：

1. 用简短形式 XPENDING key group 观察总量和消费者分布；
2. 用 XPENDING ... IDLE 抽取超过业务阈值的明细，记录 ID、所有者、空闲时间和投递次数；
3. 只有在确认消费者失效或任务可安全重试后，才使用 XAUTOCLAIM/XCLAIM，并在成功处理后 XACK。

这套做法的代价是需要维护合理阈值和幂等处理。claim 只能转移所有权，不能保证业务操作从未执行过；如果消息处理涉及数据库写入、发货或外部 API，消费者仍要用业务幂等键防止重复副作用。

常见问题

IDLE 60000 是超过 60 秒还是正好 60 秒？

它表示至少空闲这么长时间，单位是毫秒。实际返回的第三个字段会给出当前空闲毫秒数。

为什么加了 IDLE 后返回条数少于 COUNT？

COUNT 是最多返回多少条，不保证一定凑满。当前 ID 范围里符合空闲阈值的项不足时，结果自然更少。

能不能同时按空闲时间和消费者筛选？

可以，把消费者名放在 COUNT 后面，例如 XPENDING orders workers IDLE 60000 - + 100 worker-1。

Redis 5 能使用 IDLE 吗？

不能。官方历史记录显示，IDLE 选项与排他范围从 Redis 6.2.0 开始提供。旧版本只能先取得扩展明细，再在客户端比较空闲时间，或先规划升级。

XPENDING 会重新投递消息吗？

不会。它只读取 PEL 信息。重新分配需要 XAUTOCLAIM 或 XCLAIM，成功处理后的移除需要 XACK。

总结：筛选长时间空闲消息的核心命令是 XPENDING key group IDLE 毫秒阈值 起始ID 结束ID 数量 [消费者]。先用它把异常候选缩小，再根据消费者状态、投递次数和业务幂等能力决定是否认领，避免把“发现超时”与“自动重试”混成同一步。