MAXLEN 怎样限制 Stream 保留长度

Redis Stream 可以在写入时使用 XADD key MAXLEN = N ...，或对已有流执行 XTRIM key MAXLEN = N，裁掉较小 ID 的旧条目，把长度控制在指定数量内。若使用 MAXLEN ~ N，则是以效率换取长度余量的近似裁剪，不能把 N 当作严格上限。

官方地址：https://redis.io/docs/latest/commands/xtrim/；写入参数入口：https://redis.io/docs/latest/commands/xadd/。本文解释基础 MAXLEN 语义，命令均为未在本机执行的原创示例；固定 ID 和预期状态仅用于独立测试键。

背景：保留最近消息需要独立的裁剪规则

事件流持续接收设备状态、任务通知或审计线索时，业务通常只需要一个有限回放窗口。MAXLEN 解决的是条目数量保留问题：消息仍可写入，但较旧记录会按照裁剪规则退出流。它不是队列满后拒绝新消息的开关，也不是消息确认指令。

例如只保留最近一万条，必须先接受“慢消费者可能错过已裁剪记录”的业务后果。涉及必须完整处理的订单、结算或长期审计时，应另有可靠存储、积压治理及恢复方式，不能只靠一个长度阈值承诺数据永久可追溯。

旧做法的问题是把长度、时间和确认混为一谈

给键设置过期时间，会影响整个键的生命周期，并不等于逐条淘汰旧记录。消费组 XACK 处理确认状态，也不等于删除消息正文。MAXLEN 负责流条目数；这些动作必须由各自目标决定。

另一个常见问题是先 XLEN，再在客户端判断是否 XTRIM。多个生产者并发时，两次命令之间可能又有写入；而且增加了往返。把裁剪参数放进每次 XADD，可在同一命令中表达写入与裁剪。所有生产者仍需遵守相同规则，单个生产者的 MAXLEN 不会成为流永久保存的全局配置。

新规则：精确上限与近似目标分别使用

# 写入时精确保留至多三条；星号加引号以免被 shell 展开。
redis-cli XADD demo:retention:exact MAXLEN = 3 '*' event sample-a

# 独立裁剪已有 Stream，返回本次删除条目数。
redis-cli XTRIM demo:retention:exact MAXLEN = 3

# XLEN 读取当前条目数，不是内存字节数。
redis-cli XLEN demo:retention:exact

= 表示精确裁剪。对普通基础裁剪而言，已有长度不足阈值时不会填充消息；超过阈值时保留较新的条目。~ 表示近似目标，Redis 可按内部宏节点成块处理，从而减少细粒度删除工作；实际长度可能超过目标。

阈值不衡量消息大小。同样一万条，短状态字段和大段文本的内存需求可能相差很大；XLEN 也不会告诉你存储占用了多少字节。容量规划应同时限定单条负载并观察实际内存。

用写入裁剪和独立裁剪对照示例

# 仅在全新测试键上运行；每次写入都携带相同精确裁剪规则。
redis-cli XADD demo:retention:sample MAXLEN = 3 1-0 event alpha
redis-cli XADD demo:retention:sample MAXLEN = 3 2-0 event beta
redis-cli XADD demo:retention:sample MAXLEN = 3 3-0 event gamma
redis-cli XADD demo:retention:sample MAXLEN = 3 4-0 event delta

# 无其他并发写入时，观察剩余长度和 ID 范围。
redis-cli XLEN demo:retention:sample
redis-cli XRANGE demo:retention:sample - +

在全新键且没有并发写入的条件下，上述四次写入的预期保留条目为 2-0、3-0、4-0，长度为 3。本文没有实际运行这些命令。若复用旧键，固定 ID 可能低于最后一个 ID 而被拒绝，所以不能把既有键套进这个预期。

XADD 返回新条目的 ID，XTRIM 返回本次删除数，这两个返回值不能用同一种方式解释。独立 XTRIM 适合调整已有积压或作为周期维护，但它只在执行时起效，后续无裁剪写入仍可能让流增长。

# 近似保留适合允许少量长度偏差的场景，不能当作严格上限。
redis-cli XADD demo:retention:approx MAXLEN '~' 10000 '*' event sample

# Redis 6.2+：限制本次近似裁剪的工作量，可能需要后续继续裁剪。
redis-cli XTRIM demo:retention:approx MAXLEN '~' 10000 LIMIT 1000

# 读取当前状态，裁剪返回零并不自动说明命令失败。
redis-cli XLEN demo:retention:approx

近似模式的小流可能因为尚不能整块回收而暂时不删除。加入 LIMIT 后，单次工作量受到限制，积压很大时更不能假设一次就达到目标。LIMIT 不是“最终流长度”，也不要为了追求立即降到阈值在业务高峰无界循环调用。

兼容注意：消费组引用与版本选项

MAXLEN 基础功能与 LIMIT、消费组引用策略来自不同版本能力，客户端库的参数支持也应分别确认。LIMIT 在 Redis 6.2 起提供，本文只把它用于近似裁剪示例；旧环境不支持时，不能静默把完整命令当成功。

最新命令文档还列出 KEEPREF、DELREF、ACKED 等引用策略。KEEPREF 保留消费组待处理引用，正文被裁剪后可能出现只有 ID 引用而无消息内容的情况；DELREF 会连相关引用一起移除；ACKED 则限制为所有消费组都读取并确认的条目。使用这些扩展前需核对服务端版本，不能把最新语法直接套到旧 Redis。

在 ACKED 一类附加条件下，未确认消息会限制可删除范围，长度目标可能无法兑现。因此“严格限制容量”和“绝不淘汰未确认内容”不是靠一个选项就能同时保证的承诺；生产者限流、消费积压处置和外部归档也要参与设计。

采用建议：按恢复窗口和写入量设置阈值

可以用“峰值每秒条目数 × 允许的消费者恢复秒数”估算保留数量，再为突发与重试留余量。这是容量估算方法，不是 Redis 对时长的保证：写入量波动时，同样长度对应的历史时间窗口也会变化。

设置 MAXLEN 后不再写入，还会自动裁剪吗？

不会因为过去某次命令带了参数而自动运行后台裁剪。已有流需要执行新的裁剪命令，或在后续写入中继续携带规则。

为什么 XTRIM 返回零？

可能长度本来就不超标，也可能近似模式或引用策略没有允许本次删除。结合模式和当前状态判断，不能只看一个计数。

裁剪会让键立刻等比例释放内存吗？

条目数减少与进程内存变化并非一一对应。内部组织、待处理引用和分配器行为都会影响观察值，因此不能按删除数量直接推算内存下降比例。

参考资料：XTRIM https://redis.io/docs/latest/commands/xtrim/；XADD https://redis.io/docs/latest/commands/xadd/；XLEN https://redis.io/docs/latest/commands/xlen/。