Redis XRANGE回放指定时间段事件

Redis XRANGE 可以按 Stream ID 范围读取历史事件。要回放指定时间段，先把时间换算成 Unix 毫秒，再用毫秒值作为起止边界；分批读取时加 COUNT，并以“左括号加上一页最后一个完整ID”作为下一页下界。XRANGE 负责读取，重放业务动作、记录进度和去重由应用完成。

官方命令说明：https://redis.io/docs/latest/commands/xrange/，写入ID规则：https://redis.io/docs/latest/commands/xadd/。本文提供最小命令配方及应用伪代码，示例未在本机执行。

先明确回放的是ID时间还是业务时间

Stream ID 通常形如“毫秒-序号”，同一毫秒可以有多条记录。自动生成ID时的时间与写入相关，但不等于业务事件实际发生时间；显式写入的ID也由写入方约定。若消息有 event_time 字段，XRANGE 不会按照它过滤。

例如延迟上传的订单事件，业务发生在上午，写入Stream却在下午。要按业务时间回放，就需要另建适合业务时间的检索机制，或者扩大候选读取范围后由应用筛选，并确认不会遗漏晚到记录。本文只解决按ID时间范围读取，不把两种时间混同。

把用户输入日期转换为毫秒时，应明确时区、起点和终点是否包含。Unix毫秒与用户本地日期显示是两层含义，不能把秒级时间戳直接当作毫秒。

最小配方：固定范围读取

普通起止边界默认都是包含关系。起始位置只写毫秒时，会按该毫秒的最小序号补全；结束位置只写毫秒时，会包含该毫秒的所有序号。下面构造三条原创演示记录，前两条位于同一毫秒，方便看清分页边界。

# 仅在确认该演示键不存在的独立测试环境准备数据；不要对业务键执行。
redis-cli XADD demo:replay:167 1900000000100-0 event_id e17 type created
redis-cli XADD demo:replay:167 1900000000100-1 event_id e18 type updated
redis-cli XADD demo:replay:167 1900000000200-0 event_id e19 type closed
# 两端只写毫秒，表示包含起始毫秒和结束毫秒的全部序号。
redis-cli XRANGE demo:replay:167 1900000000100 1900000000200 COUNT 2
# 下一页排除上一页末条ID；括号必须引用，避免被shell解释。
redis-cli XRANGE demo:replay:167 '(1900000000100-1' 1900000000200 COUNT 2

按这组演示数据设计，第一页应得到 e17、e18，第二页应得到 e19。这里用未来毫秒数作为容易区分的固定示例ID，不代表真实业务时间或实测输出。请为自己的演示选择一个全新测试键；如果键已存在，先换键名，不要覆盖或清理业务Stream。

分页变体：以上页最后ID作为排他下界

COUNT 限制本次返回条数，不会替你保存游标。下一页若继续使用闭区间的最后ID，就会重新读到它；若直接把毫秒加一，又可能跳过同毫秒尚未读完的其他序号。使用排他完整ID可以避开这两类问题。

如果业务定义的是[start,end)，应把上界构造成“(end_ms-0”，而不是直接写end_ms；end_ms先转换成十进制文本再拼接完整ID。命令行中括号参数要加引号，客户端API则传入原始字符串，不应把shell引号一并传进去。

终点在任务创建时固定，避免每页都换成当前时间或一直使用加号上界，使历史回放不断追赶新写入。固定上界只是查询范围，不是跨多次请求的一致性快照；期间被删除或修剪的记录仍然可能消失。

把读取接入可恢复回放

# 语言无关的回放伪代码：Redis客户端和存储接口由项目实现。
lower = start_ms_as_string
upper = end_ms_as_string
while true:
    page = xrange(key, lower, upper, count=200)
    if page is empty:
        break
    for entry in page:
        # 必须先幂等提交业务效果，再保存已完成游标；错误时立即停止。
        apply_idempotently(entry.event_id, entry.fields)
        save_checkpoint(job_id, entry.id)
        # 保存完整ID，不只保存毫秒部分。
        lower = "(" + entry.id
# 恢复时读取持久化游标，使用"("加完整ID；没有游标才使用start_ms。

伪代码强调两个状态：Stream读取位置和业务完成位置。只拉到一页就提前保存末条ID，页面处理中途失败时会跳过未完成消息。逐条完成后保存游标可减少重做范围，但如果业务成功后、游标落盘前进程退出，恢复仍可能重复执行，所以必须让业务效果幂等。

event_id 应由业务定义稳定的唯一性范围，必要时组合来源或租户，避免不同事件意外共用去重键。如果业务效果与检查点位于同一事务存储，可设计为同一事务提交；涉及外部服务时需采用其幂等接口或可靠投递机制。单靠XRANGE无法保证“恰好一次”。

XRANGE不会因为你读过记录而修改消费者组的待确认列表，也不会自动ACK。历史重算通常使用独立回放任务进度，避免把消费组当前位置随意改动影响正常消费者。读取异常时停止并保留上一个已完成ID，不能把网络错误当成空列表结束。

保留期与兼容问题

为什么范围正确却返回空？

先确认键、数据库和边界对应的时间语义，再检查Stream数据是否已经删除或修剪。空结果只说明这次查询没有返回记录，不能证明历史事件从未存在。需要长期完整回放时，应配合满足保留要求的归档方案。

哪些版本支持括号排他边界？

排他范围从Redis 6.2开始支持。更早版本需要按完整ID规则计算后继，包含序号溢出的处理；不要只给毫秒加一。实际应优先采用客户端已支持的正确边界处理方式。

COUNT是不是越大越快？

大批量会增加单次响应体积和应用处理负担。先选择业务可承受的批量，并结合每条事件大小、处理耗时及失败恢复成本调整。COUNT是条数上限，不是响应字节上限。

可以直接把整页返回值当字段字典吗？

返回结果包含多个事件，每个事件都有完整ID和字段值集合。客户端可能封装为不同对象，应逐条解析；游标取事件ID，不能用业务字段event_id替代Stream ID。