Redis XADD 怎样限制流长度并保留最新消息

在每次写入时使用 XADD 键 MAXLEN = 数量 * 字段 值，就能追加消息并裁剪较旧条目。若允许条目数略高于目标值，可把 = 改为 ~。要严格保留至多 N 条，使用精确裁剪，并确保所有写入方采用一致策略。

“最新”指 Stream ID 较大的条目，不是消息里名叫 created_at 的业务字段。本文用独立演示键展示命令和预期含义，命令未在本文环境执行，文中的结果均为语义推导。

官方地址：https://redis.io/docs/latest/commands/xadd/

准备一个独立的 Stream 实验键

准备已安装 redis-cli、能够连接的实验 Redis，以及一个自己独占、当前不存在的键。下面采用本机默认连接；远端连接参数按实际环境设置，不把口令写进示例。将键名后缀替换成自己的唯一标识，整组命令在同一个 Bash 会话中执行。

# 设置当前实验使用的独占键名，不复用业务键
STREAM_KEY='demo:article:xadd-cap:my-unique-suffix'
# 预期为 0；若不是 0，换一个不存在的键名再继续
redis-cli EXISTS "$STREAM_KEY"

本文基本 XADD/MAXLEN 写法适用于支持 Streams 的 Redis 5.0 及后续版本；后文 LIMIT 属于 Redis 6.2 起的选项。示例不使用新版本的消费组引用策略参数，避免把最新文档的完整语法误当成旧版本都支持。

用 MAXLEN 精确保留最近三条记录

先连续写四条演示消息，每次都携带 MAXLEN = 3。星号交给 Redis 生成消息 ID，在 Shell 中加引号，避免被文件名通配展开。字段 seq 只帮助人识别样例，不参与服务端裁剪排序。

# 每次追加同时应用最多三条的精确长度策略
redis-cli XADD "$STREAM_KEY" MAXLEN = 3 '*' seq 1 event opened
redis-cli XADD "$STREAM_KEY" MAXLEN = 3 '*' seq 2 event edited
redis-cli XADD "$STREAM_KEY" MAXLEN = 3 '*' seq 3 event saved
redis-cli XADD "$STREAM_KEY" MAXLEN = 3 '*' seq 4 event closed

在独占实验键、四次命令均成功且没有其他写入或删除的前提下，第四次完成后预期保留 seq 为 2、3、4 的三条消息。第一次只有一条时不会补齐到三条；MAXLEN 是上限，不是必须维持的固定长度。

XADD 返回的是新条目的 ID，不是裁掉多少条，也不是当前长度。客户端要检查命令是否成功，不能把接收到一个字符串等同于业务消费已经完成。请求超时也不能直接推定未写入；生产端重试与去重需要另有设计。

读懂 XLEN 和消息 ID 的含义

# 查看当前条目数，独占样例的预期值为 3
redis-cli XLEN "$STREAM_KEY"
# 按 ID 从小到大列出当前保留消息
redis-cli XRANGE "$STREAM_KEY" - +
# 反向查看最新两条，参数顺序是上界加号、下界减号
redis-cli XREVRANGE "$STREAM_KEY" + - COUNT 2

这里三条命令分别回答“剩多少”“留下谁”“最近两条是什么”。自动生成的实际 ID 取决于服务端，不能拿某个固定时间戳当标准答案。XREVRANGE 的预期字段顺序是 seq 4、seq 3；若有并发写入，后续读取反映的是读取时的流状态，不是前一次写入的冻结快照。

假如后来写入一条业务时间较早的补录记录，但它得到更大的 Stream ID，这条补录仍位于流尾部。需要按业务事件时间保留数据的需求，不能只靠 MAXLEN 的条数策略实现。单条消息可能很大，限制条目数也不等于给内存字节数设置了上限。

改用近似裁剪时允许长度浮动

消息量较大且可以接受数量浮动时，可以考虑近似裁剪。它利用内部节点批量释放的特点减少细粒度处理，但不承诺每次写完恰好等于阈值。不要用“三条的小样例”去假设内部节点刚好也以三条为单位。

# 示例配置：允许近似保留约一万条，波浪号作为字面参数传入
redis-cli XADD "$STREAM_KEY" MAXLEN '~' 10000 '*' seq 5 event sampled
# Redis 6.2 起可给近似裁剪限制单次工作量，此处上限为一千条
redis-cli XADD "$STREAM_KEY" MAXLEN '~' 10000 LIMIT 1000 '*' seq 6 event sampled
# 观察实际数量，不能将大于一万直接判为命令失效
redis-cli XLEN "$STREAM_KEY"

以上是在同一个小实验键上展示参数，原有条目很少，不会凭空产生一万条。LIMIT 约束一次近似裁剪的工作量；它不是最终保留长度。对已经堆积很多消息的流，一次近似裁剪还可能因工作量限制而留下更多积压。不要把 LIMIT 和精确裁剪混搭成通用模板。

把保留策略放进每个生产者

MAXLEN 是这次命令的参数，不是给键永久设置的属性。一个生产者带上限，另一个直接执行普通 XADD，后者仍能把长度推高。工程上应在共享写入方法中统一参数，并明确是否允许其他入口写入同一个 Stream。

对已经存在的积压，可以单独使用 XTRIM；它不追加消息。下面仍只针对演示键，执行后会永久移除较旧载荷。

# 单独应用精确裁剪，不追加条目；返回值是移除条目数
redis-cli XTRIM "$STREAM_KEY" MAXLEN = 3
# 用长度和保留内容分别理解裁剪结果
redis-cli XLEN "$STREAM_KEY"
redis-cli XRANGE "$STREAM_KEY" - +

有消费组时还要区别“消息载荷”与“待确认引用”。默认兼容行为不会因为消息未确认就自动保住载荷：较旧条目可以被裁剪，而 PEL 中仍可能留着引用。因此“最新 N 条”不等于“每个消费者至少成功处理一次”，更不能据此承诺不丢未消费消息。

Redis 8.2 起提供 KEEPREF、DELREF、ACKED 等引用策略；若采用只裁剪所有消费组都已确认消息的策略，保留数量也可能受未确认积压影响。需要这种约束时，应按服务器版本和消费组设计单独选择，不能一边承诺绝对长度上限，一边无条件承诺慢消费者的数据都保留。

清理实验键并回答常见问题

完成演示后，只删除自己独占的实验键。若已把变量改成业务键，先停止清理；本文不需要清空数据库，也不涉及其他键。

# 仅清理本次独占演示键，删除后该实验流及其剩余消息不再存在
redis-cli DEL "$STREAM_KEY"
# 去掉当前 Shell 的演示变量
unset STREAM_KEY

没有新写入时，会自动按 MAXLEN 继续清理吗？

不会把之前的一次 XADD 参数变成定时任务。需要主动应用长度策略时，可以再次带参数写入，或对目标流执行 XTRIM。

想保留最新一条，阈值能写 1 吗？

可以采用 MAXLEN = 1。前提仍是所有写入都遵守这一策略；别用近似裁剪来要求每次只能留一条。

MAXLEN 0 能当成禁用裁剪吗？

不能。零是长度阈值，不是关闭开关。要保留数据就给出符合业务的正数；不指定 MAXLEN 才是省略这次长度裁剪策略。

为什么 XLEN 很小，内存却没有按条数成比例下降？

条目载荷大小、内部结构和消费组引用都会影响内存。长度统计不能直接代表进程内存，也不能替代容量估算。

语法依据：XADD 官方文档说明写入和裁剪参数，XTRIM 官方文档说明独立裁剪与近似工作量限制。本文示例键、事件字段和保留方案为原创演示。