Redis 与缓存 / 知识点
Redis 开发常用命令速查
去重与集合运算
SSCAN key cursor [MATCH pattern] [COUNT count]用游标渐进获取大集合成员,适合离线处理和核对样本;COUNT 不保证每次返回固定数量,重复成员应在调用方做好幂等处理。
分批扫描集合成员
当 Redis Set 包含大量成员,需要分批核对、导出或执行离线处理时,使用 `SSCAN` 通过游标渐进读取,避免像 `SMEMBERS` 一样一次性返回整个集合。一次完整遍历从游标 `0` 开始,以服务端最终返回游标 `0` 结束。
基本语法
SSCAN key cursor [MATCH pattern] [COUNT count]| 参数 | 含义 | 约束或默认值 |
|---|---|---|
| `key` | 待扫描的 Set 键 | 必须是 Set 类型;不存在的键返回空集合 |
| `cursor` | 本轮扫描起点 | 首次传 `0`,后续传上次返回的游标 |
| `MATCH pattern` | 按 glob 模式筛选成员 | 可选;如 `tag:*`,不是正则表达式 |
| `COUNT count` | 建议本次扫描的工作量 | 可选,默认 `10`;不保证固定返回数量 |
`SSCAN` 返回两个部分:下一次使用的游标,以及本批成员数组。游标不为 `0` 时,即使本批成员为空,也必须继续扫描。
该命令从 Redis 2.8.0 开始支持。单次调用通常为 O(1),完整遍历为 O(N),其中 N 是集合成员数量。`COUNT` 是工作量提示,不是严格分页上限;紧凑编码的小集合可能一次返回全部成员。
可验证示例
前置条件:本机 Redis 服务已启动,已安装 `redis-cli`,并在隔离测试库中确认 `demo:sscan:guide` 尚不存在。下面先创建包含三个成员的集合,再筛选以 `tag:` 开头的成员。
# 仅在隔离测试库创建演示集合
redis-cli SADD demo:sscan:guide tag:alpha tag:beta misc
# MATCH 只过滤返回成员,COUNT 100 不是强制返回 100 个
redis-cli SSCAN demo:sscan:guide 0 MATCH 'tag:*' COUNT 100预期输出(小集合的一种可能结果):
(integer) 3
1) "0"
2) 1) "tag:alpha"
2) "tag:beta"第一条命令在键不存在时新增三个成员,因此返回 `3`。第二条返回两个匹配成员,不包含 `misc`。成员顺序不保证固定,实际游标和批次数也可能不同。
如果返回游标不是 `0`,应将其作为下一条 `SSCAN` 的 `cursor`,并保持原来的键名与筛选条件,直到返回游标为 `0`。不要把返回成员数量不足 `COUNT` 当作遍历完成。
游标与结果处理
实际批处理建议遵循以下顺序:
- 将游标初始化为 `0`,执行首次 `SSCAN`。
- 读取返回的成员并执行业务处理,同时保存返回游标。
- 对成员执行幂等操作,或使用持久化去重记录避免重复处理。
- 如果返回游标不为 `0`,继续使用该游标发起下一次调用。
- 只有返回游标为 `0`,才标记本轮遍历结束。
`MATCH` 是在扫描候选成员后应用的过滤条件,因此匹配较少时可能连续出现空批次。`SSCAN` 也不是基于固定偏移量的分页接口,不能使用页码代替游标,或自行对游标加一。
需要断点续扫时,可以在完成当前批次的处理后保存游标和处理进度。恢复后从保存的游标继续,但集合发生修改时不能保证恢复结果与原先完全一致;处理操作仍需支持重试和去重。
风险与恢复
- **重复成员**:同一成员在完整遍历中可能被返回多次。涉及计费、通知或数据迁移时,应使用成员 ID 实现幂等,不能简单地对每次返回结果累加。
- **并发修改**:遍历期间新增或删除的成员可能出现或被遗漏。始终存在于整个遍历期间的成员会被返回,但扫描不能替代一致性快照。需要精确核对时,应先获得稳定的数据副本。
- **类型错误**:对 String、List 等非 Set 键执行 `SSCAN` 会返回 `WRONGTYPE` 错误。先使用 `TYPE demo:tags` 核对类型,确认是 `set` 后再扫描。
- **性能波动**:增大 `COUNT` 通常能减少往返次数,但也可能增加单次响应大小和处理延迟。生产环境建议从 `COUNT 100` 等保守值开始,根据响应时间和吞吐调整。
- **误中断**:扫描无须显式关闭,也不会遗留服务端游标状态。若游标丢失,可以从 `0` 重新扫描,但必须重新执行去重或幂等检查。
演示结束后,仅在确认测试键确实由本次操作创建、没有其他用途时执行清理:
# 删除本次创建的临时演示集合
redis-cli DEL demo:sscan:guide预期输出:键仍存在时返回 `(integer) 1`,已不存在时返回 `(integer) 0`。`DEL` 不可直接撤销;误删业务键只能依赖已有备份或业务数据重建。
速查:`SSCAN` 的结束条件永远是**返回游标等于 `0`**,不是成员列表为空,也不是本批数量小于 `COUNT`。
SCARD key获取集合中的去重成员总数,适合跟踪实时标签或在线标识规模;只返回精确数量,不提供成员分布,超大基数估算可考虑 HyperLogLog。
查看集合基数 SCARD
需要统计 Redis Set 中有多少个不同成员时,使用 SCARD 直接获取精确基数。例如统计某个商品的去重标签数、活动参与用户数或在线标识数。它只返回成员数量,不读取完整成员列表,时间复杂度为 O(1)。
基本语法
SCARD keykey:目标集合的键名,必须指向 Set 类型;一次查询一个键。- 返回值:非负整数,表示集合内不同成员的总数。
- 键不存在时返回
0;键存在但不是 Set 类型时返回WRONGTYPE错误。 - 不支持成员筛选、条件过滤或近似计数参数。
SCARD 是只读命令,不会修改集合内容或重置键的过期时间。Redis Open Source 1.0.0 起支持该命令。
常用示例
以下示例在安装了 redis-cli、能够连接本地 Redis 的 Shell 中执行。使用独立的测试键 demo:tags,先清理旧数据,再验证重复成员不会增加基数。
# 仅清理测试键,确保结果不受旧数据影响
redis-cli --raw DEL demo:tags > /dev/null
# 三次传入成员,其中 vip 重复,只会新增两个成员
redis-cli --raw SADD demo:tags vip new vip
redis-cli --raw SCARD demo:tags
redis-cli --raw TYPE demo:tags预期输出:
2
2
set第一行 2 是 SADD 实际新增的成员数,第二行 2 是 SCARD 返回的当前集合基数,最后的 set 表示键类型正确。重复添加 vip 不会让数量变成 3。
在 Redis 交互终端中,也可直接执行 SCARD demo:tags,预期返回 (integer) 2。如果其他客户端同时修改集合,实际结果以命令执行时的集合状态为准。
返回结果与排查
| 结果 | 含义 | 处理方式 |
|---|---|---|
| 正整数 | 集合包含对应数量的不同成员 | 可直接用于去重数量统计 |
0 |
键不存在,或查询时集合没有成员 | 使用 EXISTS key 检查键是否存在 |
WRONGTYPE |
同名键存储的不是 Set | 用 TYPE key 检查实际数据类型 |
| 连接错误 | Redis 服务不可达或连接参数不正确 | 检查服务状态、地址、端口和认证配置 |
排查 WRONGTYPE 时,先检查键类型,不要为了让命令成功而直接删除或覆盖业务键。Redis 通常不会保留空 Set,因此删除最后一个成员后,SCARD 返回 0,EXISTS 通常也返回 0。
风险与边界
- 精确计数:
SCARD返回当前 Set 的实际成员数量,不是估算值;它不提供成员顺序、分布或具体内容。 - 性能:查询本身为 O(1),无需通过
SMEMBERS取出全部成员再计数。对大集合执行SMEMBERS可能产生较大的网络传输和客户端内存开销。 - 并发变化:单次
SCARD读取是原子命令,但连续多次查询之间,成员可能被其他客户端增删,不能据此推断数量始终不变。 - 内存成本:Set 必须保存实际成员。只需要近似统计海量去重标识且容许误差时,可考虑通过
PFADD写入 HyperLogLog,再用PFCOUNT查询;不能直接对普通 Set 键使用PFCOUNT。 - 数据安全:示例中的
DEL会删除原有测试键。生产环境查询只执行SCARD即可,不要复制清理命令到真实业务键。
速查:精确数量用 SCARD key;判断单个成员是否存在用 SISMEMBER key member;需要分批遍历成员时用 SSCAN。
排序与排行榜
ZADD key [NX | XX] [GT | LT] [CH] [INCR] score member [score member ...]按分值添加或更新有序集合成员,适合排行榜、优先级和时间索引;默认更新已有成员的分数,条件选项可控制新增或更新行为。
写入排序分值
需要向排行榜、任务优先级队列或时间索引写入分值时使用 ZADD。它可以一次添加多个成员,也可以更新已有成员的分值。每个成员在同一个有序集合中只能存在一次,分值变化后排序会自动调整。
基本语法
ZADD key [NX | XX] [GT | LT] [CH] [INCR] score member [score member ...]以上是语法示意,方括号表示可选部分,不需要原样输入。
key:目标有序集合的键名。键不存在时自动创建;键存在但类型不是有序集合时返回类型错误。score:成员的排序分值,使用双精度浮点数表示,可以是整数、小数或负数。member:成员标识,同一个有序集合中不能重复。[score member ...]:允许在一次命令中指定多组分值与成员。
默认情况下,已有成员会被更新为指定分值,而不是在旧分值上累加。分值从小到大排序;分值相同时,成员按字典序排列。
关键选项
| 选项 | 作用 | 使用边界 |
|---|---|---|
NX |
仅添加不存在的成员 | 已有成员不会更新 |
XX |
仅更新已有成员 | 不会创建新成员 |
GT |
仅当新分值大于旧分值时更新已有成员 | 不阻止添加新成员 |
LT |
仅当新分值小于旧分值时更新已有成员 | 不阻止添加新成员 |
CH |
返回实际发生变化的成员数量 | 包含新增和分值改变的成员 |
INCR |
将给定分值作为增量累加 | 每次只能指定一组 score member |
选项组合需要注意:NX、GT、LT 不能相互组合;NX 与 XX 互斥,GT 与 LT 互斥。XX 可以配合 GT 或 LT,实现只对已有成员进行条件更新。
例如,排行榜只允许分数上涨时,可以使用 GT;如果还要求成员必须已经存在,则使用 XX GT。
写入与验证
以下示例要求已连接测试 Redis 实例,且 demo:rank 原先不存在。使用 redis-cli --raw 可以得到便于阅读和核对的纯文本输出。
# 首次写入两名玩家的排行榜分值
redis-cli --raw ZADD demo:rank 100 alice 95 bob
# 更新 alice 的分值,并统计实际变化的成员数
redis-cli --raw ZADD demo:rank CH 110 alice
# 按分值从低到高读取成员及其分值
redis-cli --raw ZRANGE demo:rank 0 -1 WITHSCORES预期输出(依次对应三条命令):
2
1
bob
95
alice
110第一条命令返回 2,表示新增了两个成员。第二条命令返回 1,因为 CH 将已有成员的分值更新计入变化数量。最后一条命令显示 bob 的分值为 95、alice 的分值为 110,说明更新已生效。
如果第二条命令没有使用 CH,即使成功更新 alice,返回值仍然是 0,因为默认只统计新增成员。
返回值与异常
普通 ZADD 返回整数,表示新增成员数量;指定 CH 后,返回实际发生新增或分值变化的成员数量。返回 0 不一定表示操作失败,也可能只是更新了已有成员、分值未改变或条件选项阻止了写入。
指定 INCR 时,成功返回累加后的新分值,而不是新增成员数量。如果条件选项使累加操作无法执行,则返回空值。
当目标键已经存在但不是有序集合时,Redis 返回 WRONGTYPE 错误;分值不是合法数字,或组合了互斥选项时,也会返回命令错误。
风险与恢复
- 防止意外覆盖:使用
NX保护已有成员,使用XX避免创建新成员,使用XX GT限制更新方向。 - 恢复错误分值:如果已经记录原始分值,可以再次使用
ZADD写回,然后通过ZSCORE验证;没有原始值或历史记录时,Redis 不会自动恢复之前的分值。 - 检查键类型:遇到
WRONGTYPE时先用TYPE检查目标键,不要直接删除可能属于其他业务的数据。 - 确认版本:
ZADD从 Redis 1.2.0 开始支持;多成员写入从 2.4.0 开始支持;NX、XX、CH、INCR从 3.0.2 开始支持;GT、LT从 6.2.0 开始支持。
单个成员的添加或更新通常具有 时间复杂度,N 为集合中的成员数量。批量写入时应结合成员数量评估执行成本。
速查:新增优先选 NX,只更新已有成员选 XX,限制分值变化方向选 GT 或 LT,统计实际变化选 CH,累加分值选 INCR。
ZRANGE key start stop [BYSCORE | BYLEX] [REV] [LIMIT offset count] [WITHSCORES]按排名、分数或字典区间查询有序集合,适合排行榜和时间窗口检索;REV 可反向排序,LIMIT 仅在按分数或字典范围查询时使用。
获取排行榜区间
需要读取排行榜前 N 名、按分数筛选成员,或按字典序查询有序集合时使用 `ZRANGE`。它返回指定区间内的成员,配合 `REV` 可获取高分榜,配合 `WITHSCORES` 可同时返回成员分数。命令只读,不会修改集合。
基本语法
ZRANGE key start stop [BYSCORE | BYLEX] [REV] [LIMIT offset count] [WITHSCORES]默认按分数从低到高排列,`start` 和 `stop` 是从 0 开始的排名索引,且包含结束位置。例如 `0 9` 返回前 10 个成员,`0 -1` 返回全部成员。负索引从末尾计算。
指定 `BYSCORE` 后,两个边界改为分数;指定 `BYLEX` 后,两个边界改为字典序边界。两种模式互斥,不能同时启用。
关键选项
| 参数或选项 | 作用 | 使用要点 |
|---|---|---|
| `key` | 有序集合的键 | 键不存在时返回空结果 |
| `start stop` | 指定查询区间 | 默认是排名;`BYSCORE` 和 `BYLEX` 会改变边界含义 |
| `BYSCORE` | 按分数区间筛选 | 默认包含两端;`(95` 表示不包含 95,支持 `-inf`、`+inf` |
| `BYLEX` | 按成员字典序筛选 | `[` 表示包含边界,`(` 表示排除边界;通常要求所有成员分数相同 |
| `REV` | 反向排序 | 按排名时索引仍从 0 开始;按分数或字典序时边界需从高到低填写 |
| `LIMIT offset count` | 跳过匹配结果中的 `offset` 个,再取最多 `count` 个 | 仅适用于 `BYSCORE` 或 `BYLEX`;`offset` 从 0 开始 |
| `WITHSCORES` | 同时返回成员与分数 | 原生命令返回成员、分数交替排列的序列 |
当多个成员分数相同时,默认按成员字典序升序排列;使用 `REV` 后,同分成员按字典序降序排列。排行榜若需要稳定分页,应特别注意同分成员的次序。
排行榜查询示例
前置条件:本地 Redis 服务可连接,已安装 `redis-cli`,且测试键 `demo:rank` 尚不存在。以下命令可在系统终端依次执行。
# 在空测试键中写入四名玩家及其分数
redis-cli --raw ZADD demo:rank 120 alice 110 carol 95 bob 80 dave
# 按分数降序获取前十名,并返回分数
redis-cli --raw ZRANGE demo:rank 0 9 REV WITHSCORES
# 在 95~120 分范围内,按降序获取前两名
redis-cli --raw ZRANGE demo:rank 120 95 BYSCORE REV LIMIT 0 2 WITHSCORES预期输出:
4
alice
120
carol
110
bob
95
dave
80
alice
120
carol
110第一行 `4` 表示向空集合新增了四个成员。随后八行是第一次查询返回的四组成员与分数,最后四行是按分数区间筛选后返回的两组结果。`--raw` 让 `redis-cli` 每行显示一个返回元素,便于核对。
实际业务中,`ZRANGE demo:rank 0 9 REV WITHSCORES` 可直接用于获取排行榜前十名;即使集合不足十人,也只返回实际存在的成员,不会补齐空位。
分数与字典区间的边界
按分数查询时,默认使用闭区间。`ZRANGE demo:rank 95 120 BYSCORE` 包含分数 95 和 120;若要排除下限,可将起始边界写为 `(95`。
使用 `REV BYSCORE` 时必须交换边界顺序,例如 `ZRANGE demo:rank 120 95 BYSCORE REV`。如果仍然写成 `95 120`,通常会得到空结果,而不是自动交换边界。
`BYLEX` 适用于按字典序查询成员,例如同一分数下的字符串索引。边界 `[alice` 表示包含 `alice`,`(alice` 表示排除它,特殊边界 `-` 和 `+` 分别表示字典序的最小与最大边界。若成员分数不同,字典区间结果不保证符合预期,应先确认数据模型。
风险与排查
- **版本兼容**:`ZRANGE` 基础命令自 Redis 1.2.0 可用;`BYSCORE`、`BYLEX`、`REV` 等统一范围查询选项需要 Redis 6.2.0 或更新版本。旧版本使用对应的 `ZREVRANGE`、`ZRANGEBYSCORE` 等命令。
- **LIMIT 使用错误**:普通排名查询不能直接附加 `LIMIT`。排名分页应调整 `start`、`stop`,例如第二页十条使用 `10 19`。
- **大偏移性能**:按分数分页时,较大的 `LIMIT offset` 仍需要跳过大量匹配成员。大数据集优先考虑通过上一页分数和成员位置设计游标式分页。
- **键类型错误**:目标键存在但不是有序集合时会返回 `WRONGTYPE` 错误。可使用 `TYPE demo:rank` 检查类型;键不存在时则返回空列表。
- **结果过大**:生产环境谨慎执行 `ZRANGE key 0 -1 WITHSCORES`,大型集合可能产生大量网络传输和客户端内存开销。
`ZRANGE` 本身不会删除或覆盖数据。出现空结果时,优先检查键是否存在、分数边界是否正确,以及 `REV` 是否要求反向填写区间;无需通过删除键来恢复。
ZSCORE key member读取有序集合中指定成员的当前分数,适合检查用户积分或任务优先级;成员不存在返回空值,分数是浮点表示并非原始写入文本。
查询成员的分数
需要检查排行榜用户积分、任务优先级或确认某次分数更新是否生效时,使用 ZSCORE 读取有序集合中指定成员的当前分数。命令只读取数据,不修改成员、分数或排序;成员不存在时返回空值。
基本语法
ZSCORE key member
key:目标有序集合的键名,数据类型必须为zset。member:要查询的成员名称,必须与存储的成员值完全匹配,区分大小写。
执行后,Redis 返回成员当前分数的字符串表示,而不是原始写入时的文本。如果成员不存在或整个键不存在,返回空值 nil。
ZSCORE 的时间复杂度为 O(1),适合按成员精确查询。它不负责查找成员排名,也不会列出其他成员。
常用示例与预期结果
下面使用 redis-cli 在测试环境创建一个示例成员,再读取存在和不存在的成员分数。--no-raw 强制使用易读格式,使普通终端和脚本调用时的输出形式保持一致。
# 准备一个带有分数的排行榜成员
redis-cli --no-raw ZADD demo:rank 120.5 alice
# 查询存在的成员及不存在的成员
redis-cli --no-raw ZSCORE demo:rank alice
redis-cli --no-raw ZSCORE demo:rank unknown预期输出(假设 alice 原本不存在):
(integer) 1
"120.5"
(nil)第一行来自 ZADD,表示新增了一个成员。如果 alice 已经存在,ZADD 更新其分数后返回 (integer) 0,不影响随后读取到的 120.5。
第二行是 ZSCORE 返回的分数,第三行说明 unknown 不在集合中。
返回结果与异常
| 情况 | 返回结果 | 处理方式 |
|---|---|---|
| 成员存在 | 分数字符串,例如 "120.5" |
转换为数值或直接展示 |
| 成员不存在 | (nil) |
按业务规则处理缺失成员 |
| 键不存在 | (nil) |
检查键名或数据是否已经过期 |
| 键存在但不是有序集合 | WRONGTYPE 错误 |
检查键的数据类型 |
表中的 (nil) 是 redis-cli 易读格式的显示形式。应用客户端通常会把不存在的结果映射为语言对应的空值,具体类型取决于客户端库。
ZSCORE 存储和读取的是 Redis 有序集合使用的双精度浮点分数。例如写入 120.500,读取时可能显示为 120.5。不要依赖返回字符串保留尾随零、原始小数位数或写入时的格式。
对于超出双精度浮点数精确整数表示范围的积分值,还需考虑精度损失,不能将返回的分数字符串当作任意精度十进制数。
排查与使用边界
如果读取结果与预期不一致,按以下顺序检查:
- 使用
redis-cli TYPE demo:rank检查键类型,正常应返回zset。如果返回none,说明当前数据库中不存在该键。 - 检查成员名是否完全一致,例如
alice与Alice是不同成员。 - 使用
redis-cli ZRANGE demo:rank 0 -1 WITHSCORES查看完整的成员与分数对应关系,确认写入目标和当前数据。 - 如果分数与业务记录不一致,检查最近的
ZADD或ZINCRBY操作是否更新了该成员,并核对连接的数据库和 Redis 实例。
ZSCORE 只能查询分数。如果需要查询排名,应使用 ZRANK 或 ZREVRANK;如果需要一次查询多个成员的分数,可在支持 ZMSCORE 的 Redis 版本中使用该命令。
速查:成员存在返回当前分数,成员或键不存在返回空值,键类型错误返回 WRONGTYPE;查询不会改变排行榜。
ZRANK key member [WITHSCORE]取得成员按分数升序排列的零基名次,适合定位某个成员所处位置;如果需要通常意义上的高分优先名次,应使用反向排名命令。
查询有序集合成员名次
需要知道某个成员在 Redis 有序集合中的位置时,使用 `ZRANK`。它按照分数从低到高排序,返回从 `0` 开始的名次。适合查询低分优先的排名、定位成员位置,以及判断某个成员是否存在于排行榜中。高分优先的排行榜应使用 `ZREVRANK`。
基本语法
ZRANK key member [WITHSCORE]| 参数 | 含义 | 约束 |
|---|---|---|
| `key` | 有序集合的键名 | 必须是 Sorted Set 类型,或键不存在 |
| `member` | 要查询的成员 | 按成员的完整值精确匹配,区分大小写 |
| `WITHSCORE` | 同时返回成员名次和分数 | Redis 7.2.0 及以上支持 |
不带 `WITHSCORE` 时,成功返回整数名次;带 `WITHSCORE` 时,返回包含名次和分数的数组。成员不存在或键不存在时,返回空值,而不是整数 `0`。
命令时间复杂度为 `O(log N)`,其中 `N` 是有序集合的成员数量。`ZRANK` 从 Redis 2.0.0 开始可用。
常用示例与预期结果
以下命令在已经启动的 Redis 服务上执行,使用专用演示键。确保该键原本不存在,以获得一致的结果。
# 仅向空的演示键写入数据,避免覆盖业务排行榜
redis-cli ZADD demo:zrank:example:46 10 alice 20 bob 30 carol
redis-cli ZRANK demo:zrank:example:46 alice
# 同时读取名次和分数,要求 Redis 7.2.0 或更新版本
redis-cli ZRANK demo:zrank:example:46 bob WITHSCORE
redis-cli ZRANK demo:zrank:example:46 nobody
redis-cli ZREVRANK demo:zrank:example:46 carol预期输出(按上述命令执行顺序):
(integer) 3
(integer) 0
1) (integer) 1
2) "20"
(nil)
(integer) 0结果解读:
- `alice` 分数为 `10`,升序名次为 `0`,对应通常所说的第 1 位。
- `bob` 分数为 `20`,升序名次为 `1`;`WITHSCORE` 同时返回其分数 `20`。
- `nobody` 不在集合中,因此返回 `(nil)`。
- `carol` 分数最高,使用 `ZREVRANK` 查询时,反向名次为 `0`。
如果只需要查看完整排序,可使用 `ZRANGE key 0 -1 WITHSCORES` 核对成员的实际顺序;该命令按分数升序列出成员及其分数。
排名规则与边界
**名次从零开始。** `ZRANK` 返回 `0` 表示升序第一位。业务页面需要展示从 `1` 开始的名次时,应在应用层将有效返回值加 `1`,并先判断返回值是否为空。
**同分成员仍有确定顺序。** 当多个成员分数相同时,Redis 按成员值的字典序排列;因此两个分数相同的成员也会占据不同名次。例如分数都是 `10` 时,`alice` 排在 `bob` 前面。不要将 `ZRANK` 的结果直接理解为允许并列的竞赛排名。
**排名是实时计算结果。** `ZADD` 或 `ZINCRBY` 修改成员分数后,成员顺序可能改变,后续查询的名次也可能发生变化。需要长期保存历史名次时,应由业务单独记录快照。
**错误与兼容性。** 如果 `key` 存在但不是有序集合,Redis 返回 `WRONGTYPE` 错误;如果旧版本不支持 `WITHSCORE`,可分别使用 `ZRANK` 和 `ZSCORE` 查询,但两次查询之间数据可能发生变化。
风险与恢复
`ZRANK` 是只读命令,不会修改成员、分数或集合内容,因此查询本身不需要恢复操作。
示例中的 `ZADD` 会创建或修改集合。不要直接对生产排行榜运行初始化示例;若误改成员分数,应依据事先记录的旧分数执行 `ZADD` 恢复。没有旧值记录时,不能通过 `ZRANK` 反推出原始分数。
速查:**低分优先用 `ZRANK`,高分优先用 `ZREVRANK`;两者名次都从 `0` 开始。**
ZINCRBY key increment member对有序集合成员的分数进行原子加减,适合实时积分和动态权重;默认对缺失成员从零计算,客户端须处理数值范围和并发业务规则。
原子调整排序分值
实时排行榜需要给用户增加积分、扣减积分或调整排序权重时,使用 ZINCRBY 一次完成分值修改,并取得更新后的分数。单条命令具有原子性,避免先读取分值、在客户端计算、再写回造成的并发更新丢失。
基本语法
ZINCRBY key increment member| 参数 | 含义 | 约束 |
|---|---|---|
key |
存储排行榜的有序集合键 | 不存在时自动创建;已存在时必须是有序集合类型 |
increment |
分数增量 | 支持正数、负数、零和浮点数 |
member |
要调整分数的成员 | 不存在时自动添加,初始分数视为 0 |
执行成功后返回成员的新分数,而不是本次增量或排行榜名次。RESP2 使用字符串形式返回分数,RESP3 返回双精度浮点数;使用 redis-cli --raw 时直接显示数值文本。
例如,成员原分数为 10,执行 ZINCRBY demo:rank 5 alice 后,新分数为 15;如果增量是 -3,则从当前分数中减去 3。
常用示例与预期结果
前置条件:本机 Redis 服务正在运行,redis-cli 可以连接默认地址。下面操作会修改 demo:rank 中的 alice,应在测试环境或确认安全的演示键上执行。
# 建立可重复验证的初始分数
redis-cli --raw ZADD demo:rank 10 alice
# 连续加分与减分,每次修改都是独立的原子操作
redis-cli --raw ZINCRBY demo:rank 5 alice
redis-cli --raw ZINCRBY demo:rank -2 alice
# 读取当前分数,核对计算结果
redis-cli --raw ZSCORE demo:rank alice预期输出(执行前 alice 不存在时):
1
15
13
13第一行 1 表示 ZADD 新增了成员。如果 alice 原本已经存在,第一行改为 0,表示更新已有成员分数;后面三行仍分别为 15、13、13,因为 ZADD 已将初始分数设置为 10。
验证时,第二行确认加分生效,第三行确认负增量生效,第四行通过 ZSCORE 证明最终存储分数与计算结果一致。
如果需要查询成员的降序排名,应另用 ZREVRANK;ZINCRBY 本身不返回名次。
并发与数值边界
- 单命令原子性:多个客户端同时对同一成员执行
ZINCRBY,Redis 不会因客户端读写交错而丢失单次增量。但多条业务命令组合执行时,不会自动获得整体原子性。 - 重复请求:命令不是幂等操作。同一个加分请求重试两次,会累计两次分值。涉及支付奖励、任务积分等业务时,应使用请求 ID 去重,并通过 Lua 脚本等方式将去重检查与加分合并为原子操作。
- 精度限制:分数使用双精度浮点数,整数超过精确表示范围后可能出现精度损失,小数反复累加也可能产生舍入误差。严格金额计算不宜直接使用浮点分数。
- 类型错误:如果
key已存在但不是有序集合,Redis 返回WRONGTYPE错误,原有键类型不会自动转换。 - 业务下限:Redis 允许负分数。如果业务规定积分不得小于零,需要额外实现原子校验,不能仅依赖客户端预先读取分数后判断。
ZINCRBY 的时间复杂度为 O(log N),其中 N 为有序集合成员数量。该命令自 Redis Open Source 1.2.0 起可用。
误操作恢复
如果确定某次操作误增加了 5 分,可根据业务流水核实后执行相反增量 ZINCRBY demo:rank -5 alice 进行补偿。补偿仍是一次新的分值修改,不会撤销已经发送的其他业务事件。
如果误操作创建了原本不存在的成员,单纯反向增量只会把分数恢复到零,不会删除成员;确认该成员应当不存在时,需使用 ZREM 删除。
速查:正增量加分,负增量扣分;缺失成员自动创建;返回新分数;单命令原子,但不自动保证业务幂等性。
ZREM key member [member ...]删除有序集合的指定成员,适合清理下线任务或撤销排行榜参与者;此操作不可恢复,返回值只统计实际移除的成员数量。
移除排序成员 ZREM
当排行榜参与者退出、任务下线或需要清理指定排名记录时,使用 ZREM 从 Redis 有序集合中删除一个或多个成员。命令返回实际删除数量,不存在的成员不会计数,也不会影响其他成员的分数。
基本语法
ZREM key member [member ...]key:目标有序集合的键名,必须是有序集合类型,或者尚不存在。member:要删除的成员值,至少指定一个。[member ...]:可选的其他成员,同一次命令可以删除多个成员。
ZREM 根据成员值删除记录,不按分数或排名区间删除。成员的分数由 Redis 自动关联,无须在删除命令中指定。
返回值与边界
| 情况 | 返回结果 |
|---|---|
| 指定成员存在且被删除 | 返回实际删除的成员数量 |
| 部分成员不存在 | 只统计实际删除的成员 |
| 所有成员均不存在 | 返回整数 0 |
key 不存在 |
返回整数 0 |
key 存在但不是有序集合 |
返回 WRONGTYPE 错误 |
删除最后一个成员后,Redis 会移除对应的空有序集合键。删除不会改变其余成员的分数,但其余成员的排名位置可能因此发生变化。
常用示例
以下使用独立测试键 demo:zrem:entry48 验证批量删除、重复删除及剩余成员。前置条件是本机 Redis 服务可访问,并已安装 redis-cli。示例会先清空该测试键,因此只能在确认该键不包含需要保留的数据后执行。
# 初始化独立测试排行榜,确保示例可重复运行
redis-cli --raw DEL demo:zrem:entry48 >/dev/null
redis-cli --raw ZADD demo:zrem:entry48 100 alice 80 retired-player 60 bob
# 同时删除已存在成员和不存在的成员
redis-cli --raw ZREM demo:zrem:entry48 retired-player missing-player
# 再次删除相同成员,验证幂等效果
redis-cli --raw ZREM demo:zrem:entry48 retired-player
# 按分数升序读取剩余成员及其分数
redis-cli --raw ZRANGE demo:zrem:entry48 0 -1 WITHSCORES预期输出:
3
1
0
bob
60
alice
100输出中,3 表示初始化时新增了三个成员;第一次 ZREM 返回 1,因为只有 retired-player 存在;第二次返回 0,因为该成员已被删除。最后四行是 ZRANGE 的读取结果,显示剩余成员 bob 和 alice 及其原有分数。
--raw 使 redis-cli 以原始文本形式输出结果,便于对照。若使用交互式客户端,整数和数组的显示格式可能不同,但返回含义一致。
风险与恢复
需要支持误删恢复时,先使用 ZSCORE key member 查询并保存每个目标成员的原始分数;确认删除后若需要恢复,可使用 ZADD key score member 重新写入。对于批量成员,可以事先完整保存成员与分数的对应关系。
恢复时应先确认成员未被其他业务流程重新创建或更新,避免用旧分数覆盖新状态。若删除操作同时触发了业务事件或外部清理,重新执行 ZADD 也不会自动撤销这些副作用。
在并发更新的排行榜中,预先读取分数再删除存在竞争窗口。如需保证检查与删除属于同一原子操作,应使用经过验证的 Redis Lua 脚本处理。
ZPOPMIN key [count]按最低分弹出并删除一个或多个成员,适合简易优先队列;消费即移除,不具备任务确认和故障恢复机制,需要可靠队列时优先使用 Streams。
弹出最低分成员
需要从 Redis 有序集合中取出优先级最高的任务(以较小分数表示较高优先级),并同时将其移除时,使用 ZPOPMIN。命令原子地返回最低分成员及其分数,适合消费后无需确认的简易优先队列。
基本语法
ZPOPMIN key [count]| 参数 | 含义 | 默认值或约束 |
|---|---|---|
key |
目标有序集合的键名 | 必填,数据类型为 sorted set |
count |
本次最多弹出的成员数量 | 可选,默认 1 |
执行时按分数从小到大移除成员。返回结果包含每个成员及其原始分数,而不是只返回成员名称。
- 未指定
count:弹出一个最低分成员。 - 指定
count:最多弹出对应数量的成员,结果仍按分数升序排列。 count大于现有成员数量:只返回剩余成员,不会因数量不足而报错。- 键不存在或集合为空:返回空数组;移除最后一个成员后,Redis 会删除该键。
- 分数相同时:按成员的字典序决定先后,不保证按插入时间排序。
常用示例与预期结果
前置条件:已安装 redis-cli,能够连接到可写的 Redis 5.0 或更新版本测试实例。下面创建三个带有不同优先级分数的任务,一次弹出两个,再检查剩余成员。示例使用带当前 Shell 进程号的演示键,避免直接修改业务集合。
key="cheatsheet:zpopmin:demo:$$"
redis-cli DEL "$key" >/dev/null # 仅重置当前演示键
redis-cli --raw ZADD "$key" 10 task-a 20 task-b 30 task-c
echo "已弹出:"
redis-cli --raw ZPOPMIN "$key" 2
echo "剩余:"
redis-cli --raw ZRANGE "$key" 0 -1 WITHSCORES
redis-cli DEL "$key" >/dev/null # 演示结束后清理预期输出:
3
已弹出:
task-a
10
task-b
20
剩余:
task-c
30ZADD 返回 3,表示新增三个成员。ZPOPMIN 按分数升序返回 task-a 和 task-b,各自对应分数 10、20。随后 ZRANGE ... WITHSCORES 只返回 task-c 和分数 30,证明前两个成员已被删除。
--raw 使 redis-cli 直接逐行输出成员和分数,便于阅读。应用代码需要根据所用客户端的返回结构解析成员与分数,不应假设所有客户端都返回相同的文本格式。
风险与恢复
- 执行前检查:使用
ZRANGE key 0 -1 WITHSCORES预览候选成员,确认分数含义、集合键名和弹出数量。 - 误弹出恢复:如果保留了返回的成员和原始分数,可以使用
ZADD key score member重新加入。恢复前应确认任务尚未被其他消费者完成,避免重复处理。 - 消费失败:如果弹出结果尚未持久化或记录,无法仅依靠该集合找回已移除的成员。
- 类型错误:如果
key存储的是字符串、列表等非有序集合数据,命令会返回WRONGTYPE错误。先用TYPE key检查,不要直接删除未知业务键。 - 空队列处理:
ZPOPMIN不会阻塞等待新成员;需要阻塞等待时,可考虑BZPOPMIN。
对于任务必须确认完成、消费者故障后需要重新投递的场景,优先选择 Redis Streams 配合消费者组和 XACK 等确认机制,而不是仅依赖 ZPOPMIN。
适用范围与速查
ZPOPMIN 从 Redis 5.0.0 开始提供,时间复杂度为 ,其中 为集合成员数量、 为本次实际弹出的成员数量。批量消费时应选择合理的 count,避免单次返回过多数据。
只想查看最低分成员而不删除时,使用 ZRANGE key 0 0 WITHSCORES;要取走最高分成员时,使用 ZPOPMAX。
ZCARD key快速获取有序集合的成员总数,适合显示参与人数或优先队列长度;不会返回分数分布,不能代替按区间统计或滞留时间分析。
查询排行榜规模
需要显示排行榜参与人数、统计有序集合成员总数,或查看优先队列当前长度时,使用 ZCARD。它直接返回指定有序集合中的成员数量,不读取成员详情或分数,适合快速获取整体规模。
基本语法
ZCARD keykey:目标有序集合的键名,例如demo:rank。- 返回值:整数,表示当前有多少个不同的成员。
- 时间复杂度:
O(1),不需要遍历集合中的所有成员。 - 命令没有额外的筛选、排序或分页参数。
在 redis-cli 交互模式中可以直接输入 ZCARD demo:rank;在操作系统终端中执行时,需要使用 redis-cli ZCARD demo:rank。
常用示例与预期结果
以下示例要求本地 Redis 服务可通过默认连接访问,并且测试键 demo:rank:zcard-example 此前不存在。使用 --raw 使终端输出直接显示数字,便于核对。
# 建立包含三个不同成员的测试排行榜
redis-cli --raw ZADD demo:rank:zcard-example 100 alice 80 bob 120 carol
redis-cli --raw ZCARD demo:rank:zcard-example
# 更新已有成员的分数,不会新增成员
redis-cli --raw ZADD demo:rank:zcard-example 130 alice
redis-cli --raw ZCARD demo:rank:zcard-example预期输出(四行依次对应四条命令):
3
3
0
3第一次 ZADD 新增三个成员,返回 3。第一次 ZCARD 同样返回 3。随后将 alice 的分数更新为 130,由于没有新增成员,第二次 ZADD 返回 0,最终成员总数仍然是 3。
由此可以确认:ZCARD 统计的是不同成员的数量,不是分数之和,也不是写入操作次数。
返回结果与边界
| 情况 | 结果或行为 |
|---|---|
| 有序集合包含 3 个成员 | 返回 3 |
| 键不存在 | 返回 0 |
| 同一成员的分数被更新 | 成员数量不变 |
| 键对应字符串等其他不兼容类型 | 返回 WRONGTYPE 错误 |
| 需要统计指定分数范围内的成员 | 应使用 ZCOUNT |
| 需要读取排行榜名次及对应分数 | 应使用 ZRANGE 等查询命令 |
ZCARD 返回 0 时,表示当前没有可统计的成员,但单凭这个返回值不能判断该键是从未创建、已过期还是已被删除。需要确认键类型时,可通过 TYPE key 检查,返回 zset 表示有序集合,返回 none 表示键不存在。
统计口径与使用风险
如果排行榜使用用户 ID 作为成员,每位用户只保存一条记录,那么 ZCARD 可以表示当前榜单中的唯一用户数。如果同一用户允许使用多个不同成员标识,结果就不能直接解释为去重后的参与人数。
ZCARD 统计整个集合,不支持仅统计前 100 名、最近七天或某个积分区间。需要按分数范围统计时使用 ZCOUNT;需要按加入时间统计时,应另行保存时间信息或维护以时间戳为分数的索引,不能把积分分数误当作时间。
确认测试键仅由本次示例创建且不需要保留后,可以执行 redis-cli --raw DEL demo:rank:zcard-example 清理,预期返回 1,表示删除了一个键。DEL 会删除整个集合,不要对生产排行榜执行此清理操作。
速查:查全部成员数量用 ZCARD,查分数区间人数用 ZCOUNT,查成员与排名用 ZRANGE。
JSON 文档更新
JSON.SET key path value [NX | XX] [FPHA <FP16 | BF16 | FP32 | FP64>]写入完整 JSON 文档或指定路径的值,适合结构化对象缓存;根路径使用 $,条件选项控制新增与覆盖,需确认实例支持 JSON 命令。
写入 JSON 文档
需要缓存用户资料、配置对象等结构化数据,或更新 JSON 文档中的指定字段时,使用 JSON.SET。通过根路径 $ 可以写入整个文档,通过 $.字段名 可以定位字段;配合 NX、XX 控制写入条件,并用 JSON.GET 验证结果。
基本语法
JSON.SET key path value [NX | XX] [FPHA <FP16 | BF16 | FP32 | FP64>]key:目标 Redis 键,可以是新键或已有 JSON 文档键。path:写入路径。$表示整个文档,$.name表示根对象中的name字段。value:合法 JSON 值,可以是对象、数组、字符串、数字、布尔值或null。NX、XX:可选写入条件,二者互斥。FPHA:可选浮点数组存储格式,适用于支持该选项的 Redis 版本。
当键不存在时,只能通过根路径 $ 或 . 创建新文档。对于已有对象,可以在父对象存在的情况下新增字段;如果中间路径不存在,JSON.SET 不会自动补齐整个对象层级。
条件与存储选项
| 选项 | 行为 | 典型用途 |
|---|---|---|
| 不指定 | 写入目标路径;已有值会被替换 | 普通缓存写入与更新 |
NX |
仅在目标路径没有匹配值时写入 | 防止覆盖已有字段或文档 |
XX |
仅在目标路径已有匹配值时写入 | 只修改已存在字段 |
FPHA FP16 |
使用半精度浮点格式存储适用数组 | 降低存储开销,可接受精度损失 |
FPHA BF16 |
使用 BF16 浮点格式存储适用数组 | 需要较大数值范围的低精度数据 |
FPHA FP32 |
使用单精度浮点格式存储适用数组 | 浮点向量数据 |
FPHA FP64 |
使用双精度浮点格式存储适用数组 | 对精度要求较高的数据 |
NX 和 XX 检查的是目标路径是否匹配,不只是检查 Redis 键是否存在。例如,文档已经存在但 $.age 字段不存在时,NX 仍可用于新增该字段。
FPHA 在 Redis 8.8 引入,用于指定写入值中浮点同构数组的存储精度。旧版本可能不支持该选项;选择 FP16 或 BF16 前应确认数值范围和精度要求,不要直接用于需要精确表示的业务数值。
写入与验证示例
前置条件:Redis 服务正在运行,已支持 JSON.SET 和 JSON.GET,本机已安装 redis-cli。以下命令在 Bash 或兼容 Shell 中执行,默认连接本机 Redis;若实例位于其他地址,应配置对应连接参数。
# 创建或覆盖演示文档,根路径 $ 指向整个 JSON
redis-cli JSON.SET demo:profile:42 '$' '{"name":"Ada","level":3}'
# 只更新已存在的 level 字段,不重写整个文档
redis-cli JSON.SET demo:profile:42 '$.level' '4' XX
# 读取根路径,验证对象结构和字段值
redis-cli --raw JSON.GET demo:profile:42 '$'预期输出:
OK
OK
[{"name":"Ada","level":4}]第一条命令写入完整对象;第二条仅将 level 从 3 修改为 4,保留 name 字段。第三条通过 JSON.GET 读取结果。使用 JSONPath $ 查询时,返回内容是包含匹配值的 JSON 数组,因此外层出现方括号。
这里使用 --raw 便于直接查看 JSON 文本;普通 redis-cli 可能额外显示字符串引号与转义字符。若已有同名键,第一条命令可能覆盖原有 JSON 数据,应使用专门的测试键。
返回值与失败处理
| 返回情况 | 含义 | 处理方式 |
|---|---|---|
OK |
写入成功 | 使用 JSON.GET 检查目标路径 |
空回复 (nil) |
条件未满足,或路径无法创建且返回空值 | 检查 NX、XX 与父路径是否存在 |
| JSON 格式错误 | value 不是合法 JSON |
检查对象引号、逗号和字符串转义 |
| 路径错误 | JSONPath 无效或目标位置不合法 | 检查路径表达式与数组索引 |
unknown command |
当前实例不支持该命令 | 检查 Redis 版本及 JSON 功能是否可用 |
WRONGTYPE |
同名键存储了不兼容的数据类型 | 先用 TYPE 检查键类型,不要直接覆盖业务数据 |
需要区分 JSON 字符串和 Redis 命令参数。例如写入字符串 Ada,传给 value 的内容必须是合法 JSON 字符串,即 "Ada";写入数字 4 则直接传递 4,不需要 JSON 字符串引号。
覆盖风险与恢复
如果只需要修改一个字段,优先使用精确路径,例如 $.level,避免替换整个对象。仅允许初始化新文档时,在根路径写入命令末尾添加 NX,已存在的文档就不会被覆盖。
误写后如需恢复,应从应用保存的原始值、可靠备份或其他业务数据源重新写入;无法保证仅凭 Redis 当前内容找回被覆盖字段。生产操作前建议先使用 JSON.GET 保存目标文档,并确认键名和路径。
速查:整篇写入用 $,字段更新用 $.字段名;防覆盖用 NX,限定已有路径用 XX;执行后用 JSON.GET 核对。
JSON.GET key [INDENT indent] [NEWLINE newline] [SPACE space] [path [path ...]]按 JSONPath 提取完整文档或局部字段,适合减少业务层手工解析;单个 JSONPath 的结果通常以数组封装,调用方应核对返回形态。
读取 JSON 指定路径
需要从 Redis JSON 文档中读取某个字段、嵌套对象或多个匹配值时,使用 JSON.GET。命令返回 JSON 序列化字符串,可以避免先读取整个文档再由业务代码提取字段。尤其要注意:以 $ 开头的 JSONPath 通常返回数组结构,即使只匹配一个值。
基本语法
JSON.GET key [INDENT indent] [NEWLINE newline] [SPACE space] [path [path ...]]| 参数 | 作用 | 默认行为或约束 |
|---|---|---|
key |
保存 JSON 文档的 Redis 键 | 必填,键的数据类型必须兼容 Redis JSON |
path |
指定读取位置 | 可省略以读取根文档,也可提供多个路径 |
INDENT |
设置嵌套层级缩进字符串 | 可选,仅控制输出格式 |
NEWLINE |
设置格式化时使用的换行字符串 | 可选,仅控制输出格式 |
SPACE |
设置对象键和值之间的分隔空格 | 可选,仅控制输出格式 |
路径主要有两种写法:
$.name:JSONPath,选择根对象中的name,匹配结果以数组封装。$.contact.city:JSONPath,读取嵌套字段。$..name:递归查找文档中所有匹配的name字段。$.tags[0]:读取数组中的第一个元素,索引从 0 开始。.name:传统路径语法,读取首个匹配值,不使用 JSONPath 的数组封装。
单字段读取示例
前置条件:Redis 服务已启动,并支持 Redis JSON 命令;命令行可以通过 redis-cli 连接。以下命令使用独立演示键,不依赖已有业务数据。
# 创建完整测试文档,避免依赖现有数据
redis-cli JSON.SET demo:profile:42 '$' '{"name":"Ada","age":28,"contact":{"city":"KL"}}'
# 对比 JSONPath 和传统路径的返回形态
redis-cli --raw JSON.GET demo:profile:42 '$.name'
redis-cli --raw JSON.GET demo:profile:42 '.name'
redis-cli --raw JSON.GET demo:profile:42 '$.contact.city'预期输出(按命令执行顺序):
OK
["Ada"]
"Ada"
["KL"]--raw 让 redis-cli 直接显示返回的 JSON 字符串,避免额外的终端转义影响阅读。这里最容易混淆的是 $.name 与 .name:前者返回 ["Ada"] 这样的数组,后者返回 JSON 字符串值 "Ada"。
业务代码应先解析返回的 JSON,再根据路径模式处理数组或标量,不能直接假设读取单个字段就一定得到单个标量。
多路径读取与缺失值
同一次请求可以提供多个路径,Redis 会把每条路径作为结果对象的键,对应的匹配值放在数组中。适合同时读取用户姓名、年龄等少量相关字段。
# 一次获取两个字段,并检查不存在的字段
redis-cli --raw JSON.GET demo:profile:42 '$.name' '$.age'
redis-cli --raw JSON.GET demo:profile:42 '$.unknown'预期输出:
{"$.name":["Ada"],"$.age":[28]}
[]多路径结果中的对象键顺序不保证固定,应用应按路径名称读取对应字段,不应依赖字符串顺序。当 JSONPath 没有匹配位置时,结果是空数组 [];如果整个 Redis 键不存在,则命令返回空回复(nil),两者代表不同情况。
读取嵌套数组或使用递归路径时,一条路径可能匹配多个值,例如 $..name 可能从不同层级返回多个姓名。此时必须保留数组语义,而不是只取第一个元素。
风险与排查
JSON.GET 是只读命令,不会修改原始 JSON,因此通常不需要数据恢复。不过,读取整个大型文档或使用递归、通配符路径,仍可能增加扫描、序列化和网络传输开销。
- 出现
ERR unknown command 'JSON.GET':检查 Redis 实例是否具备 JSON 命令支持,而不是把它当作普通字符串键用GET处理。 - 得到
[]:先检查字段拼写、大小写、嵌套层级和数组索引,再确认路径是否匹配。 - 得到 nil:优先检查键是否存在、是否连接了正确的 Redis 实例和数据库。
- 返回结构与预期不一致:检查是否混用了
$开头的 JSONPath 和传统路径;多路径结果可能自动采用数组结构。 - 读取结果过大:优先使用明确的字段路径,避免不必要的
$根文档读取和$..*全文递归匹配。
适用范围:JSON.GET 需要 Redis JSON 支持,其中 $ 开头的 JSONPath 语法由 RedisJSON 2.0 引入。旧环境应确认实际版本及传统路径兼容性。命令参数和返回规则可参考 Redis 官方 JSON.GET 文档。
JSON.NUMINCRBY key path value对 JSON 文档匹配路径上的数值执行增量更新,适合对象内部计数;路径必须指向可更新的数值节点,先确认多路径匹配与返回结果。
原子增加 JSON 数值
需要对 Redis JSON 文档中的等级、积分、次数或其他数值字段执行加减操作时,使用 JSON.NUMINCRBY。它在单条命令中原子更新匹配的数值节点,并返回更新后的结果,避免客户端先读取再写回造成的并发计数丢失。
基本语法
JSON.NUMINCRBY key path value| 参数 | 含义 | 约束 |
|---|---|---|
key |
保存 JSON 文档的 Redis 键 | 必须存在且包含 JSON 文档 |
path |
定位待更新数值节点的路径 | $ 开头的 JSONPath 可以匹配多个节点 |
value |
本次增加的数值 | 正数增加、负数减少,支持小数 |
例如 $.level 指向根对象中的 level 字段,$.stats.wins 指向嵌套字段,而 $..level 会递归匹配文档内所有名为 level 的节点。
JSON.NUMINCRBY 不会自动创建不存在的字段,也不能把字符串、布尔值或 null 当作数字累加。使用 $ 开头的路径需要支持 JSONPath 的 RedisJSON 2.0 或更新实现。
常用示例与预期结果
前置条件:Redis 实例支持 JSON 命令,本机已安装 redis-cli 并能连接实例。以下命令在 Bash 等支持单引号的 Shell 中执行,使用一次性演示数据;JSON.SET 会覆盖同名文档,不要直接用于已有生产数据。
# 初始化演示文档,level 初始值为 5
redis-cli --raw JSON.SET demo:profile:42 '$' '{"level":5,"name":"Ada"}'
# 对已有数值字段原子加 1
redis-cli --raw JSON.NUMINCRBY demo:profile:42 '$.level' 1
# 再次读取,确认字段已更新
redis-cli --raw JSON.GET demo:profile:42 '$.level'预期输出(默认 RESP2 协议,每行对应一条命令):
OK
[6]
[6]第一条命令创建文档,第二条把 level 从 5 更新为 6,第三条读取到相同的新值。对 $ 路径,即使只匹配一个节点,返回结果也采用数组形式。
需要减少数值时,可以把增量改为 -1;需要增加小数时可以使用 0.5。增量是变化量,而不是目标值:原值为 6、增量为 -2 时,最终结果是 4。
多路径匹配与返回值
$ 开头的 JSONPath 可以匹配多个位置,命令会更新所有匹配到的数值节点。读取返回值时,不能假设数组只有一个元素。
| 匹配情况 | RESP2 下的 JSON 结果 | 实际行为 |
|---|---|---|
匹配一个数值 5,增加 1 |
[6] |
数值更新为 6 |
匹配数值 2、字符串及数值 4,增加 1 |
[3,null,5] |
数值更新,字符串保持不变 |
| 没有匹配节点 | [] |
不发生更新 |
| 只匹配非数值节点 | [null] |
对应节点保持不变 |
以上结果表示使用 $ 路径时的典型返回内容。在 RESP2 下,命令返回包含 JSON 数组的字符串;使用 redis-cli --raw 可以直接查看其中的 JSON 文本。RESP3 则返回协议数组,其中包含数值或空值,应按实际客户端协议解析。
旧式路径(如 .level)与 JSONPath 的返回结构不同:RESP2 下通常返回单个新数值的字符串。旧式路径即使匹配多个数值也可能只返回最后一个更新结果,不适合依靠响应数量判断更新了多少节点。
错误处理与恢复
- 键不存在:命令返回错误,不会替你创建文档。应先确认
EXISTS或读取文档,再决定是否初始化。 - 字段不存在:
$路径没有匹配时返回空数组。需要先通过JSON.SET创建目标数值字段,再执行增量。 - 类型不匹配:数值以外的匹配节点返回
null且不会被更新。可以使用JSON.TYPE检查类型,用JSON.GET确认实际值。 - 计算超出允许范围:命令会报错。对金额、精度敏感的值或接近数值边界的计数,应先确定数值范围与表示方式。
- 结果重复增加:命令不具有请求幂等性。客户端超时后直接重试可能产生二次增加,应使用业务请求 ID 和去重逻辑避免重复提交。
误更新后,应根据操作前保存的数值、业务记录或备份核对并恢复。在没有其他并发写入的情况下,可以通过相反增量撤销;存在并发更新时,不要直接再执行一次负增量,否则可能覆盖或混淆其他操作的效果,应在受控条件下恢复准确状态。
单次 JSON.NUMINCRBY 对其匹配的节点执行原子更新,但它不会让多个独立命令自动构成事务。使用前确认目标路径,使用后检查返回数组和实际存储值。
JSON.DEL key [path]删除 JSON 文档中指定路径匹配的内容,适合移除废弃字段;不传路径可能删除整个键,生产执行前必须确认路径范围和备份策略。
删除 JSON 路径
当 JSON 文档需要移除废弃字段、同时保留其他成员时使用 JSON.DEL。先确认路径的命中结果,再删除并检查返回数量,避免误删整个 Redis 键。
基本语法
JSON.DEL key [path]
key:存放 Redis JSON 文档的键。path:可选的 JSONPath;省略时默认是根路径$,将删除整个键。- 返回值:被删除的路径数量;路径不存在时返回
0。一个路径表达式可能匹配多处,删除数因此可能大于1。
示例与验证
前置条件:Redis 已提供 JSON 命令,本地可使用 redis-cli 连接。以下命令在专用测试键上创建文档,删除 profile.legacy,并确认其他字段仍在。
# 仅使用演示键,初始化会覆盖该键的旧内容
redis-cli JSON.SET demo:json:del:54 '$' '{"profile":{"nickname":"Lin","legacy":"old"},"active":true}'
redis-cli --raw JSON.GET demo:json:del:54 '$.profile.legacy'
# 精确指定成员路径,不使用默认的根路径
redis-cli JSON.DEL demo:json:del:54 '$.profile.legacy'
redis-cli --raw JSON.GET demo:json:del:54 '$'
redis-cli EXISTS demo:json:del:54预期输出(依次对应五条命令):
OK
["old"]
(integer) 1
[{"profile":{"nickname":"Lin"},"active":true}]
(integer) 1风险与恢复
生产执行前使用 JSON.GET key 留存完整 JSON 文档,并按业务备份方案留有可恢复副本。JSON.DEL 没有撤销参数;若父对象仍存在,可根据留存值用 JSON.SET 补回字段:
# 恢复字符串类型的原值,外层单引号保护 JSON 字符串的双引号
redis-cli JSON.SET demo:json:del:54 '$.profile.legacy' '"old"'
redis-cli --raw JSON.GET demo:json:del:54 '$.profile.legacy'预期输出:
OK
["old"]如果整个键已删除,应从已保存的完整 JSON 或备份恢复根文档;遇到 unknown command 时,先确认实例支持 Redis JSON。
实时事件广播
PUBLISH channel message把消息发送给当前订阅指定频道的连接,适合在线通知和轻量实时广播;消息不持久化,离线消费者无法补读,不能代替可靠消息队列。
向频道发布事件
当多个在线客户端需要立即收到同一事件时,使用 PUBLISH 向指定频道广播消息。Redis 会把消息推送给当前匹配该频道的订阅连接,并返回接收客户端数量。适用于缓存失效通知、在线状态变化和轻量实时事件,不适用于要求持久化或确认消费的任务。
基本语法
PUBLISH channel messagechannel:目标频道名称,例如demo:events。频道名称需要与订阅端一致,区分大小写。message:发送的消息内容,例如user.updated。可以是普通字符串或序列化后的数据。
在 redis-cli 交互模式中直接执行 PUBLISH;在操作系统终端中执行时,需要添加 redis-cli 前缀。消息包含空格时,应正确引用参数,避免被命令行拆分。
PUBLISH 自 Redis 2.0.0 起可用。它不需要预先创建频道,发布消息也不会创建 Redis 键或持久化消息内容。
在线广播的投递关系
发布者只需指定频道,不必知道订阅者的连接地址。Redis 将消息转发给当前订阅该频道的客户端;多个在线订阅者可以各自收到消息,而发布前尚未订阅或发送时已经断线的客户端无法补收。

普通频道使用 SUBSCRIBE 接收消息;PSUBSCRIBE 可以通过模式匹配订阅多个频道。发布命令本身不会等待应用程序处理消息,也不提供业务确认。
双终端验证
前置条件:Redis 服务已经启动,两个终端能够连接同一 Redis 实例,且拥有相应的发布和订阅权限。以下示例使用默认连接参数;如果服务位于远程或启用了认证,应根据环境配置连接选项。
先在终端 A 建立订阅:
# 保持订阅连接运行,等待频道消息
redis-cli --raw SUBSCRIBE demo:events预期输出(订阅确认):
subscribe
demo:events
1其中 1 表示当前连接订阅的频道数量。终端 A 会继续等待消息,不要在发送之前关闭它。
确认终端 A 已显示订阅成功后,在终端 B 执行:
# 向已有订阅者发送一次事件通知
redis-cli --raw PUBLISH demo:events user.updated预期输出(假设只有终端 A 一个匹配的订阅连接,使用单实例 Redis):
1与此同时,终端 A 会追加收到:
message
demo:events
user.updated三行分别表示消息类型、来源频道和消息内容。终端 B 返回的数字不是消息内容,而是本次发布命中的客户端数量。
返回值与异常排查
PUBLISH 成功执行后返回整数。单实例模式下,该数字表示本次消息发送到的匹配订阅客户端数量。
| 返回情况 | 含义 | 处理方式 |
|---|---|---|
0 |
当前没有匹配的订阅客户端 | 检查频道名称、订阅时机和连接状态 |
1 |
命中一个订阅客户端 | 到订阅端检查是否出现对应消息 |
大于 1 |
命中多个订阅客户端 | 分别确认各客户端的接收与业务处理情况 |
NOPERM 错误 |
当前用户缺少对应命令或频道权限 | 检查 ACL 命令权限与频道访问规则 |
如果发布返回 0,先确认订阅端已经收到 subscribe 确认,再检查发布与订阅使用的频道名称是否完全一致。PUBLISH 和 SUBSCRIBE 不按逻辑数据库编号隔离频道,不应依赖 SELECT 实现频道隔离;需要隔离环境时可采用 dev:events、prod:events 等不同频道前缀。
风险与恢复
- 订阅端断线:重新连接并执行
SUBSCRIBE,恢复后只能接收新消息,不能自动恢复断线期间错过的消息。 - 发布顺序错误:如果消息在订阅成功前发布,应由业务方重新触发事件;Redis 不会自动重放先前的广播。
- 需要可靠消费:使用 Redis Streams 的
XADD、XREADGROUP等命令实现消息保留、消费组读取和待确认消息处理,并设计失败重试机制。 - 消息格式需要演进:建议在结构化消息中包含事件类型、版本及业务标识,由订阅端进行字段验证,不要把简单的字符串事件名当作完整业务状态。
速查:PUBLISH 适合在线即时通知。检查发布结果时同时观察订阅端,不要仅凭返回数字判断业务已完成。需要离线补读或失败恢复时,应使用支持消息持久化的机制。
SUBSCRIBE channel [channel ...]让当前连接持续接收一个或多个频道的发布消息,适合调试实时事件流;订阅者通常需要独立连接,并注意订阅期间的命令模式限制。
订阅实时频道
需要实时观察业务事件、调试消息广播或验证发布者是否正常工作时,使用 SUBSCRIBE 监听指定频道。订阅成功后,Redis 会持续向当前连接推送新消息,直到取消订阅或连接断开。它只接收订阅生效后的消息,不会补发历史消息。
基本语法
SUBSCRIBE channel [channel ...]channel:必填,要监听的频道名称,区分大小写。[channel ...]:可选,可以一次订阅多个频道,例如demo:events和demo:alerts。SUBSCRIBE按频道名称精确匹配,不会将*解释成通配符;需要模式匹配时使用PSUBSCRIBE。
命令自 Redis 2.0.0 起可用。订阅成功后,服务器不是返回一次普通的成功结果,而是为每个频道推送一条 subscribe 确认消息,其中包含频道名称和当前订阅总数。
双终端验证
前置条件:本地 Redis 服务已经启动,redis-cli 可以连接,且当前用户具有相应的订阅与发布权限。下面使用两个终端连接同一个 Redis 实例。
在终端 A 启动订阅,并保持终端运行:
# 独立连接持续监听业务事件频道
redis-cli SUBSCRIBE demo:events预期首先显示订阅确认:
Reading messages... (press Ctrl-C to quit)
1) "subscribe"
2) "demo:events"
3) (integer) 1其中 subscribe 表示订阅确认,demo:events 是频道名称,整数 1 表示当前连接的订阅总数,不是已经收到的消息数。
随后在终端 B 发布测试消息:
# 发布一条测试事件,不占用订阅连接
redis-cli PUBLISH demo:events "hello"如果只有终端 A 这一个匹配的订阅者,预期终端 B 输出:
(integer) 1PUBLISH 的返回整数表示此次发布匹配到的订阅客户端数量,实际数值可能因其他订阅者而变化。
与此同时,终端 A 会追加显示:
1) "message"
2) "demo:events"
3) "hello"三个字段分别表示消息类型、频道名称和消息内容。收到 hello 就证明该频道的实时发布与订阅链路已经连通。继续执行 PUBLISH,订阅端会持续收到后续消息。
连接限制与退出
在 RESP2 协议下,连接进入订阅状态后,只允许执行 SUBSCRIBE、PSUBSCRIBE、相应的取消订阅命令、PING、QUIT 等有限命令,以及 Redis 6.2 起支持的 RESET。不能将这个连接直接当作普通命令连接执行 GET 或 SET。
RESP3 协议允许已订阅连接执行普通命令,但客户端仍需正确处理异步推送。使用 redis-cli SUBSCRIBE 时,命令行进入专用接收模式,通常不能直接输入 UNSUBSCRIBE,应按 Ctrl+C 退出;应用程序则应通过客户端提供的取消订阅接口执行 UNSUBSCRIBE,并管理连接生命周期。
收不到消息时检查
- 确认订阅端先于发布端启动,且已收到
subscribe确认;先发布、后订阅的消息不会补发。 - 检查两端是否连接同一个 Redis 服务或正确的集群,以及频道名称、大小写是否完全一致。
- 如果
PUBLISH返回0,检查是否存在有效订阅者。频道不会按照 Redis 数据库编号隔离,切换SELECT不能创建独立的频道命名空间。 - 如果提示
NOAUTH或NOPERM,分别检查认证信息和 ACL 对频道及命令的授权。 - 如果监听过程中断线,重新建立连接并订阅;断线期间丢失的消息无法通过重新订阅恢复。
速查:SUBSCRIBE 用于持续接收,PUBLISH 用于发送验证,UNSUBSCRIBE 用于取消订阅;在 redis-cli 的订阅模式下按 Ctrl+C 退出。
可确认的流式队列
XADD key [NOMKSTREAM] [KEEPREF | DELREF | ACKED] [IDMPAUTO producer-id | IDMP producer-id idempotent-id] [<MAXLEN | MINID> [= | ~] threshold [LIMIT count]] <* | id> field value [field value ...]向 Stream 追加带字段的事件并生成消息 ID,适合订单和后台任务流水;应规划保留窗口、消费组与幂等处理,避免消息无限增长。
追加消息流事件
订单状态变化、后台任务提交或业务事件需要写入可按 ID 查询的消息流时,使用 XADD。命令将一个或多个字段写入 Redis Stream,成功后返回消息 ID。流不存在时默认自动创建,可结合长度限制控制历史消息数量。
基本语法
XADD key [NOMKSTREAM] [MAXLEN [= | ~] threshold] <* | id> field value [field value ...]以上为常用语法摘要。XADD 从 Redis 5.0 起可用;完整语法还支持 MINID、引用清理策略和生产端幂等选项,使用前需要确认服务器版本。
key:Stream 的键名,例如demo:orders。不存在时默认创建。*:由 Redis 自动生成递增消息 ID,通常优先使用。id:手动指定消息 ID,格式通常为毫秒时间戳-序号,必须大于该 Stream 已使用的最大 ID。field value:消息字段和值,至少提供一组,可以连续提供多组。NOMKSTREAM:键不存在时不创建 Stream,直接返回空值;Redis 6.2 起支持。
自动生成的 ID 通常采用 <毫秒时间戳>-<序号> 格式。消息字段和值作为事件内容保存,后续可使用 XRANGE 按 ID 读取。
关键选项
| 选项 | 作用与使用边界 |
|---|---|
MAXLEN = n |
精确修剪旧消息,使追加后的长度符合指定上限。 |
MAXLEN ~ n |
近似修剪,通常比精确修剪更高效,但实际长度可能超过 n。 |
MINID = id |
删除消息 ID 小于阈值的旧消息,Redis 6.2 起支持。 |
MINID ~ id |
按 ID 进行近似修剪,可能保留部分低于阈值的消息。 |
LIMIT count |
限制修剪期间检查的条目数量;Redis 6.2 起支持。 |
KEEPREF |
修剪时保留消费组待处理列表中的引用,属于默认策略;Redis 8.2 起可显式指定。 |
DELREF |
修剪时同时移除相关消费组的待处理引用,可能影响未确认消息的恢复;Redis 8.2 起支持。 |
ACKED |
仅修剪已被所有消费组确认的消息,可能使实际长度超过配置阈值;Redis 8.2 起支持。 |
IDMP producer-id idempotent-id |
使用固定生产者与幂等 ID 组合识别重复写入;Redis 8.6 起支持。 |
IDMPAUTO producer-id |
由 Redis 自动处理生产端幂等标识;Redis 8.6 起支持。 |
MAXLEN 与 MINID 是两种不同的修剪策略,单次 XADD 只能选择其中一种。长度限制按消息条数计算,并非按消息字节数计算。
常用示例与验证
前置条件:已启动 Redis 5.0 或更新版本,安装 redis-cli,并能够连接本机默认 Redis 服务。以下命令在 Bash 环境执行,使用 demo:orders 作为测试 Stream。
# 保存自动生成的消息 ID;引号避免 shell 展开 *
id=$(redis-cli --raw XADD demo:orders MAXLEN '~' 1000 '*' kind created order_id 42)
echo "new_id=$id"
# 按写入时返回的 ID 查询,避免并发写入影响验证
redis-cli --raw XRANGE demo:orders "$id" "$id"预期输出(示意):
new_id=<ID>
<ID>
kind
created
order_id
42<ID> 是 Redis 实际生成的消息 ID,每次写入通常不同。--raw 使数组响应以逐行文本展示。成功时,XRANGE 查询到的 ID 应与写入返回的 ID 一致,且包含 kind=created、order_id=42 两组字段。
这里的 MAXLEN ~ 1000 表示在追加事件的同时尝试将消息数量控制在约 1000 条附近,并不保证精确上限。如果不需要写入时修剪,可以直接使用元数据中的命令:XADD demo:orders * kind created order_id 42,在 redis-cli 交互模式执行即可。
在 Shell 中直接调用 redis-cli 时,应将 * 写成 '*',防止被展开为当前目录中的文件名。
返回值与失败处理
| 情况 | 结果与处理方法 |
|---|---|
| 正常写入 | 返回新增消息 ID,可用 XRANGE key id id 读取。 |
| Stream 不存在 | 默认自动创建并追加消息。 |
使用 NOMKSTREAM 且键不存在 |
返回空值,不会创建 Stream,也不会写入消息。 |
| 键对应其他数据类型 | 返回 WRONGTYPE 错误;先检查 TYPE key,不要直接覆盖原有数据。 |
| 手动指定的 ID 不大于历史最大 ID | 返回错误;优先改用 * 自动生成 ID。 |
使用 IDMP 识别到重复写入 |
返回首次写入的消息 ID,不再新增重复事件。 |
需要排查写入失败时,可先执行 TYPE demo:orders 确认数据类型,再检查命令参数与 Redis 版本。对业务重试,Redis 8.6 及更新版本可使用固定的 producer-id 和 idempotent-id 组合控制生产端重复写入;旧版本应在应用层维护可靠的事件去重机制。
风险与恢复
XADD 只负责追加消息,写入成功不代表消费组已经处理完成。消费组一般通过 XREADGROUP 获取事件,并在业务处理成功后使用 XACK 确认。生产端幂等与消费端幂等是两个独立问题,不能用写入返回的 ID 代替业务处理确认。
对于必须完整保留的订单或任务流水,不应只依赖有限长度的 Stream。应先把重要事件持久化到数据库、归档系统或其他可靠存储,再按业务保留策略修剪 Stream。已经被修剪且没有外部副本的消息,不能通过 XRANGE 恢复。
Redis 8.6 的 IDMP、IDMPAUTO 在部分非默认 AOF 配置中存在版本特定限制,启用前应核对部署版本的发行说明和持久化配置。
速查:普通追加使用 XADD key * field value;需要限制增长时选择 MAXLEN ~ threshold;需要保护未确认消息时评估 ACKED 策略。完整参数和版本说明参见 Redis XADD 官方文档。
XRANGE key start end [COUNT count]在指定 ID 范围内顺序读取已存储的 Stream 消息,适合核对历史与小批量回放;结束边界包含在内,建议配合 COUNT 限制单次返回。
按消息 ID 查看 Stream 历史
需要核对订单事件、定位某条历史消息,或按 ID 顺序分批读取 Stream 时使用 XRANGE。它返回指定范围内仍然存在的消息及其字段,按消息 ID 升序排列,不会删除消息或改变消费组的确认状态。
基本语法
XRANGE key start end [COUNT count]以上为命令格式,在 redis-cli 交互模式中执行;使用系统 Shell 时需要在命令前添加 redis-cli。
| 参数 | 含义 | 常用写法 |
|---|---|---|
key |
要查询的 Stream 键 | demo:orders |
start |
起始消息 ID,默认包含边界 | - 或具体 ID |
end |
结束消息 ID,默认包含边界 | + 或具体 ID |
COUNT count |
最多返回的消息条数 | COUNT 10 |
- 表示最小 ID,+ 表示最大 ID。使用 - + 可以查询整个 Stream,但没有 COUNT 时可能一次返回大量消息。
Stream ID 通常采用 毫秒时间戳-序列号 格式,例如 1700000000000-0。两个边界默认都是包含关系,因此起始 ID 和结束 ID 相同时,可以用于精确查找单条消息。
常用示例与预期结果
先在测试 Redis 中创建两条消息,再按 ID 范围读取。要求测试键 demo:orders:xrange:58 尚不存在,避免固定 ID 与已有消息冲突。
# 创建两条带固定 ID 的测试消息
redis-cli XADD demo:orders:xrange:58 1700000000000-0 orderId O100 status created
redis-cli XADD demo:orders:xrange:58 1700000001000-0 orderId O101 status paid
# 按 ID 升序读取,最多返回 10 条
redis-cli XRANGE demo:orders:xrange:58 - + COUNT 10预期结果:前两条 XADD 分别返回指定的消息 ID;第三条命令返回两条消息及其完整字段。标准 redis-cli 的结构化输出如下:
1) 1) "1700000000000-0"
2) 1) "orderId"
2) "O100"
3) "status"
4) "created"
2) 1) "1700000001000-0"
2) 1) "orderId"
2) "O101"
3) "status"
4) "paid"其中每条消息都包含 ID 和字段值。即使 COUNT 10 大于实际消息数量,也只返回符合范围的两条记录。
精确定位与分批续读
已知消息 ID 时,把同一个 ID 同时作为起始和结束边界,即可查询该消息;如果消息不存在或已被删除,则返回空数组。
对于大量历史消息,推荐记录上一批最后一条消息的 ID,再从该 ID 之后继续查询。Redis 6.2 及以上版本支持在边界 ID 前添加 (,表示不包含该 ID。
# 从第一条消息之后继续读取,避免重复
redis-cli XRANGE demo:orders:xrange:58 '(1700000000000-0' + COUNT 10预期结果:只返回 ID 为 1700000001000-0 的消息,包含 orderId=O101 和 status=paid,不会再次返回第一条消息。
在 Bash 中,包含 ( 的参数应使用引号包裹,避免 Shell 将其解释为特殊语法。交互式 redis-cli 中可直接输入不带引号的排他边界。
实际分页时,按以下顺序操作:
- 首次使用
XRANGE key - + COUNT 100获取第一批数据。 - 保存返回结果中最后一条消息的完整 ID。
- 下一次将该 ID 作为排他起点,并继续设置
COUNT 100。 - 处理当前批次后重复查询,直到返回空数组。
若需要限制读取范围,可以将结束边界 + 替换为具体 ID。分页过程应保持固定结束边界,以免把后续新增消息混入既定历史查询范围。
风险与边界
- 返回范围:
XRANGE只能读取当前 Stream 中仍然保留的消息。经过XDEL删除或XTRIM裁剪的记录无法通过该命令恢复,必要时应从备份或原始事件来源恢复。 - 性能控制:查询大范围历史时始终优先设置
COUNT,并按最后一个 ID 分页。单次返回条数越多,网络传输量和客户端内存占用通常越高。 - 消费语义:
XRANGE是只读历史查询,不会创建消费者组待处理记录,也不会执行XACK。需要可靠消费与确认时应使用XREADGROUP等消费组命令。 - 错误排查:键不存在时返回空数组;如果键存在但不是 Stream 类型,则会返回
WRONGTYPE错误。可使用TYPE key检查键类型。 - 版本范围:
XRANGE从 Redis 5.0 开始提供;通过(指定排他范围的能力从 Redis 6.2 开始支持。
XREAD [COUNT count] [MAXCOUNT maxcount] [MAXSIZE maxsize] [BLOCK milliseconds] STREAMS key [key ...] id [id ...]从给定 ID 之后读取一个或多个 Stream,适合无消费组的事件跟踪;阻塞等待需使用专用连接,不能自动形成待确认消息记录。
直接读取消息流
需要查看 Stream 历史事件或按游标拉取新增消息、且不需要消费组确认机制时使用 `XREAD`。它返回给定 ID 之后的条目;调用者需要保存每个 Stream 最后读到的 ID,下一轮继续传入,避免重复读取。
基本语法
XREAD [COUNT count] [MAXCOUNT maxcount] [MAXSIZE maxsize] [BLOCK milliseconds] STREAMS key [key ...] id [id ...]`STREAMS` 后先列出全部键,再按照相同顺序列出等量起始 ID。每个 ID 都对应一个 Stream,读取结果不包含该 ID 本身。
- `0-0`:从已有记录的最早位置开始读取。
- 具体 ID:只返回 ID 严格大于该值的记录,适合连续分页或断点续读。
- `$`:以调用时的最新位置为起点,只等待之后写入的新记录,不回放已有历史。通常配合 `BLOCK` 使用。
例如同时读取两个 Stream 时,`STREAMS orders payments 0-0 0-0` 表示分别从两个流的起点读取。不能把键和 ID 交替排列。
关键选项
| 选项 | 含义与约束 |
|---|---|
| `COUNT n` | 每个 Stream 最多返回 n 条记录,不是所有流合计 n 条。 |
| `BLOCK ms` | 没有符合条件的记录时最多等待指定毫秒数;`0` 表示无限等待。 |
| `MAXCOUNT n` | Redis 8.10+,限制所有 Stream 合计返回的记录数,必须为正整数;与 `COUNT` 同用时不能小于 `COUNT`。 |
| `MAXSIZE bytes` | Redis 8.10+,限制整个回复的字节大小;至少允许返回一条记录,因此单条大消息可能超过上限。 |
不设置 `BLOCK` 时立即返回结果;没有符合条件的消息则返回空响应。设置阻塞读取时,建议使用专用 Redis 连接,避免长时间占用需要处理其他请求的连接。
可验证示例
前置条件:能够通过本地 `redis-cli` 连接 Redis,且测试键 `demo:xread:verify` 尚不存在。使用固定 ID 是为了让输出可核对,实际业务写入通常使用 `XADD` 的 `*` 自动生成 ID。
# 在全新的测试 Stream 中写入两条可预测的消息
redis-cli XADD demo:xread:verify 1-0 event placed
redis-cli XADD demo:xread:verify 2-0 event shipped
# 从起点读取,最多返回每个 Stream 的 10 条消息
redis-cli XREAD COUNT 10 STREAMS demo:xread:verify 0-0预期输出(默认 `redis-cli` 的 RESP2 风格展示):
"1-0"
"2-0"
1) 1) "demo:xread:verify"
2) 1) 1) "1-0"
2) 1) "event"
2) "placed"
2) 1) "2-0"
2) 1) "event"
2) "shipped"前两条命令分别返回写入成功的消息 ID。第三条返回 Stream 名称及两条完整记录,每条包含 ID 和字段值。不同 RESP 协议模式或客户端的显示格式可能不同,但记录内容应一致。
再次读取时传入 `2-0`,即可跳过已经读取的两条消息。如果没有新消息且未指定 `BLOCK`,结果通常显示为 `(nil)`。
连续读取与阻塞等待
普通轮询应把本次返回的最后一条 ID 作为下一次读取的起点。多 Stream 场景需要分别维护每个键的游标,不能把某个流的最后 ID 直接用于其他流。
只关心新消息时,可以指定 `\` 并配合 \`BLOCK\`。例如等待最多 3000 毫秒,超时后返回空响应;若使用 \`BLOCK 0\`,则一直等待直到有可返回的数据或连接中断。Shell 中建议将 \`` 写为 `'$'`,避免与变量展开规则混淆。
风险与恢复
`XREAD` 不会创建消费组待确认列表(PEL),也不能依靠 `XACK` 确认这些读取结果。需要多个消费者分工、消息确认或处理超时后的认领恢复时,应使用 `XREADGROUP`,并配合 `XACK` 和相应的待处理消息恢复机制。
使用 `XREAD` 实现业务消费时,应在处理成功后持久化对应游标,并使业务处理具备幂等性:如果处理成功但尚未保存游标就发生故障,重启后可能重新读取同一消息;若在处理前推进游标,则可能遗漏尚未处理的消息。
测试键已经存在时,不要直接重放示例中的固定小 ID,否则 `XADD` 可能因 ID 不大于已有最大 ID 而报错。应换用新的测试键,而不是删除业务 Stream。Redis 5.0 起支持 `XREAD`;`MAXCOUNT`、`MAXSIZE` 需要 Redis 8.10 或更新版本。具体版本及返回约束见 Redis 官方 XREAD 文档。
XGROUP CREATE key group <id | $> [MKSTREAM] [ENTRIESREAD entries-read]为 Stream 建立消费者组,适合多工作者分担可确认消息;从零开始处理历史消息或从 $ 开始只处理新消息需在创建时明确选择。
创建消费者组
当一个 Redis Stream 需要由多个工作者分担消息,并通过 XACK 确认处理结果时,使用 XGROUP CREATE 建立消费者组。创建时必须选择读取起点:使用 0 可以处理已有消息,使用 $ 则从创建时的流末尾开始,只接收后续新消息。
基本语法
XGROUP CREATE key group <id | $> [MKSTREAM] [ENTRIESREAD entries-read]以上为 Redis 命令语法摘要,尖括号和方括号表示参数规则,不应原样粘贴到 Shell。通过终端执行时,需要在命令前添加 redis-cli,或进入 Redis CLI 交互模式。
| 参数 | 含义与约束 |
|---|---|
key |
目标 Stream 的键名,必须不存在或属于 Stream 类型。 |
group |
新消费者组名称,同一个 Stream 内不得重名。 |
id |
组的初始最后投递 ID,可指定有效消息 ID,常用 0 或 $。 |
MKSTREAM |
目标键不存在时自动创建空 Stream;省略时要求 Stream 已存在。 |
ENTRIESREAD entries-read |
初始化组的已读条目计数,用于计算消费延迟 lag;Redis 7.0 起支持,通常无需手动指定。 |
命令成功时返回 OK。它只负责创建消费者组,不会自动启动消费者、读取消息或执行消息确认。
读取起点怎么选
id 表示消费者组视角下最后已经投递到的位置,而不是第一条需要读取的消息。消费者随后通过 XREADGROUP ... STREAMS key > 获取尚未投递给该组的新消息。
| 起始 ID | 首次读取行为 | 适用场景 |
|---|---|---|
0 |
从当前保留的历史消息开始读取。 | 新部署工作者,需要处理积压任务。 |
$ |
跳过创建组时已有的消息,只读取随后追加的消息。 | 上线实时处理任务,不需要回放历史。 |
| 具体消息 ID | 从指定 ID 之后读取。 | 已明确历史处理边界,需要从特定位置继续。 |
例如,Stream 已包含订单 A、B、C。使用 0 创建组后,消费者可以通过 > 读取这些历史订单;使用 $ 创建组后,消费者要等订单 D 等新消息追加后才能读到内容。
创建并验证
前置条件:已安装 redis-cli,能够访问具有写入权限的 Redis 5.0 或更高版本实例。以下示例假定 demo:orders 不存在,或已经是 Stream,且其中尚未建立名为 workers 的消费者组。
# 从历史消息起点创建消费者组,不存在时自动创建空 Stream
redis-cli XGROUP CREATE demo:orders workers 0 MKSTREAM
# 确认键类型,以及消费者组是否存在
redis-cli TYPE demo:orders
redis-cli XINFO GROUPS demo:orders预期结果:第一条命令返回 OK,第二条返回 stream。第三条的消费者组信息中能够找到 name 为 workers 的记录;对于新建的空 Stream,last-delivered-id 为 0-0。XINFO GROUPS 的实际排版及其他统计字段可能随 Redis 版本和运行状态变化。
创建完成后,工作者可以使用 XREADGROUP GROUP workers consumer-1 STREAMS demo:orders > 读取新消息。成功处理消息后再通过 XACK 确认,未确认的投递记录会保留在该组的 Pending Entries List(PEL)中。
常见失败与恢复
| 现象 | 原因 | 处理方式 |
|---|---|---|
BUSYGROUP |
同一个 Stream 中已存在同名消费者组。 | 使用 XINFO GROUPS demo:orders 检查已有组,不要重复创建。 |
| Stream 不存在错误 | 目标键不存在且没有指定 MKSTREAM。 |
确认键名无误,允许自动建流时添加 MKSTREAM。 |
WRONGTYPE |
目标键存在,但数据类型不是 Stream。 | 用 TYPE demo:orders 检查;更换键名或先处理错误类型的数据。 |
| 选错起始 ID | 创建时将 0 和 $ 混淆。 |
先检查现有读取进度,再谨慎使用 XGROUP SETID 调整位置。 |
已经创建的消费者组不能通过再次执行 XGROUP CREATE 覆盖。若要调整读取起点,可使用 XGROUP SETID demo:orders workers 0,但这不会清空已有的待确认消息;执行前应先通过 XPENDING demo:orders workers 检查待确认状态,避免重复处理或遗漏。
确实需要撤销误建的消费者组时,可以执行 XGROUP DESTROY demo:orders workers。成功删除返回 1,不存在的组返回 0。删除会清除该组的消费者信息和待确认记录,但不会删除 Stream 本身;如需恢复,只能重新建组,并从仍然保留在 Stream 中的消息开始处理。