Redis XADD MAXLEN 怎样控制 Stream 的近似长度

Redis Stream 持续接收消息时，最直接的长度控制方式不是另起一个定时清理任务，而是在写入命令 XADD 中带上 MAXLEN。如果只需要“保留最近一段消息”，通常使用 MAXLEN ~ N；如果长度不能超过阈值，再使用精确形式 MAXLEN = N。

官方地址：https://redis.io/

实战建议：日志、埋点和短期事件流优先考虑 MAXLEN ~；需要严格控制保留条数时使用 MAXLEN =。LIMIT count 只限制本次裁剪的工作量，不是“最终保留 count 条消息”。

先把长度控制放到 XADD 写入点

XADD 会向 Stream 追加一条消息，也可以在追加时声明裁剪策略。这样，消息进入 Stream 的时机和旧消息淘汰的时机是一致的，应用不需要先写入、再额外发起一次清理命令。

下面的命令把 events 控制在约 1000 条附近，并让 Redis 自动生成消息 ID：

# 写入新事件，并在写入阶段把 Stream 控制在约 1000 条
redis-cli XADD events MAXLEN ~ 1000 * type login user_id 42

# 只读取当前长度，用于业务监控，不把它当作裁剪证明
redis-cli XLEN events

这里的 ~ 是关键。它告诉 Redis 可以采用近似裁剪策略，以较低的写入成本维持一个接近目标值的保留窗口。被淘汰的是较旧的 Stream 条目，因此这个写法适合只关心近期事件的场景。

用 MAXLEN ~ 设置近似上限

常见形式是：

# ~ 表示允许近似裁剪，1000 是目标长度而非绝对实时长度
redis-cli XADD events MAXLEN ~ 1000 * type purchase order_id A100

# = 表示要求精确裁剪，边界更严格但裁剪成本可能更高
redis-cli XADD events MAXLEN = 1000 * type purchase order_id A101

MAXLEN ~ 1000 的含义不是每次命令返回后长度都恰好等于 1000，而是允许 Redis 为了性能暂时保留少量超过目标的条目。随着后续写入继续发生，裁剪会继续在写入点进行，Stream 会围绕这个目标长度运行。

近似形式特别适合日志、指标、审计事件等“保留最近窗口即可”的数据。它避免每次写入都为严格边界支付相同的裁剪成本，但也意味着业务不能把 1000 当作绝对容量上限。

理解 LIMIT 只限制本次裁剪工作量

在支持该语法的 Redis 版本中，可以在裁剪条件后追加 LIMIT count。它控制一次 XADD 触发裁剪时，最多处理多少条待淘汰记录，用来限制单次写入的额外工作量。

# 每次追加时目标约为 1000 条，并限制本次近似裁剪的处理数量
redis-cli XADD events MAXLEN ~ 1000 LIMIT 100 * type heartbeat node-1

# LIMIT 100 不是“最终只保留 100 条”，仍然是 MAXLEN 负责定义目标长度
redis-cli XLEN events

因此，LIMIT 和 MAXLEN 的职责不同：

比较精确 MAXLEN 与近似 MAXLEN

两种形式的选择，本质上是“严格边界”和“写入吞吐”的取舍：

• MAXLEN = N：更适合有明确容量边界、需要严格限制保留量的场景。每次裁剪的边界更明确，但高频写入时要关注裁剪带来的额外开销。
• MAXLEN ~ N：更适合只需要近期窗口的日志、监控和事件数据。长度可能短时间高于 N，但通常能以更低成本完成持续写入。
• 不设置 MAXLEN：适合需要完整保留、由归档策略统一管理的 Stream；此时必须另行规划容量、持久化和删除策略。

如果消费者偶尔离线，裁剪还会影响它以后能否读到旧消息。MAXLEN 只负责保留策略，并不会理解你的业务是否已经确认某条消息；在消费者组场景中，要把消息保留窗口和重放需求一起评估。

一套可落地的选择顺序

1. 先问数据是否只需要最近窗口：如果需要，优先把 MAXLEN 放进 XADD。
2. 再问目标长度是不是绝对容量：不是，就用 MAXLEN ~ N；是，就评估 MAXLEN = N。
3. 如果单次裁剪可能影响写入延迟，再考虑 LIMIT count，但不要把它当成最终保留数量。
4. 最后检查消费者离线和重放需求：旧消息一旦被裁剪，后续读取就不能再依赖它。

例如，普通业务事件只保留近期窗口，可以从下面的形式开始：

# 以近似长度控制写入压力，适合只关心近期事件的 Stream
redis-cli XADD app:events MAXLEN ~ 50000 LIMIT 500 * event order_created order_id 10086

# 如果容量必须严格受控，再把 ~ 改成 = 并重新评估写入延迟
redis-cli XADD app:events MAXLEN = 50000 * event order_created order_id 10087

常见问题

MAXLEN ~ 1000 会不会永远超过 1000？

它允许近似裁剪，因此短时间可能多保留一些条目。它不是绝对容量保证；若必须严格不超过阈值，应考虑精确的 MAXLEN =。

LIMIT 100 是不是只保留 100 条？

不是。LIMIT 限制当前裁剪动作的处理量，目标长度仍由 MAXLEN 决定。

XADD MAXLEN 和 XTRIM 应该怎么选？

希望“写入时顺便维护长度”时用 XADD 的 MAXLEN；需要把裁剪作为独立维护任务执行时，再考虑单独使用 XTRIM。两者都可能淘汰旧消息，消费者重放需求不能省略。

总结

Redis XADD 的 MAXLEN 是控制 Stream 增长的入口。MAXLEN ~ N 用近似边界换取更平滑的写入成本，MAXLEN = N 提供更严格的长度控制，LIMIT count 则只负责限制一次裁剪的工作量。先明确数据保留窗口和消费者重放要求，再决定使用哪一种组合。