在维护基于Redis Stream的消息系统时，运维和开发人员最常问的问题之一就是：某个Stream里到底堆积了多少条消息？数量是评估消费是否积压、内存占用是否合理的基础指标。Redis提供了专门的XLEN命令来回答这个问题，它返回指定Stream中的消息条目数量，执行速度极快，即使在流非常庞大的情况下也能瞬间给出结果。这篇文章将围绕XLEN的语法、返回值、底层实现以及实际开发中的使用细节展开，帮助你把这个看似简单的命令用得明明白白。
XLEN命令的基本语法与使用方法
XLEN的语法非常简洁，只接受一个参数，即Stream的键名。完整格式为XLEN key，其中key是Stream类型键的名称。命令执行后返回一个整数，表示该Stream中当前存在的消息条目总数。
我们先通过redis-cli实际操作一遍，加深理解。首先创建一个Stream并向其中添加几条消息，然后执行XLEN查看数量：
127.0.0.1:6379> XADD mystream * name alice age 25 "1718000000000-0" 127.0.0.1:6379> XADD mystream * name bob age 30 "1718000000001-0" 127.0.0.1:6379> XADD mystream * name carol age 28 "1718000000002-0" 127.0.0.1:6379> XLEN mystream (integer) 3 127.0.0.1:6379> XLEN not Exist (integer) 0
从上面的输出可以看到，添加了三条消息后，XLEN返回3。值得注意的是最后一条命令，当我们对一个不存在的键执行XLEN时，命令并不会报错，而是返回0。这是因为Redis把不存在的Stream视为空流来处理，这个特性在脚本和程序中很有用，省去了先判断键是否存在的步骤。
如果对一个非Stream类型的键执行XLEN，比如对一个String或者List执行该命令，Redis会抛出WRONGTYPE错误。所以在业务代码中，如果键的类型可能被其他模块复用，最好做好异常捕获。另外，XLEN统计的是流中所有消息的总数，它不区分消息是否已被某个消费组读取，这一点后面会详细展开。
XLEN的返回值规则与特殊情况处理
XLEN返回的数字并不是一个一成不变的值，它会随着消息的增加和删除而变化。理解这些变化规则，对准确解读监控数据至关重要。
第一种情况是消息被显式删除。Stream支持通过XDEL命令删除指定ID的消息，删除后XLEN的计数会立即减少。比如前面的mystream中有3条消息，执行XDEL mystream 1718000000001-0删除中间那条后，再执行XLEN就会返回2。这与List的LREM行为类似，是即时生效的。
第二种情况是使用XTRIM裁剪流。生产环境中为了控制内存，经常需要限制Stream的长度，常见做法是定期执行XTRIM mystream MAXLEN 10000，只保留最近的一万条消息。裁剪掉的消息同样不会计入XLEN的结果。还有一种近似裁剪写法XTRIM mystream MAXLEN ~ 10000，使用波浪线表示允许一定误差以换取更高性能，这种情况下实际保留的消息数可能略多于限制值，XLEN的返回值也会相应体现。
127.0.0.1:6379> XADD bigstream * field value "1718000001000-0" 127.0.0.1:6379> XTRIM bigstream MAXLEN 10000 (integer) 0 127.0.0.1:6379> XLEN bigstream (integer) 1
第三种情况是消费组的存在与否对XLEN没有影响。消费组只是记录消费进度的元数据，消息本体依然留在Stream中。即使所有消费组都确认消费完毕（执行了XACK），消息也不会被删除，XLEN返回值保持不变。许多初学者误以为XLEN能查到未消费的消息数量，这是最常见的误区。要获取每个消费组的待处理数量，应该使用XPENDING命令，它能看到该组已读取但尚未确认的消息；而判断整体积压，则需要结合消费者最后一次读取的ID与流的最新ID来计算。
为什么XLEN的时间复杂度是O(1)
很多命令在统计数量时需要遍历数据，比如LLEN对List是O(1)，而ZCARD对有序集合也是O(1)，Redis在设计上倾向于把这类高频查询做成常数时间。XLEN同样如此，官方文档标注其时间复杂度为O(1)。
实现层面的原因在于，Redis为每个Stream对象内部维护了一个基数形态的条目计数（内部结构中的length字段）。每执行一次XADD，计数加一；每执行一次XDEL或XTRIM裁剪，计数相应减少。XLEN执行时只是直接读取这个字段并返回，完全不需要遍历底层的基数树（rax tree）节点。因此无论流里有一千条还是一亿条消息，XLEN的耗时都几乎相同。
这个特性让XLEN非常适合放进高频率的监控采集循环中。比如每秒采集一次所有核心Stream的XLEN值并写入时序数据库，配合告警规则，当消息数量超过阈值时触发告警，可以及时发现消费停滞的问题。由于命令本身开销极小，这种采集对Redis性能的影响可以忽略不计。
在客户端代码中调用XLEN的实践示例
实际项目中很少直接在redis-cli里敲命令，更多是通过编程语言的客户端库调用。下面给出Python和Java两种常见语言的示例。
Python使用redis-py库时，调用方式非常直观。下面的代码演示了添加消息后查询数量，并对异常做了基本处理：
import redis
# 连接Redis，decode_responses=True让返回值为字符串
r = redis.Redis(host='127.0.0.1', port=6379, decode_responses=True)
# 向Stream添加两条消息，*表示由Redis自动生成ID
r.xadd('order:stream', {'order_id': '1001', 'amount': '59.9'})
r.xadd('order:stream', {'order_id': '1002', 'amount': '128.0'})
# 获取Stream中的消息数量
count = r.xlen('order:stream')
print(f'当前消息数量: {count}')
# 对不存在的键执行xlen返回0，不会抛异常
empty_count = r.xlen('not:exist:stream')
print(f'不存在的流数量: {empty_count}')
Java使用Jedis客户端时，写法略有不同但思路一致。下面是一个包含连接管理和关闭的完整示例：
import redis.clients.jedis.Jedis;
import redis.clients.jedis.StreamEntryID;
import java.util.HashMap;
import java.util.Map;
public class StreamLenDemo {
public static void main(String[] args) {
Jedis jedis = new Jedis("127.0.0.1", 6379);
try {
// 构造消息字段
Map<String, String> fields = new HashMap<>();
fields.put("order_id", "2001");
fields.put("amount", "88.0");
// 添加消息，ID由Redis自动生成
jedis.xadd("order:stream", new StreamEntryID(), fields);
// 获取消息数量
long len = jedis.xlen("order:stream");
System.out.println("当前消息数量: " + len);
} finally {
jedis.close();
}
}
}
需要注意的一点是，如果使用Spring Data Redis，则通过RedisTemplate.opsForStream().size(key)来获取长度，方法名不再叫xlen，但底层发出的命令是同一个。不同客户端封装方式不同，查阅文档时认准底层命令名即可。
XLEN与其他Stream统计命令的对比
Redis Stream生态中有多个命令能提供统计信息，XLEN只是其中最简单的一个。弄清楚它们各自的定位，才能在合适的场景选用合适的工具。
XINFO STREAM key返回流的完整概览信息，包括长度、基数树节点数、最后一条消息的ID、第一个和最后一个消息的内容、以及关联的消费组数量等。它的输出是嵌套数组形式，信息量远大于XLEN，适合做深度诊断。如果只想快速拿一个数字，XLEN显然更轻量。
XRANGE和XREVRANGE按ID范围检索消息，本身不做计数，但如果配合范围参数可以间接判断某个时间段内的消息情况。把它们的结果交给应用层统计会比较繁琐，一般不用于单纯计数。XPENDING则是站在消费组视角，查看已读未确认的消息详情，包括数量、每个消费者的待处理条数以及最长阻塞时间等，是排查消费者故障的关键命令。
| 命令 | 作用 | 复杂度 | 典型场景 |
|---|---|---|---|
| XLEN | 统计流中消息总数 | O(1) | 监控采集、容量评估 |
| XINFO STREAM | 查看流的完整元信息 | O(1) | 深度诊断、状态检查 |
| XPENDING | 查看消费组待确认消息 | O(N) | 排查消费积压与故障恢复 |
| XTRIM | 裁剪流，控制长度 | 近似O(1)或O(N) | 内存控制、定期清理 |
总结来看，XLEN是一个小而美的命令：功能单一、速度极快、语义清晰。日常用它做消息量监控非常合适，但要牢记它统计的是流中现存消息总数，与消费状态无关。监控消费是否积压时，应将XLEN的结果与消费组的读取进度结合起来分析，必要时配合XPENDING定位具体卡住的消费者。掌握这些搭配用法，才能把Redis Stream的运维工作做扎实。
Redis XLENRedis StreamRedis命令修改时间：2026-09-15 20:02:50