Redis 与缓存 / 知识点
Redis 开发常用命令速查
字符串与缓存生命周期
UNLINK key [key ...]从键空间摘除键并将内存回收主要交给后台线程,适合清理大键降低阻塞风险;它同样是不可逆的删除操作,必须核实范围。
异步释放指定键
需要删除大型 Hash、List、Set、Sorted Set 等键,同时尽量减少内存回收对 Redis 主线程的阻塞时,使用 UNLINK。命令会先从键空间摘除目标键,使其立即无法被正常读取,再将主要内存回收工作交给后台线程处理。删除不可撤销,且内存占用不保证立即下降。
基本语法
UNLINK key [key ...]key:要删除的键名,至少指定一个,可以同时指定多个。[key ...]:可选的其他键名,使用空格分隔。- 返回值:整数,表示实际从键空间删除的键数量。
- 不存在的键会被忽略,不计入返回值,也不会因此报错。
例如同时指定三个键,其中只有两个存在,成功执行后返回 2。如果所有目标键均不存在,则返回 0。
UNLINK 不支持通过 *、? 等通配符直接匹配键名。传入的参数是具体键名,而不是自动展开的键模式。
可验证示例
前置条件:Redis 服务正在运行,已安装 redis-cli,并且当前终端可以连接到测试实例。以下使用 Bash 和默认连接参数,使用带当前 Shell 进程号的临时键,避免直接操作业务数据。
# 使用进程号构造演示键,降低与现有键冲突的可能性
key="anystack:unlink:demo:$$"
# NX 防止覆盖已有键;创建失败时不执行删除
if [ "$(redis-cli --raw SET "$key" temporary NX)" = "OK" ]; then
redis-cli --raw UNLINK "$key"
redis-cli --raw EXISTS "$key"
redis-cli --raw UNLINK "$key"
else
echo '演示键创建失败,已跳过删除'
fi首次创建成功且后续命令正常执行时,预期输出:
1
0
0三个数字依次表示:
UNLINK返回1,说明一个存在的键已被删除。EXISTS返回0,说明该键已经不在键空间中。- 再次执行
UNLINK返回0,说明不存在的键不会重复计数。
如果显示“演示键创建失败,已跳过删除”,应检查 Redis 连接、权限或键名冲突,不应绕过创建检查直接执行删除。
返回结果与内存回收
UNLINK 的执行结果需要区分两个阶段:键空间中的删除完成,以及相关内存的实际释放完成。
- 键空间删除:命令成功返回后,目标键对后续正常读取已不可见,
EXISTS返回0。 - 内存回收:对象主要通过后台机制释放;即使
UNLINK已返回成功,内存指标也可能暂时没有明显变化。 - 复杂度:从键空间摘除每个键的操作为 O(1);后台回收仍需要与对象内部内存分配数量相关的工作量。
可以通过 INFO memory 观察 used_memory 和 lazyfree_pending_objects 等指标。后者表示等待异步释放的对象数量,但小对象或已经完成的回收任务可能不会形成明显积压。
不要只根据操作系统显示的 RSS 是否立即下降判断删除是否成功。Redis 释放对象后,内存分配器也不一定立即把物理内存归还操作系统。
风险与恢复
执行生产环境删除前,应完成以下检查:
- 确认 Redis 实例、数据库和目标键名,避免连接到错误环境。
- 使用
EXISTS判断键是否存在,必要时通过TYPE、TTL和MEMORY USAGE检查键的类型、剩余有效期与内存占用。 - 核实目标键是否仍被业务使用,尤其是会话、订单状态、锁和任务队列相关数据。
- 批量删除前先明确生成的键名清单,抽样核对,再控制每批操作数量。
- 确认存在可用的备份或业务数据重建手段后,再执行不可逆删除。
Redis Cluster 中,多键 UNLINK 通常要求目标键位于同一哈希槽,否则可能返回 CROSSSLOT 错误。对于不同哈希槽的键,应按槽分组执行或逐键删除,不能假定一次命令可以跨节点删除全部目标。
如果误删,只能依据可用的备份、业务源数据或应用重建机制恢复;Redis 不提供对应的 UNLINK 撤销命令。
UNLINK 自 Redis Open Source 4.0.0 起可用。需要清理大键时优先考虑它,但大量删除操作仍需分批控制,避免后台回收任务积压或给业务带来集中缓存失效压力。
DELEX key [IFEQ ifeq-value | IFNE ifne-value | IFDEQ ifdeq-digest | IFDNE ifdne-digest]仅在字符串值或摘要满足条件时删除键,适合按令牌释放租约;Redis 8.4 起可用,调用方仍需处理锁过期与并发执行边界。
按值条件安全删除
释放 Redis 租约或分布式锁时,如果只允许持有指定令牌的客户端删除键,使用 `DELEX key IFEQ token`。它在 Redis 服务端原子地完成比较和删除,避免先 `GET` 再 `DEL` 期间锁已被其他客户端重新获取的问题。Redis 8.4.0 起支持该命令。
基本语法
DELEX key [IFEQ ifeq-value | IFNE ifne-value | IFDEQ ifdeq-digest | IFDNE ifdne-digest]`key` 是待删除的键。方括号中的条件可省略;如果指定条件,四种比较方式只能选择一种。
| 条件 | 删除条件 | 适用场景 |
|---|---|---|
| `IFEQ value` | 当前字符串值等于指定值 | 按所有者令牌释放租约 |
| `IFNE value` | 当前字符串值不等于指定值 | 清理不符合指定值的缓存 |
| `IFDEQ digest` | 当前字符串值的摘要等于指定摘要 | 按摘要执行条件删除 |
| `IFDNE digest` | 当前字符串值的摘要不等于指定摘要 | 清理摘要不匹配的数据 |
省略条件时,`DELEX key` 会无条件删除存在的键,且不限制键的数据类型。释放锁时必须使用所有者校验,不能省略 `IFEQ`。
安全释放租约示例
以下命令适用于 Redis 8.4+,要求本地已安装 `redis-cli`、能够连接测试 Redis,且测试键最初不存在。真实业务应为每次成功获取的租约生成不可预测且足够唯一的令牌,不要复用示例中的固定值。
# 创建带 120 秒有效期的测试租约,NX 防止覆盖已有持有者
redis-cli SET demo:delex:lease token-A NX PX 120000
# 错误所有者不能释放该租约
redis-cli DELEX demo:delex:lease IFEQ token-B
redis-cli GET demo:delex:lease
# 正确所有者释放租约并检查键是否消失
redis-cli DELEX demo:delex:lease IFEQ token-A
redis-cli EXISTS demo:delex:lease预期输出(按命令执行顺序,假设测试期间租约未过期):
OK
0
token-A
1
0结果说明:
- `SET` 返回 `OK`:成功创建租约;如果键已存在,`NX` 会阻止覆盖,必须先确认测试前置条件。
- 第一次 `DELEX` 返回 `0`:令牌不匹配,没有删除键。
- `GET` 返回 `token-A`:证明错误令牌未删除租约。
- 第二次 `DELEX` 返回 `1`:令牌匹配,键已被删除。
- `EXISTS` 返回 `0`:确认测试键不再存在。
这里的 `GET` 仅用于展示和诊断。实际释放操作只需要携带自己保存的令牌执行一次 `DELEX ... IFEQ ...`,不要将 `GET` 的结果作为随后无条件删除的依据。
返回值与版本边界
| 返回结果 | 含义 | 调用方处理 |
|---|---|---|
| 整数 `1` | 条件满足且成功删除 | 记录释放成功 |
| 整数 `0` | 键不存在或条件不满足 | 按未删除处理,不得改用无条件删除 |
| 错误响应 | 例如带条件操作遇到非字符串键 | 检查键类型与调用参数 |
Redis 8.4 中,指定 `IFEQ`、`IFNE`、`IFDEQ` 或 `IFDNE` 时,已有键必须是字符串类型,否则会返回类型错误。不存在的键返回 `0`,而不是类型错误。
摘要由 XXH3 算法计算,可通过 `DIGEST key` 获取。`IFEQ`、`IFNE` 的时间复杂度为 O(1);`IFDEQ`、`IFDNE` 为 O(N),其中 N 是字符串值的长度。摘要比较存在哈希碰撞的理论可能,不应代替所有者令牌的安全校验。
Redis 8.4 之前没有 `DELEX` 命令。如果需要兼容旧版本,可以使用 Lua 脚本在服务端原子完成值比较和删除,不能使用客户端分开的 `GET` 与 `DEL` 替代。
风险与恢复
- **租约已过期**:原持有者应停止依赖旧租约执行受保护的操作;需要继续工作时,应按业务规则重新申请租约并取得新令牌。
- **返回 `0`**:可能是租约已过期、已被释放,或被其他持有者重新获取。检查令牌、有效期和业务日志,不要为了清理键而退化为 `DEL`。
- **误删键**:成功删除后不能通过 `DELEX` 撤销。如果误删的是锁,应通过正常的竞争获取流程重新创建租约,不能直接恢复旧令牌或无条件覆盖其他持有者。
- **业务执行超过租约时间**:即使原持有者随后无法删除新持有者的锁,旧任务仍可能产生过期写入。对严格要求互斥的外部资源操作,应额外考虑续租控制、超时停止执行或 fencing token 等机制。
速查判断:释放自己持有的字符串租约,优先使用 `DELEX key IFEQ token`;返回 `1` 才表示本次确实删除了键,返回 `0` 时不要强制删除。
对象字段读写
HSET key field value [field value ...]写入哈希对象的一个或多个字段,适合用户资料及稀疏属性;已有字段会覆盖,返回值表示新增字段数而不是成功写入的字段总数。
写入对象字段
需要创建或更新用户资料、商品属性等 Redis Hash 字段时,使用 HSET。一次可以写入一个或多个字段;不存在的哈希键会自动创建,已有字段的值则直接覆盖。执行后通过 HGET 或 HMGET 读取实际保存的值。
基本语法
HSET key field value [field value ...]key:哈希对象的 Redis 键名,例如demo:user:42。field:哈希内部的字段名,例如name、level。value:要保存的字段值,例如Ada、3。[field value ...]:可选的额外字段和值,必须成对出现。
例如,HSET demo:user:42 name Ada level 3 会写入 name=Ada 和 level=3。字段值以字符串形式保存,数字 3 不会自动变成独立的数值数据类型。
HSET 自 Redis 2.0.0 起可用;一次写入多个字段的语法要求 Redis 4.0.0 或更新版本。每个字段值对的平均时间复杂度为 O(1),写入 N 个字段时整体为 O(N)。
返回值与覆盖规则
HSET 返回整数,表示本次新增加的字段数量,而不是实际写入或更新的字段总数。
| 写入情况 | 返回值 | 实际效果 |
|---|---|---|
| 新哈希写入两个不同字段 | 2 |
创建哈希并新增两个字段 |
| 已有字段更新为新值 | 0 |
字段值已成功覆盖 |
| 一个新字段、一个已有字段 | 1 |
新增一个并更新一个 |
因此,返回 0 不代表写入失败。判断写入是否成功,应结合命令是否报错,以及读取后的字段值。
可验证示例
前置条件:已安装 redis-cli,并有可写的测试 Redis 实例。以下命令默认连接本机 127.0.0.1:6379,使用一次性键名避免覆盖已有业务数据。
# 使用时间戳和进程号生成临时键,避免与已有数据冲突
key="demo:hset:check:$(date +%s)-$$"
redis-cli HSET "$key" name Ada level 3
redis-cli HSET "$key" level 4
redis-cli HMGET "$key" name level
# 验证后仅删除本示例创建的临时键
redis-cli DEL "$key"预期输出(使用非交互式 redis-cli):
2
0
Ada
4
1第一条 HSET 新增两个字段,因此返回 2。第二条覆盖已有的 level,返回 0。HMGET 证明 name 保持为 Ada,而 level 已从 3 更新为 4。最后的 DEL 删除测试键,返回 1。
临时键后缀由执行时间和进程号生成,实际值会变化;在测试键没有被其他操作修改的前提下,上述结果可复现。
风险与恢复
- 覆盖不可自动撤销:
HSET不保留旧字段值。修改重要字段前先使用HGET key field读取旧值;需要恢复时,再用HSET key field oldValue写回。若事先没有保存旧值,只能依赖其他可信数据来源或备份。 - 避免误判返回值:返回
0可能是正常覆盖。如果只允许创建不存在的字段,改用HSETNX key field value;它一次只处理一个字段。 - 键类型必须正确:如果
key已存在但不是 Hash,命令会返回WRONGTYPE错误。先通过TYPE key检查类型,不要为消除错误而直接删除未知业务键。 - 注意过期范围:普通
HSET不会自动设置过期时间,也不会清除已有的键级 TTL。需要控制整个哈希的过期时间时,另行使用EXPIRE key seconds。 - 批量写入注意字段数量:多个字段值对作为一条 Redis 命令执行,但字段越多,命令处理和网络传输成本越高。大量字段应根据实际负载分批组织,不要把全部业务对象无限堆积在同一个哈希中。
速查判断:HSET 用于新增或覆盖字段;看返回整数判断新增数量,用 HGET 或 HMGET 验证最终值。
HGET key field读取哈希键内的指定字段,适合只取业务需要的属性;字段或键不存在时返回空值,可避免每次传输完整的用户或配置对象。
当业务只需要读取用户姓名、配置项或订单状态等单个属性时,使用 HGET 从 Redis 哈希中获取指定字段,不必读取整个对象。该命令是只读操作,不会修改字段值,也不会刷新键的过期时间。
基本语法
HGET key fieldkey:Redis 中的哈希键,例如demo:user:42。field:要读取的字段名,例如name。字段名区分大小写,必须精确匹配。
命令的时间复杂度为 O(1),适合按已知字段名进行单字段读取,不支持通配符匹配或按字段名前缀检索。
返回值与边界
| 条件 | 返回结果 |
|---|---|
| 键和字段均存在 | 字段保存的字符串值 |
| 哈希键不存在 | nil(空响应) |
| 哈希存在但字段不存在 | nil(空响应) |
| 键存在但不是哈希类型 | WRONGTYPE 错误 |
| 字段存在且值为空字符串 | 空字符串,不是 nil |
Redis 协议能够区分 nil 与空字符串,但 redis-cli --raw 的终端显示可能让两者看起来都是空行。需要判断字段是否真正存在时,应结合 HEXISTS,不要仅凭打印内容判断。
常用示例
前置条件:Redis 服务已启动,本机已安装 redis-cli,并且当前连接具备哈希读写权限。以下命令在测试实例执行,第一条用于准备数据,后两条分别读取字段和检查字段是否存在。
# 准备一个包含 name 字段的测试哈希
redis-cli --raw HSET demo:user:42 name Ada
# 精确读取 name,不传输其他字段
redis-cli --raw HGET demo:user:42 name
# 验证该字段确实存在
redis-cli --raw HEXISTS demo:user:42 name预期输出(name 原先不存在时):
1
Ada
1第一行 1 表示 HSET 新增了字段;如果该字段原先已存在,第一行会返回 0,表示覆盖已有字段。第二行 Ada 是实际读取值,第三行 1 表示字段存在。无论字段此前是否存在,执行准备命令后,后两条的结果均应保持一致。
这里使用 --raw 让字符串结果直接显示为 Ada,不带交互模式中的引号和类型标记。如果 Redis 不在默认地址,需根据实际连接配置提供 -h、-p、-a 或其他认证参数;不要在共享终端记录中暴露密码。
缺失字段的排查
遇到空值时,可按以下顺序检查,避免将字段缺失误判为数据为空字符串。
- 使用
EXISTS demo:user:42检查键是否存在。返回0表示键不存在,可能尚未写入或已经过期。 - 使用
TYPE demo:user:42检查键类型。正常哈希应返回hash;返回none表示键不存在,其他类型不能直接执行HGET。 - 使用
HEXISTS demo:user:42 name检查指定字段。返回1表示字段存在,返回0表示不存在。 - 如果字段存在但业务显示为空,检查写入值是否为空字符串,以及客户端是否错误地将空字符串、nil 和字段缺失合并处理。
这些检查命令均不会修改 Redis 数据。若确认字段未写入,应排查上游写入逻辑,而不是在读取路径中随意填充默认值并覆盖已有数据。
使用边界与注意事项
HGET每次只读取一个字段。需要同时获取多个已知字段时,可以使用HMGET,减少客户端与 Redis 之间的请求次数。- 需要获取全部字段时可以使用
HGETALL,但大型哈希会产生较大的响应;不应为了读取name一个字段而传输完整对象。 - 字段名区分大小写:
name与Name是两个不同字段。读取不到数据时应先核对业务字段命名。 HGET不会延长键的 TTL。如果业务需要延长有效期,应在明确缓存策略后单独处理过期时间。- 示例中的
HSET会写入或覆盖测试字段;生产排查时仅执行读取与检查命令,避免修改真实用户数据。
速查:已知哈希键和字段名时使用 HGET;无法区分缺失与空字符串时使用 HEXISTS;遇到 WRONGTYPE 时先用 TYPE 核对键的数据类型。
HMGET key field [field ...]按指定顺序取回同一哈希中的多个字段,适合详情页的字段投影;缺失字段保留空值位置,客户端需要按字段名正确映射。
一次读取多个字段
当详情页只需要 Redis 哈希中的 `name`、`level` 等部分字段时,使用 `HMGET` 一次取回指定字段的值,减少逐字段读取的请求次数。返回值严格对应请求字段的顺序,缺失字段保留空值位置,适合按字段列表构建业务对象。
基本语法
HMGET key field [field ...]- `key`:目标哈希键,一次只能查询一个哈希。
- `field`:必填,至少指定一个字段。
- `[field ...]`:可选的其他字段,按输入顺序依次读取。
`HMGET` 是只读命令,不会创建或修改字段。时间复杂度为 ,其中 是本次请求的字段数量。字段名需要明确指定,不支持通过通配符自动展开字段。
常用示例与预期结果
前置条件:Redis 服务已启动,`redis-cli` 可以连接目标测试实例。以下示例假设演示键 `demo:hmget:25` 原先不存在。
# 准备两个哈希字段,避免依赖已有数据
redis-cli --no-raw HSET demo:hmget:25 name Ada level 7
# 同时读取两个已有字段与一个不存在的字段
redis-cli --no-raw HMGET demo:hmget:25 name level nickname预期输出:
(integer) 2
1) "Ada"
2) "7"
3) (nil)第一项 `(integer) 2` 是 `HSET` 新增的字段数量;如果字段原先已存在,新增数量可能不同。`HMGET` 的三个返回位置分别对应 `name`、`level`、`nickname`,其中 `(nil)` 表示第三个字段不存在。
使用 `--no-raw` 可以强制 `redis-cli` 显示带序号和类型信息的结果,避免非交互式终端使用原始输出格式时丢失直观的空值标记。
返回值与字段映射
`HMGET` 返回一个数组,数组长度与请求字段数量相同,不会因为字段不存在而跳过位置,也不会在结果中附带字段名。
例如执行 `HMGET demo:user:42 name level`,返回数组的第一个元素对应 `name`,第二个元素对应 `level`。客户端应保存请求时的字段顺序,按下标建立字段名与返回值之间的对应关系。
需要特别区分以下情况:
- **字段存在**:返回字段保存的字符串值,例如 `"7"`;业务代码需要时再转换成数字。
- **字段不存在**:返回空值,RESP2 中为 nil,RESP3 中为 null;不是空字符串。
- **整个键不存在**:Redis 将其视为空哈希,所有请求位置都返回空值。
- **键存在但类型不是哈希**:返回 `WRONGTYPE` 错误,不会返回部分字段值。
不能先过滤空值再按原始字段顺序映射,否则一个字段缺失就可能导致后续字段全部错位。需要进一步区分字段不存在和空字符串时,可以使用 `HEXISTS` 检查字段是否存在。
与其他读取命令的选择
| 命令 | 读取范围 | 适用情况 |
|---|---|---|
| `HGET` | 一个指定字段 | 只需要单个属性 |
| `HMGET` | 同一哈希的多个指定字段 | 详情页字段投影、批量读取固定属性 |
| `HGETALL` | 哈希中的全部字段和值 | 确实需要完整对象且字段规模可控 |
`HMGET` 只针对同一个哈希键。如果需要读取多个不同键,不能把多个键作为参数传给 `HMGET`,应由客户端分别查询或使用适当的批量请求机制。
风险与恢复
`HMGET` 本身没有写入副作用,误读不需要回滚。示例中的 `HSET` 会创建或覆盖指定字段,应仅在测试环境运行;如果误写生产数据,需要依据原始值记录或备份恢复,不能直接删除整个哈希键。
当结果与预期不一致时,先检查键名、字段拼写和键类型,再确认是否把空值误处理为空字符串。字段映射异常时,应保留原始返回数组及请求字段列表,重新按对应下标映射,而不是删除空值后重新排列。
HGETALL key获取哈希中全部字段和值,适合字段规模可控的小对象;若字段数量很大,单次返回会增加网络和解析成本,应改用 HSCAN。
读取整个哈希对象
需要一次获取 Redis 哈希键中的全部字段和值时,使用 HGETALL。适合读取用户资料、业务属性和小型配置对象。命令不会修改数据,返回结果可按字段名组装为应用程序中的对象。
基本语法
HGETALL keykey:要读取的 Redis 哈希键名,例如demo:user:42。- 返回内容:哈希中全部字段及其对应值,不支持指定字段范围或分页。
- 时间复杂度:
O(N),其中N为哈希中的字段数量。
HGETALL 在 RESP2 协议中返回交替排列的字段和值,在 RESP3 中返回映射。通过 redis-cli 查看时,通常按字段和值逐对显示。字段返回顺序没有保证,应用程序不能依赖固定位置识别字段。
可复现示例
前置条件:本地 Redis 服务已启动,redis-cli 可以连接。以下示例使用测试数据库中尚不存在的 demo:hgetall:sample,避免覆盖已有数据。
# 创建包含三个字段的测试哈希
redis-cli HSET demo:hgetall:sample name Lin role editor enabled 1
# 读取全部字段和值,使用 --raw 简化显示
redis-cli --raw HGETALL demo:hgetall:sample
# 验证哈希的字段数量
redis-cli HLEN demo:hgetall:sample预期输出(字段顺序可能不同):
(integer) 3
name
Lin
role
editor
enabled
1
(integer) 3第一行表示 HSET 新增了三个字段;中间六行是 HGETALL 返回的三组字段和值;最后一行表示 HLEN 确认哈希包含三个字段。
读取结果中的 enabled 对应字符串 1,不是布尔类型。Redis 哈希字段和值都以字符串数据存储,应用程序应根据业务字段定义转换数字、布尔值或其他数据类型。
空键与类型错误
| 场景 | 结果 | 处理方式 |
|---|---|---|
| 哈希键存在 | 返回全部字段和值 | 按字段名解析,不依赖返回顺序 |
| 键不存在 | 返回空集合或空映射 | 按业务需要处理为空对象或不存在 |
| 键属于其他数据类型 | 返回 WRONGTYPE 错误 |
使用 TYPE 检查键类型 |
| 字段很多 | 一次读取全部字段和值 | 改用 HSCAN 分批遍历 |
Redis 哈希删除最后一个字段后,整个键也会消失。因此,空结果不代表连接异常,也不能仅凭 HGETALL 区分从未创建和已经删除的键。
遇到 WRONGTYPE 时,先检查实际键类型,不要直接删除或覆盖数据。HGETALL 仅适用于哈希键,无法读取字符串、列表或集合中的内容。
大哈希的替代读取
HGETALL 会一次返回整个哈希。字段数量大或字段值较长时,可能增加 Redis 命令执行时间、网络流量和客户端内存占用。尤其不要在高频请求路径中反复读取大型哈希。
- 读取单个字段:使用
HGET key field,只返回指定字段的值。 - 读取多个已知字段:使用
HMGET key field [field ...],避免获取无关字段。 - 遍历大量字段:使用
HSCAN key cursor [MATCH pattern] [COUNT count],逐批处理直到返回游标为0。
HSCAN 的 COUNT 是扫描工作量提示,不保证每次返回固定数量的字段。遍历期间如果哈希发生变化,结果可能包含重复字段,也不保证包含遍历期间新增或删除的全部内容。需要严格一致的对象快照时,不能将普通 HSCAN 遍历直接视为原子读取。
风险与恢复
HGETALL 是只读命令,不需要数据恢复操作,但应注意读取量与数据泄露风险。用户资料或业务哈希可能包含敏感字段,排障时不要把完整返回值直接写入共享日志。
HINCRBY key field increment原子增加或减少哈希中的整数字段,适合对象级统计和轻量额度;缺失字段从零开始,不能直接用于浮点字段或带约束的库存事务。
原子修改数值字段
需要并发增加或减少用户积分、访问次数、累计数量等哈希整数字段时,使用 `HINCRBY`。Redis 在单条命令中原子完成数值修改并返回新值,避免客户端先 `HGET`、计算、再 `HSET` 导致的并发覆盖。
基本语法
HINCRBY key field increment| 参数 | 含义 | 约束 |
|---|---|---|
| `key` | 存放哈希对象的 Redis 键 | 已存在时必须为 Hash 类型 |
| `field` | 要修改的哈希字段 | 已有值必须能表示为整数 |
| `increment` | 本次增加的整数 | 正数增加、负数减少、零保持数值不变 |
三个参数均为必填,没有默认增量。命令时间复杂度为 `O(1)`,返回修改后的字段整数值,而不是实际增加的数量。
缺失字段与数值边界
- **键不存在**:Redis 自动创建 Hash,并将目标字段视为从零开始累加。
- **字段不存在**:初始值按 `0` 处理。例如首次执行 `HINCRBY demo:user:42 points 10`,返回 `10`。
- **字段已存在**:在原整数基础上增加指定增量。`increment` 为 `-3` 表示减去三。
- **数值范围**:字段值及运算结果必须处于有符号 64 位整数范围,即 `-9223372036854775808` 至 `9223372036854775807`。超出范围会报错,不会自动截断或回绕。
- **类型错误**:键不是 Hash、字段不是合法整数或增量非法时,命令返回错误,不会自动把浮点数转换为整数。
需要修改小数时使用 `HINCRBYFLOAT`,但不应把浮点运算结果直接当作精确货币账本。
可验证示例
前置条件:Redis 服务已启动,终端能够使用 `redis-cli` 连接本地默认实例。以下示例使用独立测试键,第一条命令会将测试字段重置为 `7`,请勿替换成生产业务键后直接执行。
# 固定测试初始值,保证重复运行仍可验证后续结果
redis-cli HSET demo:hincrby:verify points 7
redis-cli HINCRBY demo:hincrby:verify points 10
redis-cli HINCRBY demo:hincrby:verify points -3
redis-cli HGET demo:hincrby:verify points预期输出(测试字段首次创建时,使用 `redis-cli` 单次命令模式):
1
17
14
14第一行来自 `HSET`:创建字段返回 `1`,覆盖已存在字段则返回 `0`;后面三行始终依次为 `17`、`14`、`14`,前提是没有其他客户端并发修改该测试键。
第二、三行的 `HINCRBY` 返回整数新值,最后的 `HGET` 返回存储的字符串形式 `14`。在交互式 `redis-cli` 中,整数回复通常显示为 `(integer) 17` 等形式,字符串回复可能带引号,属于终端展示差异。
并发安全与业务约束
`HINCRBY` 保证单条命令的原子性,但不保证包含其他读写操作的整个业务流程原子。例如先执行 `HGET` 判断余额是否足够,再执行负增量扣减,两个命令之间仍可能有其他请求修改余额。
对于库存扣减、余额减少等必须满足非负约束的操作,应使用 Redis Lua 脚本等方式,在同一次原子执行中完成读取、边界判断和扣减。单纯使用 `HINCRBY key field -1` 允许结果变成负数,Redis 不会自动执行库存或余额校验。
错误处理与恢复
- **错误字段类型**:用 `HGET key field` 检查实际值;修复数据格式后再执行,不要直接覆盖未知业务数据。
- **错误键类型**:用 `TYPE key` 确认键类型。若不是 `hash`,应核对键名与数据模型,避免删除已有其他类型的数据。
- **整数越界**:检查当前值及增量,使用分段计数、业务限额等方案,不要假设 Redis 会自动饱和到边界值。
- **误加或误减**:若只是独立计数且没有连带业务影响,可用相反增量纠正,例如误加 `10` 后执行 `HINCRBY key field -10`;若涉及订单、余额或外部副作用,应先对账,再根据业务流水补偿。
适用于 Redis Open Source 2.0.0 及后续支持该命令的版本。需要记住的边界是:**单条修改原子、缺失字段从零开始、支持负增量,但不自动提供非负约束与请求幂等性**。参见 Redis 官方 HINCRBY 文档。
HDEL key field [field ...]移除哈希中的一个或多个字段,适合废弃属性与局部数据修正;删除最后一个字段后键会消失,返回值只统计实际移除的字段。
删除对象指定字段
当 Redis Hash 中的属性已经废弃、需要移除错误字段或局部修正对象数据时,使用 HDEL 删除指定字段及其值,同时保留其他字段。命令返回实际删除的字段数量,不返回被删除的内容。
基本语法
HDEL key field [field ...]key:目标哈希键,例如demo:user:42,必须是 Hash 类型或不存在。field:必须提供的字段名,只删除该字段及对应值。[field ...]:可选的更多字段,多个字段用空格分隔,属于同一次删除操作。
HDEL 不支持字段名通配符匹配,也不递归删除嵌套对象。字段名必须明确指定;如果字段不存在,Redis 会忽略它,不会因此报错。
常用示例与验证
以下示例在已启动 Redis、可执行 redis-cli 的终端中运行。使用专用测试键,先创建两个字段,再删除废弃属性,并检查剩余字段是否保留。
# 准备测试数据,忽略 HSET 的新增字段数量输出
redis-cli HSET demo:hdel:verify:42 name Alice unused_field obsolete >/dev/null
# 删除废弃字段,并验证删除结果
redis-cli HDEL demo:hdel:verify:42 unused_field
redis-cli HEXISTS demo:hdel:verify:42 unused_field
redis-cli HGET demo:hdel:verify:42 name预期输出:
1
0
Alice第一行 1 表示实际删除一个字段;第二行 0 表示该字段已经不存在;Alice 说明其他字段没有受到影响。这里的 redis-cli 使用默认本地连接;远程实例需要提供实际主机、端口和认证配置。
需要一次删除多个属性时,可以使用 HDEL demo:user:42 old_name unused_field。如果两个字段都存在,返回 2;如果只存在一个,返回 1。重复指定同一字段不会重复计算删除数量。
返回值与边界
| 情况 | 返回值或行为 |
|---|---|
| 删除一个已存在字段 | 1 |
| 删除两个不同的已存在字段 | 2 |
| 字段不存在 | 0 |
| 哈希键不存在 | 0,不会创建新键 |
| 删除哈希的最后一个字段 | 返回实际删除数量,整个键随之消失 |
| 键存在但不是 Hash 类型 | WRONGTYPE 错误,不能按哈希字段删除 |
返回 0 不代表命令执行失败,通常表示没有找到需要移除的字段。若需要检查整个键是否仍存在,使用 EXISTS key;若需要区分字段不存在与数据类型错误,可以先通过 TYPE key 检查键类型。
HDEL 从 Redis 2.0.0 起可用,从 Redis 2.4.0 起支持在一次调用中指定多个字段。时间复杂度为 O(N),其中 N 是本次指定删除的字段数量。
风险与恢复
误删后,如果已经保存原值,可以使用 HSET key field original_value 写回;其中 original_value 必须替换成备份的真实值。如果没有备份,就无法仅凭 HDEL 的返回数量恢复内容。
当被删除的是最后一个字段时,Redis 会连同哈希键一起移除,该键原有的过期时间也会丢失。重新创建字段后,如需恢复原先的过期策略,还必须根据删除前保存的 TTL 或过期时间信息重新设置。
速查:只删除部分属性用 HDEL,确认是否删除成功看返回数量,确认字段是否残留用 HEXISTS。
HSCAN key cursor [MATCH pattern] [COUNT count] [NOVALUES]使用游标分批遍历大哈希,可按字段名筛选并选择只取字段名;适合迁移和诊断,需循环至游标归零且容忍重复结果。
分批遍历哈希字段
当 Redis Hash 包含大量字段,需要逐批检查、迁移或筛选字段时,使用 HSCAN 避免一次性取回全部内容。命令返回下一次扫描使用的游标和本批字段数据,必须持续扫描至返回游标为 0。它允许重复结果,不提供固定大小分页或一致性快照。
基本语法
HSCAN key cursor [MATCH pattern] [COUNT count] [NOVALUES]| 参数 | 含义 | 使用要点 |
|---|---|---|
key |
待遍历的哈希键 | 必须是 Hash 类型,不能直接扫描整个数据库 |
cursor |
扫描游标 | 首次传 0,之后使用上次返回的游标 |
MATCH pattern |
按字段名称筛选 | 使用 glob 模式,如 user:*;不匹配字段值 |
COUNT count |
每轮扫描工作量提示 | 默认 10,不是返回数量上限 |
NOVALUES |
只返回字段名 | Redis 7.4 及以上支持,不返回字段值 |
返回结果包含两部分:第一部分是下一游标,第二部分是本次扫描到的字段与值。指定 NOVALUES 后,第二部分只包含字段名。
MATCH 和 COUNT 不保证每次都取得指定数量的匹配字段。即使当前批次为空,只要返回游标不为 0,就必须继续扫描。
常用示例与预期结果
以下命令要求 Redis 服务可访问,并且终端已安装 redis-cli。使用独立演示键,避免修改业务哈希。
# 创建三个演示字段,前两个用于匹配测试
redis-cli HSET demo:hscan:sample user:name Ada user:role editor meta:source tutorial
# 按字段前缀扫描,COUNT 只是工作量提示
redis-cli HSCAN demo:hscan:sample 0 MATCH 'user:*' COUNT 100
# 单独检查已写入的字段值
redis-cli HGET demo:hscan:sample user:name预期结果:
HSET在演示键原本不存在时返回(integer) 3,表示新增三个字段;如果字段已存在,新增数量可能更少。HSCAN返回两部分数据:下一游标,以及匹配user:*的字段和值,例如user:name对应Ada、user:role对应editor。字段顺序和每批数量不固定;meta:source不属于匹配结果。HGET返回"Ada",用于独立验证字段值。
对于这个小型演示哈希,扫描通常一次就会返回游标 0。但应用程序不得依赖这一现象;如果返回非零游标,应继续使用该游标扫描。
Redis 7.4 及以上版本还可以只获取字段名称:
# 不传输字段值,适合字段清点和名称筛选
redis-cli HSCAN demo:hscan:sample 0 MATCH 'user:*' COUNT 100 NOVALUES预期结果:返回下一游标和字段名数组,其中可能包含 user:name、user:role,但不包含 Ada、editor 等字段值。实际返回数量仍取决于扫描过程。
游标循环与终止条件
完整遍历必须遵循以下顺序:
- 将初始游标设为
0,执行第一次HSCAN。 - 读取返回结果的第一部分作为下一游标,处理第二部分的字段数据。
- 如果返回游标非零,继续使用该游标和相同的筛选选项执行下一次扫描。
- 如果返回游标为
0,本轮完整遍历结束。
游标是 Redis 返回的不透明位置标识,不是数组下标,也不是已经读取的字段数量。不能通过自增游标或使用固定偏移量模拟分页。
对于持续变化的哈希,建议为已处理字段建立去重记录。迁移时可以使用源键与字段名组成去重标识,并使目标写入操作具备幂等性,避免字段重复出现时触发重复副作用。
边界、风险与恢复
- 重复结果:完整遍历期间,同一个字段可能出现多次。统计字段数量或执行外部操作时必须考虑去重。
- 并发修改:扫描开始后新增、删除或修改的字段,不保证得到一致的观察结果。需要精确时间点数据时,应采用额外的一致性控制方案。
- 空结果:
MATCH过滤后,一轮可能返回空数组;只有游标回到0才代表结束。 - 性能开销:
COUNT 100不保证最多返回 100 个字段。部分紧凑编码的小哈希可能一次返回大量数据,应根据响应体积和延迟调整扫描频率。 - 类型错误:目标键存在但不是 Hash 时会返回
WRONGTYPE。可先使用TYPE检查键类型。 - 版本限制:
HSCAN自 Redis 2.8.0 提供,NOVALUES从 Redis 7.4 开始支持。旧版本需要接收完整字段和值,再在客户端舍弃不需要的值。
HSCAN 本身是只读操作,不修改哈希。网络中断后,可以从已保存的游标继续尝试;但若遍历期间集合发生变化,就不能据此保证恰好处理一次。对于允许重新执行的任务,更稳妥的恢复策略是从游标 0 重新遍历,并通过去重和幂等处理避免重复写入。
列表与简单队列
RPUSH key element [element ...]把一个或多个元素追加到列表右端,适合按进入顺序记录临时任务;配合 LPOP 可构成简单先进先出队列,但没有可靠确认机制。
向队列尾部追加
需要按任务进入顺序记录待处理工作时,使用 `RPUSH` 将一个或多个元素追加到 Redis 列表右端。命令返回追加后的列表长度,配合从左端取出的 `LPOP`,可以实现简单的先进先出(FIFO)队列,适合临时任务和轻量级生产消费场景。
基本语法
RPUSH key element [element ...]上述是 Redis 命令语法,可直接在 `redis-cli` 交互模式中执行;在系统终端中执行时,需要添加 `redis-cli` 前缀。
- `key`:目标列表的键名。如果键不存在,Redis 会自动创建列表。
- `element`:要追加的元素,至少提供一个。元素可以是字符串或能够表示为字符串的数值。
- `[element ...]`:可选的更多元素,按照参数从左到右的顺序依次追加。
命令成功时返回整数,表示操作完成后的列表总长度,而不是本次新增元素数量。例如原有三个元素,再追加两个,返回值为 `5`。
如果键已经存在且类型为 List,新元素追加到原有元素之后;如果键存在但不是 List 类型,则返回 `WRONGTYPE` 错误,不会自动转换数据类型。
常用示例与预期结果
前置条件:本地 Redis 服务已启动,`redis-cli` 可以正常连接,并且测试键 `demo:jobs` 尚不存在。以下示例使用 `--raw` 保持终端输出简洁,避免不同显示模式带来的额外格式。
# 将两个任务按给定顺序加入列表右端
redis-cli --raw RPUSH demo:jobs job-a job-b
# 从左到右查看任务顺序
redis-cli --raw LRANGE demo:jobs 0 -1
# 消费最早入队的任务,再查看剩余任务
redis-cli --raw LPOP demo:jobs
redis-cli --raw LRANGE demo:jobs 0 -1预期输出(按上述四条命令的执行顺序):
2
job-a
job-b
job-a
job-b第一行 `2` 表示追加后列表长度为两个元素。随后两行是 `LRANGE` 查询结果,说明 `job-a` 位于左端、`job-b` 位于右端。`LPOP` 返回并删除 `job-a`,最后一次查询仅剩 `job-b`。
如果测试键已经存在,`RPUSH` 会继续追加而不是覆盖,返回长度和查询内容也会不同。重复执行同一命令会产生重复元素,Redis 不会自动按任务 ID 去重。
命令行为与适用边界
| 操作 | 行为 | 是否改变列表 |
|---|---|---|
| `RPUSH` | 从右端追加一个或多个元素 | 是 |
| `LPUSH` | 从左端插入元素 | 是 |
| `LRANGE key 0 -1` | 按列表顺序读取全部元素 | 否 |
| `LLEN key` | 获取当前列表长度 | 否 |
| `LPOP key` | 返回并删除左端元素 | 是 |
| `RPUSHX` | 仅当列表键已存在时追加 | 是,符合条件时 |
一次 `RPUSH` 可以提交多个元素,Redis 会将该命令作为单次原子操作执行,其他客户端不会观察到该命令只追加了一部分元素的中间状态。追加 N 个元素的时间复杂度为 O(N),因此一次提交大量元素仍会占用相应的执行时间。
`RPUSH` 自 Redis 1.0.0 起可用;一次追加多个元素的语法从 Redis 2.4.0 开始支持。
风险与恢复
- **出现 `WRONGTYPE`**:先执行 `TYPE demo:jobs` 检查键类型。正常列表返回 `list`;如果返回 `string`、`hash` 等其他类型,应选择正确的列表键,不要直接删除可能包含业务数据的原键。
- **误追加任务**:在确定没有其他生产者写入、消费者取出,且能确认列表尾部元素属于本次操作时,可以通过 `RPOP` 从尾部撤销;并发环境不能依赖这种方式恢复,应根据任务标识进行业务补偿。
- **重复任务**:`RPUSH` 不检查元素是否已经存在。生产端重试可能重复入队,需要应用层使用任务 ID 和幂等处理避免重复产生业务副作用。
- **任务不能丢失**:如果需要消费确认、失败重试、待处理消息跟踪和消费者组,应考虑 Redis Streams 的 `XADD`、`XREADGROUP`、`XACK` 等命令,并配合超时任务接管与幂等处理。
速查:**右端入队用 `RPUSH`,左端出队用 `LPOP`,查看顺序用 `LRANGE`**。仅需要顺序存取的临时队列可直接使用 List;需要可靠任务处理时,不应只依赖这两个命令。
LPOP key [count]从列表左端弹出元素,适合简单任务队列或一次性消费;读取会移除数据,消费者崩溃时不能自动重投,需要可靠消费应使用 Streams。
从队列头部取出
当任务按队列尾部入队、头部消费时,使用 LPOP 原子地读取并删除列表最左侧的元素。适用于简单任务队列、一次性消费和临时数据处理。执行成功后,弹出的元素立即从原列表中移除,不会保留等待确认。
基本语法
LPOP key [count]| 参数 | 含义 | 约束 |
|---|---|---|
key |
要操作的 Redis 列表键 | 必须是 List 类型,键不存在时返回空值 |
count |
一次弹出的元素数量 | 可选,非负整数;Redis 6.2.0 起支持 |
省略 count 时,每次只弹出一个元素。指定 count 后,一次最多弹出对应数量的元素;若列表剩余元素不足,则只返回实际存在的元素。
典型先进先出队列使用 RPUSH 从右端添加任务,再通过 LPOP 从左端取出。生产端如果改用 LPUSH,消费顺序也会随之变化。
返回值与边界
- 不带
count:返回单个字符串元素;键不存在时返回 nil。 - 带
count:返回元素数组,顺序与从左端依次弹出的顺序一致;键不存在时返回 nil。 - 列表被弹空:Redis 自动删除对应的列表键,后续
LLEN返回0。 - 键类型错误:如果键存储的是 String、Hash 等其他类型,返回
WRONGTYPE错误,原数据不受影响。 - 队列为空:立即返回 nil,不会等待生产者写入新任务。
LPOP 是非阻塞命令。如果消费者需要等待任务到来,可以使用 BLPOP,但阻塞读取仍不提供任务完成确认机制。
可复现示例
在测试 Redis 实例中启动 redis-cli,逐行执行以下命令。示例先清理演示键,再写入三个任务,依次测试单元素弹出、批量弹出和空队列读取。
# 重置演示数据,仅在测试环境执行
DEL demo:jobs
RPUSH demo:jobs job-001 job-002 job-003
# 先取出一个任务,再批量取出两个任务
LPOP demo:jobs
LPOP demo:jobs 2
# 验证剩余数量,并测试空队列行为
LLEN demo:jobs
LPOP demo:jobs预期输出(演示键原本不存在时):
(integer) 0
(integer) 3
"job-001"
1) "job-002"
2) "job-003"
(integer) 0
(nil)输出中的 (integer) 3 表示 RPUSH 后列表共有三个元素,而不是成功写入三个任务之外的其他数据。
第一次 LPOP 返回 job-001,说明最早从右端加入的任务最先被取出。第二次 LPOP demo:jobs 2 一次弹出 job-002 和 job-003,返回数组而不是单个字符串。
随后 LLEN 返回 0,最后一次 LPOP 返回 nil,说明列表已经弹空。如果演示键在执行前已存在,首条 DEL 的返回值可能是 1,但清理后的其余结果保持一致。
风险与恢复
LPOP 的读取和删除是原子操作,但弹出任务不等于业务处理成功。消费者取出任务后,如果在写数据库、调用接口或更新状态之前崩溃,该任务已经不在 Redis 列表中,不能依靠再次执行 LPOP 找回。
实际使用时需要区分以下情况:
| 情况 | 处理建议 |
|---|---|
| 队列为空 | 将 nil 视为暂无任务,不要作为业务任务处理 |
| 需要等待任务 | 使用 BLPOP,根据超时时间处理空结果 |
| 任务误弹出 | 根据原始数据重新入队,并检查重复处理风险 |
| 需要失败重试 | 使用 Streams 消费者组,或采用独立处理中列表方案 |
| 需要批量消费 | Redis 6.2.0 及以上版本使用 LPOP key count |
对于不能丢失的任务,可以使用 Redis Streams 消费者组,通过 XREADGROUP 读取任务、XACK 确认处理完成,并使用 XPENDING、XAUTOCLAIM 等机制检查和接管超时未确认的消息。此类恢复需要应用主动实现,并不意味着 Redis 会自动完成失败任务的重试。
如果必须继续使用 List,可以使用 LMOVE 原子地把任务从待处理列表转移到处理中列表,业务成功后再显式移除,并为超时任务安排重新投递逻辑。该方案需要自行实现超时检查、任务标识和幂等处理。
BLPOP key [key ...] timeout在列表为空时等待元素并从左侧弹出,适合轻量后台任务处理;timeout 为秒且零表示无限等待,连接池应为阻塞消费者单独配置。
等待队列出现元素
消费者需要等待新任务、又不希望反复轮询 Redis 时,使用 BLPOP。列表非空时立即从左侧弹出一个元素;列表为空时阻塞当前连接,直到有元素入队或等待超时。成功后返回来源键名和元素值,适合简单的后台任务队列。
基本语法
BLPOP key [key ...] timeout
| 参数 | 含义 | 约束 |
|---|---|---|
key |
要消费的列表键 | 至少一个,可指定多个 |
[key ...] |
其他候选列表 | 多个非空列表按参数顺序选择 |
timeout |
最长阻塞时间,单位为秒 | 0 表示无限等待;正数表示最长等待时间 |
Redis 6.0 起支持使用小数秒表示超时;需要兼容更早版本时使用整数秒。
阻塞行为与返回值
- 列表非空:立即从第一个非空列表的左端弹出一个元素,不进入等待状态。
- 列表为空或不存在:连接进入阻塞状态,等待其他客户端通过
LPUSH或RPUSH写入元素。 - 成功取出:返回包含两个元素的数组,依次为列表键名和弹出的元素值。
- 等待超时:返回空回复(
nil),不会删除任何元素;这不是命令执行错误。 - 键类型错误:候选键保存的是字符串等非列表类型时,可能返回
WRONGTYPE错误。
多个列表同时存在数据时,优先检查命令中靠左的键。例如 BLPOP jobs:high jobs:normal 2 会优先消费已经非空的 jobs:high。这属于固定键顺序选择,不保证不同队列之间的公平调度。
可运行示例
前置条件:本机 Redis 服务已经启动,redis-cli 可以连接,使用 Bash 执行以下命令。示例通过后台生产者延迟写入,验证消费者等待和弹出行为。
# 清空专用演示键,避免已有数据影响等待结果
redis-cli DEL demo:jobs >/dev/null
# 后台模拟生产者延迟入队,消费者先发起阻塞读取
(sleep 0.2; redis-cli RPUSH demo:jobs task-001 >/dev/null) &
redis-cli --raw BLPOP demo:jobs 2
redis-cli --raw LLEN demo:jobs
wait预期输出(只列出 Redis 命令结果,交互式 Shell 可能额外显示后台作业信息):
demo:jobs
task-001
0BLPOP 在任务到达后返回键名 demo:jobs 和任务内容 task-001。LLEN 返回 0,证明任务已经从列表中移除。--raw 使数组成员按行显示,便于核对。
如果队列始终没有新元素,执行 BLPOP demo:jobs 2 会在大约两秒后返回 nil;超时之后可以再次调用,继续等待下一项任务。使用 RPUSH 入队、BLPOP 出队,可以按照先进先出的顺序消费任务。
风险与恢复
- 独占连接等待:阻塞期间,该 Redis 连接不能执行后续普通命令。应为后台消费者配置独立连接或连接池,避免占满 Web 请求使用的连接池。
- 任务可能丢失:
BLPOP弹出时就删除元素,没有任务确认机制。若消费者取出任务后崩溃,任务不会自动重新入队。需要可靠确认、重试及待处理任务管理时,优先考虑 Redis Streams 消费组。 - 连接中断:网络断开时应重新连接并再次执行
BLPOP;但无法仅凭断线判断最后一次弹出是否已经发生,业务任务需要幂等处理和补偿机制。 - 无限等待:
timeout=0不会因等待时间过长而自动返回。需要定期检测退出信号、健康状态或关闭流程时,宜使用有限超时并循环消费。 - 集群限制:Redis Cluster 中使用多个键时必须满足相同哈希槽要求,否则可能出现跨槽错误。单键消费没有这个多键限制。
速查:BLPOP demo:jobs 2 最多等待两秒;BLPOP demo:jobs 0 持续等待。成功返回键名和元素,超时返回空回复,弹出后的任务不会自动恢复。
LRANGE key start stop按零基索引读取列表的一段元素,适合分页查看短队列或最近记录;结束位置包含在内,负索引从末尾算起,不应对超长列表无限制读取。
按范围读取列表
需要查看 Redis List 中指定位置的任务、消息或最近记录,而不移除元素时,使用 LRANGE。它按列表当前顺序返回指定区间内的元素,适合小批量读取、队列检查和开发调试。
基本语法
LRANGE key start stop| 参数 | 含义 | 取值与约束 |
|---|---|---|
key |
目标列表键 | 必须是 List 类型,键不存在时返回空数组 |
start |
起始索引 | 从 0 开始,支持负整数 |
stop |
结束索引 | 包含该位置,支持负整数 |
索引从列表左端开始计算,0 表示第一个元素,1 表示第二个元素。负索引从右端计算,-1 表示最后一个元素,-2 表示倒数第二个元素。
stop 是包含式边界,因此读取前 20 个元素应使用 LRANGE demo:jobs 0 19,而不是 0 20。如果列表不足 20 个元素,Redis 只返回实际存在的部分。
常见范围写法
| 命令 | 读取范围 |
|---|---|
LRANGE demo:jobs 0 19 |
前 20 个元素 |
LRANGE demo:jobs 20 39 |
第 21~40 个元素 |
LRANGE demo:jobs -5 -1 |
最后 5 个元素 |
LRANGE demo:jobs 0 -1 |
整个列表 |
LRANGE demo:jobs 2 2 |
索引 2 对应的单个元素 |
需要特别注意以下边界:
start超出列表右端时返回空数组。stop超出列表右端时,自动截断到最后一个元素。start大于stop时返回空数组。- 键不存在时返回空数组,不会创建新键。
- 键存在但类型不是 List 时,返回
WRONGTYPE错误。
这些规则允许调用方直接指定固定窗口,而不必先读取列表长度。不过,空结果只能说明当前区间没有元素,不能直接证明整个列表为空。
可验证示例
前置条件:Redis 服务已启动,当前终端安装了 redis-cli,并且能够连接到目标实例。以下命令在终端中执行,使用独立测试键避免影响业务列表。
# 检查连接并重建测试列表,确保结果可复现
redis-cli PING
redis-cli DEL demo:lrange:verify
redis-cli RPUSH demo:lrange:verify job-a job-b job-c job-d job-e
# 从左端读取前三个元素
redis-cli --raw LRANGE demo:lrange:verify 0 2
# 从右端读取最后两个元素
redis-cli --raw LRANGE demo:lrange:verify -2 -1预期结果:PING 返回 PONG;DEL 返回整数 0 或 1,取决于测试键此前是否存在;RPUSH 返回整数 5。两次 LRANGE 的输出依次为:
job-a
job-b
job-c
job-d
job-e前三行来自 0 2,后两行来自 -2 -1。--raw 让命令行直接打印元素内容,便于核对;在交互式 redis-cli 中执行时,通常会看到带序号的数组格式。
LRANGE 只读取数据,不修改列表。再次执行相同范围查询,只要列表没有发生变化,就会获得相同结果。
分页读取与性能边界
当列表包含数百或数千条记录时,可以按照固定窗口分批读取。例如每页 20 条,起始索引由页码计算:
start = (page - 1) * 20,stop = start + 19。
第一页读取 0 19,第二页读取 20 39。需要了解当前列表长度时,使用 LLEN demo:jobs。
但这种分页不提供快照一致性。如果其他客户端在分页期间执行 LPUSH、LPOP 或 LTRIM,元素索引会改变,后续页面可能出现重复或遗漏。对持续变化的任务列表,不应把索引分页当成可靠的消费进度。
Redis 官方给出的 LRANGE 时间复杂度为 O(S+N),其中 S 与定位起始元素的距离有关,N 是实际返回的元素数量。大范围返回不仅增加服务端处理工作,还会增加网络传输和客户端内存开销。
错误排查与选择建议
查询返回空结果时,先使用 EXISTS demo:jobs 和 LLEN demo:jobs 检查键是否存在、列表是否有元素,再核对 start、stop 是否超出范围。若遇到 WRONGTYPE,可用 TYPE demo:jobs 检查键类型;不要为了读取列表而直接覆盖其他类型的数据。
LRANGE 适合观察队列内容,但不会消费任务。需要实际取出元素时,应根据处理语义选择 LPOP、RPOP 或阻塞弹出命令,而不是把读取成功等同于任务已完成。
速查:读取前 N 个元素用 0 N-1;读取末尾 N 个元素用 -N -1;只读检查用 LRANGE,不要把它当作出队操作。
LLEN key快速获取列表中的元素个数,适合观察简单任务队列的积压变化;该值只代表当前时刻,不能直接推导处理速率或任务是否已完成。
查看列表元素数量
排查 Redis List 任务队列是否积压、确认列表是否为空,或检查入队和出队后的元素数量时,使用 `LLEN`。命令返回指定列表在执行时的元素个数,不读取元素内容,也不会改变队列。连续观察该值可以发现积压趋势,但不能单独计算任务处理速率或判断任务是否全部完成。
基本语法
LLEN key- `key`:需要统计的 Redis 列表键名,必填且只能指定一个键。
- 返回值:非负整数,表示列表当前包含的元素数量。
- 键不存在:返回 `0`,按空列表处理,不会创建新键。
- 键类型错误:如果键存在但不是 List,返回 `WRONGTYPE` 错误。
`LLEN` 是只读命令,时间复杂度为 `O(1)`,不需要遍历整个列表。该命令自 Redis Open Source 1.0.0 起可用,没有额外选项,也不支持通过通配符批量统计多个键。
常用查询与预期结果
前置条件:已经安装 `redis-cli`,能够连接目标 Redis 实例,并具有读取目标键的权限。以下使用默认本地连接;远程实例应通过受控连接方式指定实际主机、端口和认证信息。
# 读取任务队列当前长度,不修改队列
redis-cli LLEN demo:jobs
# 核实目标键的数据类型
redis-cli TYPE demo:jobs预期输出(假设 `demo:jobs` 已存在且恰好包含 3 个元素):
(integer) 3
list第一行表示列表长度为 `3`,第二行确认键类型是 `list`。实际长度取决于查询时刻的数据;生产者和消费者同时运行时,连续两次查询可能得到不同结果。
如果键不存在,`LLEN` 返回 `(integer) 0`,`TYPE` 返回 `none`。因此,仅凭长度为零,不能区分一个不存在的键和一个当前为空的列表。需要确认键是否存在时,应结合 `TYPE` 或 `EXISTS` 判断。
判断队列积压变化
对简单的 List 任务队列,可以按固定时间间隔记录长度,观察待处理元素是否持续增长。
例如,某队列在 10:00 查询到 `120` 个元素,10:01 查询到 `190` 个元素,说明这一分钟内列表净增加了 `70` 个元素。它不代表只有 70 个任务入队,也不意味着消费者没有工作;期间可能同时发生大量入队和出队。
判断时应区分以下情况:
- **长度持续增加**:在队列仅由任务入队和消费出队操作维护的前提下,表示观测区间内入队总量大于出队总量,需要结合生产量和消费量继续排查。
- **长度持续减少**:表示列表中的待处理元素正在净减少,但不能证明每个出队任务已经成功处理。
- **长度保持为零**:表示查询时列表为空;任务可能正在消费者内部执行,或已转移到其他处理状态。
例如,消费者先使用 `LPOP` 或 `BLPOP` 移除任务,再执行实际业务逻辑时,`LLEN` 不包含已经出队但尚未完成的任务。需要统计执行中、成功和失败任务时,应结合业务状态记录或相应的队列确认机制。
错误处理与使用边界
遇到 `(error) WRONGTYPE Operation against a key holding the wrong kind of value`,先通过 `TYPE demo:jobs` 检查键类型,再确认程序是否使用了错误的键名或复用了其他数据结构的键。不要为了让 `LLEN` 成功而直接删除生产环境中的非列表键,应先定位写入方并修复键名或数据类型冲突。
如果查询结果与应用日志不一致,应确认连接的是同一 Redis 实例、数据库和目标键,并检查是否存在并发写入、键过期或队列迁移。`LLEN` 只提供单次查询的长度快照,不能把多次独立查询当成原子统计。
LTRIM key start stop仅保留列表指定索引区间,适合维持最近若干条记录的固定窗口;区间外元素会永久移除,执行前要确认索引与保留策略。
截断列表保留窗口
当 Redis 列表只需要保存最近若干条记录时,使用 LTRIM 保留指定索引区间,并删除区间外的元素。常用于限制日志、操作历史和消息缓存的长度。命令直接修改原列表,已删除的元素不能通过撤销命令恢复。
基本语法
redis-cli LTRIM key start stop| 参数 | 含义 | 约束 |
|---|---|---|
key |
要截断的列表键 | 必须是 List 类型或不存在 |
start |
保留区间的起始索引 | 从 0 开始,支持负数 |
stop |
保留区间的结束索引 | 包含该位置,支持负数 |
索引 0 表示列表头部,-1 表示列表尾部,-2 表示倒数第二个元素。start 和 stop 都包含在保留范围内,因此 0 99 最多保留 100 个元素,而不是 99 个。
命令成功返回 OK,不返回被删除的元素。列表键不存在时也返回 OK;如果保留范围为空,Redis 会删除整个列表键。
选择正确的保留窗口
保留最近 N 条记录时,必须先确认新元素从哪一端加入。
| 写入方式 | 新元素位置 | 保留最近 100 条 |
|---|---|---|
LPUSH |
列表头部 | LTRIM key 0 99 |
RPUSH |
列表尾部 | LTRIM key -100 -1 |
其他常见索引组合:
0 -1:保留整个列表,不删除元素。0 9:最多保留头部 10 个元素。-10 -1:最多保留尾部 10 个元素。10 5:起始索引大于结束索引,删除全部元素。
当列表不足 N 条时,-N -1 会保留现有全部元素,不会补充空元素。结束索引超过列表尾部时,Redis 只保留实际存在的区间。
常用示例与预期结果
以下示例在已安装 redis-cli、能够连接本地 Redis 的测试环境中执行。使用独立测试键模拟向列表尾部追加五条记录,再将窗口限制为最近三条。
KEY="demo:ltrim:window:example"
# 仅清空专用测试键,禁止替换成正在使用的业务键
redis-cli --raw DEL "$KEY" >/dev/null
redis-cli --raw RPUSH "$KEY" a b c d e
redis-cli --raw LTRIM "$KEY" -3 -1
redis-cli --raw LRANGE "$KEY" 0 -1
redis-cli --raw LLEN "$KEY"预期输出:
5
OK
c
d
e
3RPUSH 返回追加后的列表长度 5,LTRIM 返回 OK,LRANGE 显示最终剩余 c、d、e,LLEN 确认列表长度为 3。
实际业务中,若持续使用 RPUSH 写入,可以在每次追加后执行 LTRIM key -100 -1,将列表长度限制在最多 100 条。若多个客户端同时写入且要求追加与截断不可被其他命令插入,应使用 MULTI / EXEC 将这两个写操作组成事务。
风险与恢复
- 窗口方向错误:使用
RPUSH却保留0 99,可能留下最旧记录而删除最新记录。先确认写入方式,再确定保留头部还是尾部。 - 列表被清空:当
start超过列表末尾,或计算后的保留区间无效时,列表键会被删除。执行前可使用LLEN检查长度,并用LRANGE检查边界元素。 - 数据类型不匹配:对 String、Hash 等非 List 类型执行会收到
WRONGTYPE错误。先通过TYPE确认键类型,不要为了执行命令而直接删除原键。 - 一次删除过多元素:时间复杂度为 O(M),其中 M 是删除的元素数量。单次截断超长列表可能增加 Redis 主线程的处理延迟;持续维护小窗口通常比积累大量数据后集中清理更合适。
如果已经误删元素,应优先检查业务原始数据源或事先保存的备份。Redis 不提供 LTRIM 撤销命令,持久化文件也不能保证能够直接恢复到误操作前的状态。
去重与集合运算
SADD key member [member ...]将成员加入无序集合并自动去重,适合标签、参与者和去重标识;返回的是新增加的数量,不能依赖任何遍历顺序。
添加去重成员
需要将标签、参与者或去重标识写入 Redis Set,并避免重复存储时使用 SADD。同一成员无论添加多少次,集合中都只保留一份;命令返回本次新增成员数,而不是集合总大小。
基本语法
SADD key member [member ...]key:目标集合键。键不存在时,Redis 自动创建 Set。member:至少提供一个成员,可以一次传入多个成员。同一命令中重复出现的成员也会自动去重。- 返回值:整数,表示本次实际新增的成员数量。所有成员均已存在时返回
0。
SADD 不会覆盖已有 Set 中的其他成员。如果目标键已存在但类型不是 Set,命令会返回 WRONGTYPE 错误,而不会自动转换数据类型。
常用示例
确保 Redis 服务已启动,并且测试键 demo:tags 尚不存在。以下命令在终端逐行执行,使用 --raw 输出便于核对的整数结果。如果第一条命令返回非 0,请更换未占用的测试键,避免修改已有数据。
# 确认测试键不存在,再执行添加操作
redis-cli --raw EXISTS demo:tags
redis-cli --raw SADD demo:tags redis cache backend
redis-cli --raw SADD demo:tags redis search
# 验证最终成员数量及成员是否存在
redis-cli --raw SCARD demo:tags
redis-cli --raw SISMEMBER demo:tags search预期输出(对应五条命令,按执行顺序):
0
3
1
4
1第一次添加 redis、cache、backend,新增数量为 3。第二次添加 redis 和 search,由于 redis 已存在,只有 search 被加入,返回 1。
SCARD 返回集合最终成员总数 4;SISMEMBER 返回 1 表示指定成员存在,返回 0 表示不存在。这样可以区分本次新增数量与集合实际大小。
检查集合内容
需要检查完整成员列表时,可以使用 SMEMBERS。它返回所有成员,但输出顺序不固定,不能依赖成员位置实现排序、分页或按顺序处理。
redis-cli --raw SMEMBERS demo:tags预期结果包含以下四个成员,实际显示顺序可能不同:
redis
cache
backend
search如果只需要判断一个成员是否已经加入,优先使用 SISMEMBER,避免读取整个集合。需要获取成员数量时使用 SCARD,不要通过遍历结果自行计数。
风险与恢复
- 类型不匹配:执行前可使用
TYPE demo:tags检查键类型。已有集合应返回set;返回none表示键不存在;其他类型不能直接执行SADD。 - 重复添加:返回
0不表示命令失败,而是本次没有新成员。不要将返回值直接当成请求是否成功的布尔标志。 - 成员无序:Set 不提供稳定的遍历顺序。如果业务需要按时间或分数排序,应评估是否改用 Sorted Set。
- 误添加恢复:已确认某个成员是误加入的,可以使用
SREM删除该成员。删除成功返回1,成员不存在时返回0;删除之前应确认它没有被其他业务依赖。
例如撤销示例中新加入的 search:
redis-cli --raw SREM demo:tags search
redis-cli --raw SCARD demo:tags
redis-cli --raw SISMEMBER demo:tags search预期输出:
1
3
0这里先删除一个成员,再确认集合大小恢复为 3、被删除成员不再存在。不要使用 DEL 清空整个业务键来恢复单个成员的误添加,否则其他合法成员也会丢失。
速查:SADD 添加并去重,SCARD 查看数量,SISMEMBER 检查是否存在,SREM 删除指定成员。
SISMEMBER key member判断某个值是否属于指定集合,适合权限候选、标签匹配和去重查询;返回的是当前集合的成员关系,不代表带过期限制的历史记录。
检查集合成员
需要判断标签、权限候选或去重标记是否属于某个 Redis Set 时,使用 SISMEMBER。成员存在返回 1,不存在返回 0。该命令只检查查询瞬间的成员关系,不记录成员是否曾经存在。
基本语法
redis-cli SISMEMBER key memberkey:目标集合的键名,必须是 Set 类型;键不存在时返回0。member:待检查的成员值,按照实际字节内容精确匹配,区分大小写。- 返回值:
1表示成员存在,0表示成员不存在。
SISMEMBER 的平均时间复杂度为 O(1),适合高频单成员检查。它不会修改集合,也不会刷新键的过期时间。
返回值与判断
| 返回结果 | 含义 | 处理方式 |
|---|---|---|
1 |
成员存在于当前集合 | 可以执行依赖成员关系的后续操作 |
0 |
成员不存在,或整个键不存在 | 按未命中处理;需要时进一步确认键状态 |
WRONGTYPE |
键存在,但数据类型不是 Set | 使用 TYPE 检查实际类型 |
例如,demo:tags 存储文章标签,SISMEMBER demo:tags redis 返回 1,表示 redis 当前属于该集合。若返回 0,只能说明当前未命中,不能断言它过去从未被添加。
可验证示例
前置条件:Redis 服务正在运行,redis-cli 能连接到目标实例,当前账号具有 SADD、SISMEMBER、TYPE 和 DEL 权限。以下示例在本机默认连接上创建临时测试集合,并在验证后清理。
# 生成测试专用键,降低与已有数据冲突的风险
key="demo:tags:check:$(date +%s):$$"
# --raw 使用适合脚本读取的原始输出格式
redis-cli --raw SADD "$key" redis cache
redis-cli --raw SISMEMBER "$key" redis
redis-cli --raw SISMEMBER "$key" mysql
redis-cli --raw TYPE "$key"
redis-cli --raw DEL "$key"预期输出(测试键原本不存在且所有命令成功时):
2
1
0
set
1结果依次表示:SADD 新增两个成员,redis 命中,mysql 未命中,键类型为 set,最后成功删除一个测试键。
如果要检查已有的 demo:tags 集合,可以直接使用条目提供的命令:
redis-cli SISMEMBER demo:tags redis预期结果:集合包含 redis 时返回整数 1,否则返回整数 0。redis-cli 在交互模式下通常显示为 (integer) 1 或 (integer) 0;非交互模式的默认输出格式可能不同,脚本可使用 --raw 获取便于解析的数值。
常见错误与边界
- 混淆成员不存在与键不存在:两种情况都返回
0。可以使用EXISTS key辅助判断,但独立命令之间可能发生并发修改,因此不能保证两次检查得到同一时刻的状态。 - 对错误数据类型执行检查:如果键实际上是 String、Hash、List 或 ZSet,Redis 返回
WRONGTYPE错误。先使用TYPE key确认,不要为了消除错误直接删除生产数据。 - 把成员检查当作历史记录查询:如果整个 Set 因 TTL 到期而被删除,
SISMEMBER返回0,不会告知以前是否存在该成员。 - 误认为支持成员级过期:常规 Set 的键级 TTL 作用于整个集合,
SISMEMBER不提供每个成员的独立有效期判断。需要逐成员过期时,应另外维护有效期信息并在查询时校验。 - 将检查结果直接等同于最终授权:成员检查与后续操作是两次独立执行,期间集合可能变化。需要原子化检查并执行操作时,应按业务需求使用 Redis Lua 脚本或其他适当的原子操作方案。
故障排查与恢复
如果命令返回错误,先确认连接与键类型,再决定是否需要修正数据。
redis-cli PING
redis-cli TYPE demo:tags
redis-cli TTL demo:tags预期结果及读取方式:
PING正常返回PONG,表示当前连接可以执行该命令;认证、网络或权限问题可能导致失败。TYPE返回set表示类型正确,返回none表示键不存在;返回其他类型时应检查写入逻辑。TTL返回正整数表示剩余秒数,-1表示键存在且未设置过期时间,-2表示键不存在。
如果键因过期或误删而消失,SISMEMBER 无法恢复成员。应从可信业务数据源重新构建集合;存在可用备份时,也可以依据备份与恢复流程处理,避免直接覆盖仍在使用的数据。
速查:判断当前 Set 的单个成员是否存在,用 SISMEMBER;区分键是否存在,用 EXISTS;检查类型,用 TYPE;排查键级过期,用 TTL。
SMEMBERS key返回集合的全部成员,适合规模较小的标签或白名单;结果无序且数据量随集合大小增长,大集合扫描应使用 SSCAN。
读取全部集合成员
需要一次读取某个 Redis Set 中的全部标签、白名单 ID 或去重值时,使用 `SMEMBERS`。命令返回集合内的所有成员,不修改原集合,也不会返回重复成员。适合小规模集合的内容核对、数据展示和本地遍历。
基本语法
redis-cli SMEMBERS demo:tags在已经进入 `redis-cli` 的交互环境中,直接执行 `SMEMBERS demo:tags` 即可。其命令签名为 `SMEMBERS key`,其中 `key` 是目标集合的键名。
- `key`:必填,必须指向 Set 类型的键。
- 返回值:包含全部集合成员的数组,成员顺序不固定。
- 时间复杂度:`O(N)`,其中 `N` 是集合成员数量。
- 不支持分页、偏移量或指定返回条数,每次都会尝试返回整个集合。
常用示例与预期结果
以下示例需要 Redis 服务已经启动,且当前数据库中的 `demo:tags` 尚不存在。先创建测试集合,再读取成员,并通过 `SCARD` 核对数量。
# 向测试集合添加三个不同的标签
redis-cli SADD demo:tags backend cache redis
# 一次读取全部成员
redis-cli SMEMBERS demo:tags
# 核对集合成员数量
redis-cli SCARD demo:tags预期结果:在全新测试集合中,`SADD` 返回 `3`,`SMEMBERS` 返回三个成员,`SCARD` 返回 `3`。以下是使用普通终端执行时的一种可能输出:
3
backend
cache
redis
3`backend`、`cache`、`redis` 的实际输出顺序可能不同。若测试键原先已有成员,`SADD` 的新增数量和最终集合内容也可能不同,应以实际返回值为准。
返回值与异常
| 情况 | 结果 | 处理方式 |
|---|---|---|
| 集合存在且有成员 | 返回全部成员 | 不依赖返回顺序 |
| 键不存在 | 返回空数组 | 判断为空集合,不当作命令错误 |
| 键存在但不是 Set | 返回 `WRONGTYPE` 错误 | 用 `TYPE key` 检查类型 |
| 集合成员很多 | 一次返回大量数据 | 改用 `SSCAN` 分批迭代 |
如果只需统计成员数量,使用 `SCARD`;如果只想判断某个值是否属于集合,使用 `SISMEMBER`,不必将全部成员传输到客户端。
大集合风险与替代
`SMEMBERS` 是只读命令,不会删除数据,但读取成本与集合大小成正比。集合包含大量成员时,一次性返回全部结果可能增加 Redis 的命令处理耗时、网络传输量和客户端内存占用,因此不宜在高频接口中反复调用。
对于大集合,使用 `SSCAN key cursor [MATCH pattern] [COUNT count]` 增量遍历。首次游标设为 `0`,后续使用响应返回的新游标继续扫描,直到返回游标为 `0` 才结束。
- `COUNT` 是单次扫描工作量的提示值,不保证每批恰好返回指定数量。
- `MATCH` 用于按模式过滤,但不能保证每次调用都有匹配结果。
- 迭代过程中可能出现重复成员,消费端应根据业务需要去重。
- 集合在扫描期间发生增删时,不保证得到某一时刻的完整一致快照。
速查:小集合读取全部成员用 `SMEMBERS`;只查数量用 `SCARD`;只查成员是否存在用 `SISMEMBER`;大集合遍历用 `SSCAN`。
SREM key member [member ...]从集合中删除一个或多个成员,适合取消订阅和移除临时标识;不存在成员不会报错,返回值只记录实际删除的数量。
当需要从 Redis Set 中取消某个标签、移除用户标识或删除业务订阅关系时,使用 SREM。它只移除指定成员,不影响集合中的其他成员;通过整数返回值可以确认实际删除了多少个成员。
基本语法
SREM key member [member ...]key:目标集合的键名,必须是 Set 类型或尚不存在的键。member:要删除的成员,至少提供一个,可以一次指定多个。[member ...]:可选的其他成员,适合批量移除,不需要逐个发起请求。
例如,SREM demo:tags cache 会尝试从 demo:tags 集合中移除成员 cache,不会删除整个集合。
返回值与执行边界
SREM 返回整数,表示实际成功移除的成员数量,而不是传入参数的数量。
| 情况 | 返回结果 | 说明 |
|---|---|---|
| 指定成员存在 | 1 |
成功移除一个成员 |
| 指定成员不存在 | 0 |
不报错,集合内容不变 |
| 一次指定多个成员 | 0 至实际存在的成员数 |
只统计成功移除的不同成员 |
| 集合键不存在 | 0 |
不会创建新集合 |
| 键存在但不是 Set | WRONGTYPE 错误 |
不执行成员删除 |
如果删除的是集合中的最后一个成员,Redis 会自动移除这个空集合对应的键。命令的时间复杂度为 ,其中 是请求删除的成员数量,而不是集合的总成员数。
可验证示例
前置条件:本机 Redis 服务正在运行,已安装 redis-cli,当前连接账号具有集合读写权限。以下示例使用带随机后缀的测试键,避免修改现有业务集合;在 Bash 中一次执行完整代码。
# 使用临时键,降低与现有业务键冲突的概率
key="demo:srem:verify:$$:$RANDOM"
redis-cli --raw SADD "$key" cache api
# 不存在的成员不会计入删除数量
redis-cli --raw SREM "$key" cache missing
redis-cli --raw SISMEMBER "$key" cache
redis-cli --raw SMEMBERS "$key"
redis-cli --raw DEL "$key"预期输出(按命令执行顺序):
2
1
0
api
1结果解释:
SADD返回2,表示新加入cache和api两个成员。SREM返回1,因为cache存在并被移除,missing原本不存在。SISMEMBER返回0,确认cache已不在集合中。SMEMBERS只输出api,确认其他成员保留。- 最后的
DEL返回1,表示成功清理本次创建的测试键。
--raw 用于让 redis-cli 输出便于核对的原始值。示例采用默认本地连接;如果 Redis 部署在其他主机或端口,需要按实际环境配置连接参数。
风险与恢复
- 删除不可自动撤销:
SREM没有回滚机制。误删已知成员后,可以使用SADD demo:tags cache将其重新加入;如果该成员当前不存在,成功补回时返回1。 - 最后一个成员被删除:集合键会消失。如果原键设置过过期时间,重新通过
SADD创建集合不会自动恢复原来的 TTL,需要根据业务记录重新设置。 - 成员必须精确匹配:Redis 区分大小写,
cache与Cache是不同成员;执行前可以用SISMEMBER核实成员是否存在。 - 类型错误:遇到
WRONGTYPE时,先使用TYPE demo:tags检查键类型,不要为了让命令成功而直接删除或覆盖业务键。 - 订阅语义有限:
SREM只能删除存储在 Set 中的订阅关系记录,不会取消 Redis Pub/Sub 的实际订阅;后者应使用相应的UNSUBSCRIBE或PUNSUBSCRIBE命令。
SINTER key [key ...]查找多个集合共有的成员,适合共同标签和简单集合筛选;参与集合较大时开销可能明显,集群场景下多个键还须位于同一槽。
计算集合交集
需要找出两个或多个 Redis Set 共同包含的成员时,使用 SINTER。典型场景包括共同标签筛选、用户兴趣交集和权限集合匹配。命令直接返回交集成员,不修改原集合,也不会将结果保存到新键。
基本语法
SINTER key [key ...]key:必填,参与计算的第一个集合键。[key ...]:可选,其他参与交集计算的集合键,可以指定多个。
所有键都必须是 Set 类型。只传一个键时,返回该集合的全部成员;传多个键时,只有同时存在于所有集合中的成员才会出现在结果中。
命令返回交集成员集合,成员不重复,不保证返回顺序。如果需要稳定排序,应在客户端进行排序。
常用示例
假设需要找出两个标签集合共同包含的标签。以下示例使用已启动的 Redis 实例和 redis-cli,请在独立测试环境中执行,并确保示例键此前不存在。
# 准备两组有部分重叠的标签
redis-cli SADD demo:tags:a backend cache redis
redis-cli SADD demo:tags:b backend cache search
# 计算交集,并在客户端排序以保证展示顺序
redis-cli --raw SINTER demo:tags:a demo:tags:b | sort预期输出(Linux/macOS Shell,且示例键初始不存在):
(integer) 3
(integer) 3
backend
cache两个 SADD 分别新增 3 个成员。交集只有 backend 和 cache,因为 redis 仅属于第一个集合,search 仅属于第二个集合。
最后一条命令使用 --raw 输出原始成员字符串,再通过系统的 sort 命令排序。去掉 | sort 后,Redis 返回的成员顺序可能不同,但交集内容不变。
返回结果与边界
| 输入情况 | 结果或行为 |
|---|---|
| 所有集合有共同成员 | 返回共同成员,每个成员只出现一次 |
| 集合没有共同成员 | 返回空结果 |
| 任意一个键不存在 | 不存在的键按空集合处理,交集为空 |
| 只传一个集合键 | 返回该集合全部成员 |
| 任意键存在但不是 Set 类型 | 返回 WRONGTYPE 错误 |
| 多个集合包含重复添加的成员 | Set 自动去重,不影响交集结果 |
可以先用 TYPE demo:tags:a 检查键的数据类型,正常应返回 set。使用 SCARD demo:tags:a 可以读取集合成员数量,帮助判断参与计算的数据规模。
SINTER 只读取集合,不会创建结果键。如果需要将交集保存起来,应使用 SINTERSTORE destination key [key ...],但该命令会写入目标键,不能与只读的 SINTER 混淆。
集群与性能限制
Redis 官方给出的最坏时间复杂度为 ,其中 是参与计算的最小集合的成员数, 是集合数量。集合成员越多、参与键越多,计算耗时可能越明显。
在 Redis Cluster 中,参与 SINTER 的多个键必须位于同一哈希槽,否则通常会返回 CROSSSLOT 错误。
可以使用相同的哈希标签组织相关集合,例如:
demo:{tags}:ademo:{tags}:b
两个键的 {tags} 部分一致,因此会映射到同一哈希槽。可以分别执行 CLUSTER KEYSLOT 命令确认槽号一致;该检查适用于 Redis Cluster,普通独立实例不需要进行槽位检查。
常见错误与处理
- 返回空结果:先确认各键存在且确实具有共同成员;使用
SCARD检查成员数量,必要时使用SISMEMBER验证指定成员是否存在。 - 出现
WRONGTYPE:使用TYPE定位非 Set 类型的键,再修正键名或数据写入逻辑,不要直接删除生产键。 - 出现
CROSSSLOT:检查各键的哈希槽,使用相同哈希标签重新设计相关键。已有数据需要迁移时,应规划迁移过程,不要仅修改查询参数。 - 查询耗时过长:减少参与集合数量,评估集合规模和调用频率,必要时改为预计算交集或调整数据模型。
速查:SINTER 用于只读求交集,结果无序且不保存;Redis Cluster 多键操作需满足同槽约束。