*Redis XTRIM 命令
截断 Stream 到指定长度或最小 ID。删除最旧的消息。
*语法
XTRIM key MAXLEN | MINID [= | ~] threshold [LIMIT count]
*参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | String | 是 | Stream 键名 |
| MAXLEN | 标志 | 是 | 按最大长度截断 |
| MINID | 标志 | 是 | 按最小 ID 截断（Redis 6.2+） |
| = | 标志 | 否 | 精确截断 |
| ~ | 标志 | 否 | 近似截断（更快） |
| threshold | Integer/String | 是 | MAXLEN 时为长度，MINID 时为 ID |
| LIMIT | Integer | 否 | 每次迭代最多删除数量 |
*返回值
| 条件 | 返回值 |
|---|---|
| 截断完成 | 删除的消息数量（Integer） |
*时间复杂度
O(N)，N 为删除的消息数量。
*示例
> XADD mystream * temp 20
> XADD mystream * temp 21
> XADD mystream * temp 22
# 截断到最多 2 条
> XTRIM mystream MAXLEN 2
(integer) 1
> XLEN mystream
(integer) 2
# 近似截断（更快）
> XTRIM mystream MAXLEN ~ 1000
*常见错误
| 错误 | 原因 | 解决 |
|---|---|---|
| ERR syntax error | MAXLEN 和 MINID 同时指定或语法错误 | 确保只使用 MAXLEN 或 MINID 之一 |
| WRONGTYPE Operation against a key holding the wrong kind of value | 对非 Stream 类型执行 XTRIM | 使用 TYPE 命令确认 key 类型为 stream |
| ERR Invalid stream ID | MINID 时 threshold 不是合法的 Stream ID | 使用正确的时间戳-序列号格式 |
| ERR value is not an integer | MAXLEN 时 threshold 传入非整数 | 确保 threshold 为整数表示最大长度 |
*最佳实践
- 内存控制：定时任务 XTRIM Stream，防止消息无限增长。
XADD 时自动截断：
XADD key MAXLEN ~ 1000 * field value在添加时自动截断，比事后 XTRIM 更高效。定时任务清理：使用 Cron 定时执行 XTRIM，防止 Stream 无限增长。
监控 Stream 长度：配合 XLEN 监控，接近阈值时触发预警或自动清理。
*5. 近似截断优先：生产环境优先使用 MAXLEN ~ 近似截断，获得更好的性能同时保持内存可控。
*FAQ
Q1: XTRIM 和 XDEL 有什么区别？ A: XTRIM 批量删除最旧消息（按长度或 ID）；XDEL 删除指定 ID 的单个/多个消息。
Q2: ~ 近似截断安全吗？ A: 安全。性能更好，可能略超限制但差距很小。绝大多数场景推荐 ~。
Q3: XTRIM 删除的消息还能恢复吗？ A: 不能。XTRIM 删除是永久性删除，无法恢复，执行前请确认数据不再需要。
Q4: XTRIM 和 LTRIM 有什么区别？ A: XTRIM 操作 Stream，按 MAXLEN/MINID 截断；LTRIM 操作 List，按索引范围保留。两者数据结构不同。
Q5: 为什么推荐使用 ~ 近似截断？ A: 精确截断需要逐条检查，性能差；近似截断批量删除，性能提升明显，且内存控制效果接近。