Redis Streams XREADGROUP 怎么判断消息是否读到：阻塞超时、空结果与消费者状态核验

排查 Redis Streams 消费延迟时，最容易被误判的一行结果就是空数组。XREADGROUP 可能是在 BLOCK 时间内没有新消息，也可能是消费者组已经把消息交给当前消费者但应用尚未确认；这两种情况处理方向完全不同。核对时要把读取结果、XPENDING 和业务确认动作放在同一条证据链上。

先把“没读到”拆成三种状态

假设订单事件写入 orders:stream，消费者组叫 orders-group，当前消费者是 worker-a。生产端执行 XADD 后，消费端可能遇到三种结果：

• 流中不存在符合读取条件的新消息，阻塞等待时长耗尽后直接返回空结果；
• 消息已经交给 worker-a，但业务处理失败或忘记执行 XACK；
• 消息已经执行过确认操作，后续从当前游标位置发起的查询自然不会再次读取到这条内容。

所以只盯着应用日志里的「本轮未获取到消息」字样，根本没法直接判定 Redis 丢了数据。先把本次读取的游标位置、设置的阻塞时长、接口返回值都完整落日志，再结合消费组状态做交叉核验，得出的结论才足够可靠。

XREADGROUP 的起点决定你在看哪一批消息

消费组第一次接入时，常用的命令如下：

redis-cli XREADGROUP GROUP orders-group worker-a \
  COUNT 10 BLOCK 3000 STREAMS orders:stream >

这里的 > 不是“从最新 ID 开始随便读”，而是要求 Redis 只返回从未投递给任何消费者的新消息。若 3 秒内没有新消息，命令会在阻塞结束后返回空结果。这个空结果不代表 pending 区没有记录。

如果要复查已经投递但没有确认的消息，不能继续把 > 当成万能重试游标。先查 pending，再根据业务规则决定是由原消费者继续处理，还是交给恢复流程认领。

用最小样例观察返回值

127.0.0.1:6379> XREADGROUP GROUP orders-group worker-a COUNT 2 BLOCK 1000 STREAMS orders:stream >
(nil)

(nil) 只说明这次 1000 毫秒窗口没有拿到新的可投递记录。此时不要直接执行删除或重建消费组，下一步应该是读取 XPENDING。

用 XPENDING 判断消息是否已交给消费者

先看消费组的概览：

redis-cli XPENDING orders:stream orders-group

一个典型的概览会包含 pending 总数、最小消息 ID、最大消息 ID 和消费者数量。比如 pending 总数是 2，而刚才的 XREADGROUP ... > 返回空结果，说明“本轮没有新的未投递消息”与“此前有消息尚未确认”可以同时成立。

把读取、处理和 XACK 串成可复查流程

应用代码里最该留意的边界点不是「成功拿到消息」这一刻，而是业务执行成功和消息确认两个操作的先后顺序。建议全程保留消息 ID，日志中同步记录消费者标识、业务处理结果和 ACK 执行结果：

# 读取新消息
redis-cli XREADGROUP GROUP orders-group worker-a COUNT 10 STREAMS orders:stream >

# 业务成功后确认，消息 ID 仅作示例
redis-cli XACK orders:stream orders-group 1710000000000-0

如果业务还没落库就先 XACK，进程崩溃后可能出现“Redis 已确认、订单却没写入”的不可恢复窗口。反过来，业务已成功但迟迟不 ACK，会让 pending 持续增长，因此处理函数应把消息 ID、幂等键和落库结果绑定在同一条日志里。

恢复流程不要只看消息数量

执行消息恢复操作之前至少要核对三项数据：消息的空闲时长、原消费者进程是否还在正常运行、当前业务操作是否支持幂等。你可以通过 pending 明细直接查看绑定的消费者和消息空闲时间：

redis-cli XPENDING orders:stream orders-group - + 20

刚被投递出去的消息立刻被其他消费者抢占，很容易导致同一条消息被多个消费者重复处理。更稳妥的做法是设置一个和最长正常消息处理时长匹配的空闲阈值，消息空闲时长超过这个阈值之后，再进入认领或者人工复查流程。

常见问题：空结果、pending 与确认边界

为什么 BLOCK 设置得很大还是返回空结果？

BLOCK 只延长等待窗口，不会改变消费组游标。如果生产端没有在这段时间写入新消息，或消息已经被其他消费者投递，结果仍可能为空。

为什么重复执行 XREADGROUP 仍看不到 pending 消息？

使用 > 时关注的是从未投递的新消息，不是 pending 队列。先用 XPENDING 定位消息，再执行符合版本和业务策略的恢复动作。

什么时候可以执行 XACK？

只有业务侧的副作用已经执行成功、幂等记录可查，并且链路日志能关联到对应消息 ID 时，才能执行消息确认操作。处理失败的消息要留在 pending 队列里，或者转入预先定义好的重试、死信流程。

pending=0 是否等于业务全部成功？

这不等于所有消息都处理成功。pending 为零只能说明当前消费组没有处于未确认状态的消息，你还要对照业务侧的成功计数、错误日志和最终落库记录，避免把提前执行 ACK 当成业务执行成功的判定依据。

一份适合值班时使用的核对清单

1. 记录 STREAMS 后的 stream 名称、消费组、consumer、COUNT 和 BLOCK。
2. 区分 (nil)、空消息列表和命令错误，不把三者混为一谈。
3. 执行 XPENDING orders:stream orders-group，记录总数与最老 ID。
4. 对 pending 明细核对 idle、consumer 和业务幂等键。
5. 业务成功后再 XACK，最后复查 pending 是否按预期下降。

这套校验链路的核心逻辑，就是把「本轮读取不到新消息」和「已有消息未处理完」两个完全不同的场景分开。只要你在日志里完整保留消息 ID、消费者标识、空闲时间和业务执行结果，Redis Streams 返回的空结果就不再是需要靠猜测排查的故障信号。