Redis Stream是专门为消息队列场景设计的数据结构，每条消息都有一个唯一的ID。当我们需要从流中读取某一段时间范围内、或者某一段ID区间内的消息时，XRANGE命令就是最直接的解决方案。它不依赖消费者组，可以直接按ID区间扫描消息，非常适合消息回溯、日志检索和分页遍历这类需求。
一、理解消息ID的结构是使用XRANGE的前提
Redis Stream中的每条消息ID由两部分组成，格式为毫秒时间戳-序列号，例如1626847600000-5。前半部分是消息生成时的服务器毫秒时间戳，后半部分是同一毫秒内的序列号，用于区分同一毫秒内插入的多条消息。ID在同一个流内是严格递增的，这是XRANGE能够按范围查询的基础。
当我们执行XADD写入消息时，可以自己指定完整的ID，也可以让Redis自动生成。自动生成时Redis会保证ID单调递增：如果当前时间戳小于流中已有消息的时间戳，Redis会用已有消息的ID时间戳部分加一来保证唯一性。理解这一点很重要，因为XRANGE的范围本质上就是基于这个递增顺序做二分查找，效率非常高，时间复杂度为O(log N)定位起点加上返回元素数量。
需要特别注意的是，ID的两个部分缺一不可。如果只写时间戳部分不写序列号，Redis会自动补全：作为起始ID时补为1626847600000-0，作为结束ID时补为1626847600000-18446744073709551615，也就是该毫秒内最大的序列号。这个规则在很多按时间查询的场景中非常实用。
二、XRANGE基本语法与特殊符号
XRANGE的基本语法为：XRANGE key start end [COUNT count]。其中start是起始ID（包含），end是结束ID（也包含），这是一个闭区间查询。除了写具体的ID之外，还支持两个特殊符号：减号-代表流中最小的ID，加号+代表流中最大的ID。
比如查询整个流的所有消息，可以直接写XRANGE mystream - +。如果只想看最早的前10条，加上COUNT选项即可：XRANGE mystream - + COUNT 10。COUNT是一个非常实用的选项，尤其在遍历大流量流数据时，配合游标式迭代可以避免单次返回过多数据阻塞Redis。
127.0.0.1:6379> XADD mystream * name alice
"1626847600000-0"
127.0.0.1:6379> XADD mystream * name bob
"1626847600000-1"
127.0.0.1:6379> XRANGE mystream - +
1) 1) "1626847600000-0"
2) 1) "name"
2) "alice"
2) 1) "1626847600000-1"
2) 1) "name"
2) "bob"
127.0.0.1:6379> XRANGE mystream - + COUNT 1
1) 1) "1626847600000-0"
2) 1) "name"
2) "alice"
按时间范围查询是XRANGE最常见的用法之一。例如想查询某个毫秒时间戳1626847600000之后的所有消息，可以写成XRANGE mystream 1626847600000 +，此时起始ID会被补全为1626847600000-0。反过来查询某时间之前的消息则写成XRANGE mystream - 1626847600000。
三、EXCLUSIVE排除边界与迭代遍历的技巧
从Redis 6.2开始，XRANGE支持EXCLUSIVE选项，用于将边界ID从包含改为排除。写法是在ID后面加上(左括号，例如XRANGE mystream (1626847600000-0 +表示返回严格大于该ID的消息，不包含ID本身。这个语法乍看有些奇怪，但它是实现无缝迭代的关键。
迭代遍历一个巨大流的经典模式是这样的：第一次用XRANGE key - + COUNT 100取100条，拿到最后一条消息的ID，下一次查询就从这条ID的下一个位置开始。在没有EXCLUSIVE之前，只能把上次的最后一条ID拆开加一，手动计算下一个ID，比较繁琐且容易出错。有了排除语法后直接写XRANGE key (上次最后ID + COUNT 100即可。
# 第一轮迭代
127.0.0.1:6379> XRANGE mystream - + COUNT 2
1) 1) "1626847600000-0"
2) 1) "name"
2) "alice"
2) 1) "1626847600000-1"
2) 1) "name"
2) "bob"
# 第二轮迭代，从上轮最后一条之后继续（排除边界）
127.0.0.1:6379> XRANGE mystream (1626847600000-1 + COUNT 2
1) 1) "1626847600000-2"
2) 1) "name"
2) "carol"
如果Redis版本低于6.2，也可以自己实现ID递增逻辑：取出最后一条ID后，序列号加一即可作为下一轮的起始ID，因为序列号溢出的情况极其罕见。此外还可以用XREAD配合$符号做增量读取，但XREAD更适合实时消费，XRANGE更适合历史数据回溯，两者定位不同。
四、在Java项目中使用XRANGE查询消息
在Java中，如果使用Jedis客户端，可以直接调用xrange方法，传入起始和结束ID字符串。下面是一个按时间范围查询并分页遍历的完整示例。
import redis.clients.jedis.Jedis;
import redis.clients.jedis.resps.StreamEntry;
import java.util.List;
public class XRangeDemo {
public static void main(String[] args) {
try (Jedis jedis = new Jedis("127.0.0.1", 6379)) {
String streamKey = "mystream";
String start = "-"; // 最小ID
String end = "+"; // 最大ID
int batchSize = 100;
while (true) {
// 每次最多取100条
List<StreamEntry> entries = jedis.xrange(streamKey, start, end, batchSize);
if (entries == null || entries.isEmpty()) {
break;
}
for (StreamEntry entry : entries) {
System.out.println("ID: " + entry.getID()
+ " 字段: " + entry.getFields());
}
// 使用排除语法，从最后一条之后继续
start = "(" + entries.get(entries.size() - 1).getID();
if (entries.size() < batchSize) {
break; // 已经取完
}
}
}
}
}
这段代码的核心在于游标的更新：每轮迭代结束后，把最后一条消息的ID加上左括号变成排除型起始ID。如果取回的数量小于批次大小，说明已经遍历到流末尾，可以直接退出循环。这种模式的优点是不会一次性把整个流加载进内存，对百万级消息量的流也能平稳遍历。
如果使用Spring Data Redis，可以通过StreamOperations的range方法实现同样功能，它接收一个Range对象来描述区间，代码更加简洁，底层逻辑与上面完全一致。
五、XRANGE与XREVRANGE的区别及注意事项
XREVRANGE是XRANGE的反向版本，语法为XREVRANGE key end start，注意两个参数的顺序反过来了，先写大ID再写小ID，返回结果也是按ID从大到小排列。它最常见的用途是获取流中最近的消息，比如XREVRANGE mystream + - COUNT 5可以拿到最新的5条消息，做消息预览或快速查看最近日志时特别方便。
使用XRANGE时还有几点需要注意。首先，如果指定的范围内没有消息，命令会返回空数组而不是报错。其次，起始ID大于结束ID同样返回空数组。另外，XRANGE返回的消息数量上限受MAXIMUM限制，官方建议配合COUNT使用，避免一次查询百万级数据造成Redis响应变慢。最后，XRANGE是只读命令，不会消费或删除消息，也不会影响消费者组的读取进度，可以放心地重复查询同一范围的数据。
综合来看，XRANGE配合ID结构、COUNT选项和EXCLUSIVE排除语法，能够覆盖绝大多数按范围读取消息的需求。在实现消息回溯、故障排查、数据补录这类功能时，它比自行维护索引或者用LIST结构模拟要简洁可靠得多。
Redis XRANGERedis Stream消息范围查询修改时间：2026-09-12 23:34:42