Redis 与缓存 / 知识点
Redis 开发常用命令速查
连接与键定位
redis-cli [OPTIONS] [cmd [arg [arg ...]]]通过 redis-cli 连接指定实例或执行单条命令,适合本地联调与远程排查;生产环境应启用加密连接,并避免在命令行参数中明文传递密码。
命令行连接实例
需要确认 Redis 实例是否可连接、认证是否成功,或临时执行一条 Redis 命令时,使用 redis-cli。它支持本地与远程连接、交互模式、单命令执行、ACL 认证及 TLS 加密连接。最常用的检查方式是发送 PING,正常响应为 PONG。
基本语法
redis-cli [OPTIONS] [cmd [arg [arg ...]]]其中 OPTIONS 指定连接方式,cmd 是要执行的 Redis 命令,后续 arg 是命令参数。省略 cmd 会进入交互模式;提供 cmd 则执行该命令并输出结果。
默认情况下,redis-cli 使用普通 TCP 连接 127.0.0.1:6379,不主动启用 TLS。实际端口及认证要求由 Redis 实例配置决定。
常用连接选项
| 选项 | 作用 | 使用要点 |
|---|---|---|
-h <HOST> |
指定主机名或 IP | 默认 127.0.0.1 |
-p <PORT> |
指定连接端口 | 默认 6379 |
--user <USER> |
指定 ACL 用户名 | 与密码认证配合使用 |
--askpass |
交互式输入密码 | 输入时隐藏密码,不适合无人值守脚本 |
-a <PASSWORD> |
通过参数传递密码 | 可能暴露在进程参数或命令历史中 |
--tls |
启用 TLS 加密连接 | 服务端必须提供 TLS 端口 |
--cacert <PATH> |
指定受信任的 CA 证书文件 | 用于验证服务端证书 |
-n <DB> |
选择逻辑数据库 | 默认数据库 0;Redis Cluster 仅支持数据库 0 |
-c |
启用集群重定向处理 | 跟随 MOVED、ASK 重定向 |
--askpass 会优先使用交互输入的密码,忽略 -a 和 REDISCLI_AUTH。如果实例未启用密码认证,不需要提供认证选项。
本地连接与验证
前置条件:本机已安装 redis-cli,且目标 Redis 实例正在监听 127.0.0.1:6379,允许当前客户端执行 PING。
# 只检查连接响应,不读取或修改业务键
redis-cli -h 127.0.0.1 -p 6379 PING预期输出:
PONG收到 PONG 表示客户端能够连接实例,并且当前连接可以执行 PING。它不能证明业务读写权限正常,也不能说明所有集群节点均可访问。
如果需要连续执行多条命令,可以不指定 PING,直接运行 redis-cli -h 127.0.0.1 -p 6379 进入交互模式。在提示符下输入 PING 检查响应,输入 QUIT 退出。
远程认证与 TLS
连接生产环境时,先向实例管理员确认主机、TLS 端口、CA 证书及 ACL 用户。不要默认远程实例也使用端口 6379,更不要为了排查连接问题直接关闭证书验证。
以下为片段示例,必须先把 <HOST>、<PORT>、<PATH> 和 <USER> 分别替换为真实主机、端口、CA 文件路径及 ACL 用户名。要求目标实例已启用 TLS,且该用户允许执行 PING。
# 使用 TLS 验证服务器证书,并交互式输入 ACL 密码
redis-cli -h <HOST> -p <PORT> --tls --cacert <PATH> --user <USER> --askpass PING预期结果:终端先要求输入密码;证书验证和认证均成功后输出:
PONG若服务器要求双向 TLS,还需要通过 --cert 和 --key 提供客户端证书及对应私钥。不要将 --insecure 作为生产环境的连接解决方案,它会跳过证书验证。
无人值守脚本可以通过受控的环境变量 REDISCLI_AUTH 提供密码,但仍应限制变量的读取范围,避免在日志、构建输出或调试信息中泄露凭据。环境变量并不等于专用密钥管理系统。
常见失败与恢复
| 现象 | 可能原因 | 排查与恢复 |
|---|---|---|
Connection refused |
端口未监听、地址错误或连接被拒绝 | 核对 -h、-p 和实例监听配置 |
| 连接超时 | 路由、防火墙、安全组或网络策略阻断 | 检查网络可达性和连接超时设置 |
NOAUTH |
实例要求认证,但当前连接尚未认证 | 使用正确的认证方式重新连接 |
WRONGPASS |
用户名、密码错误或 ACL 用户被禁用 | 检查凭据及 ACL 用户状态 |
| TLS 握手或证书验证失败 | TLS 模式、CA、主机名或证书不匹配 | 确认 TLS 端口、证书信任链和主机名 |
MOVED |
命令涉及的键属于其他集群节点 | 对 Redis Cluster 使用 -c 并确保目标节点可达 |
错误文本会随 Redis 版本、客户端版本、操作系统及代理实现而有所不同,应结合实际终端输出判断。
安全与使用边界
- 优先使用
--askpass交互认证,避免在共享终端直接传递-a密码,或在含密码的redis://URI 中暴露凭据。 - 生产环境优先使用 TLS,并验证服务端证书;普通 TCP 连接不提供传输加密。
- 连接成功不代表拥有所有命令或键的权限。ACL 可能分别限制命令、键模式与发布订阅频道。
- 不要在尚未确认实例身份和数据库范围时执行
FLUSHDB、FLUSHALL等破坏性命令;误删后的恢复依赖事先存在的备份或其他数据恢复机制。
速查:本地探活使用 redis-cli -h 127.0.0.1 -p 6379 PING;远程生产连接应根据实例配置补充 TLS、证书验证和认证参数。
PING [message]确认当前连接能向 Redis 发出命令并取得响应,正常返回 PONG;适合健康检查,但不能单独证明业务键可写或客户端权限配置正确。
检查 Redis 连接是否可用
当怀疑 Redis 连接断开、请求超时或服务无法响应时,使用 PING 验证当前连接能否完成一次命令往返。无参数时正常返回 PONG,表示服务器已响应请求,但不代表业务读写一定正常。
基本语法
PING [message] 是 Redis 命令,可在已连接的 redis-cli 交互会话中直接执行,也可以由客户端发送。
- 不传
message:正常返回PONG。 - 传入
message:返回该消息本身,而不是PONG;可用于确认请求与响应的对应关系。 message:可选的单个字符串参数,不是键名,也不会写入 Redis 数据库。
命令自 Redis 1.0.0 起可用,时间复杂度为 O(1),ACL 分类包括 @connection 和 @fast。
快速验证
前置条件:已安装 redis-cli,目标 Redis 正在运行,网络可达,且当前用户具有执行该命令的权限。
在系统终端检查本机默认 Redis 连接:
# 默认连接 127.0.0.1:6379
redis-cli PING预期输出:
PONGPONG 表示本次连接能够到达 Redis,并成功获得命令响应。
检查指定实例时,可使用 redis-cli -h <HOST> -p <PORT> PING,其中 <HOST> 和 <PORT> 需要替换为实际主机与端口。远程实例如果启用了身份认证或 TLS,还必须配置相应的认证信息和连接选项。
常见异常与恢复
| 现象 | 可能原因 | 排查与恢复 |
|---|---|---|
PONG |
命令成功执行 | 连接层检查通过,继续验证业务操作 |
Could not connect |
服务未启动、地址或端口错误、网络不可达 | 核对连接地址、监听端口、服务状态和防火墙 |
| 连接超时 | 网络不通、服务繁忙或响应延迟过高 | 检查网络路径、服务器负载与客户端超时配置 |
NOAUTH Authentication required |
当前连接尚未完成所需认证 | 使用正确凭据认证后重试 |
NOPERM |
当前 ACL 用户无权执行命令 | 检查用户权限,由管理员按需授权 |
| 其他 Redis 错误 | 实例可能处于暂时无法服务的状态 | 根据具体错误信息检查实例状态和服务器日志 |
使用 redis-cli --askpass 可以交互输入密码,避免将明文密码直接放在命令行参数中。若实例使用 ACL 命名用户,还需提供正确的用户名。不要仅为使 PING 成功而关闭认证或扩大用户权限。
健康检查边界
PING 只验证当前连接的一次命令响应,不能证明以下条件成立:
- 当前账号拥有业务键的读取、写入或删除权限。
- Redis 数据能够正常持久化到磁盘。
- 主从复制已经同步,或所有集群节点均可用。
- 业务客户端的连接池、数据库选择、超时和重试配置正确。
若需要验证实际业务能力,应使用业务账号,在目标实例上执行受控的读取或写入检查。写入测试建议使用专门的测试键并设置过期时间,避免覆盖真实业务数据。
AUTH [username] password在受 ACL 保护的实例上完成用户或默认账户认证;适合交互式联调,避免将真实凭证明文写入可记录的命令历史和共享日志。
认证当前连接
连接 Redis 后遇到 NOAUTH Authentication required.,或需要切换到指定 ACL 用户身份时,使用 AUTH 认证当前连接。成功后返回 OK,后续命令按照该用户的 ACL 权限执行,无需重新建立连接。
基本语法
AUTH [username] password| 参数 | 含义 | 约束 |
|---|---|---|
username |
要认证的 ACL 用户名 | 可选;省略时使用 default |
password |
对应用户的认证密码 | 必填;必须与服务器配置的有效凭证匹配 |
Redis 6.0 起支持两参数形式 AUTH username password,用于 ACL 用户认证。Redis 6.0 之前只支持 AUTH password,针对默认账户使用配置的密码。
单参数形式在 Redis 6.0 及之后仍可使用,但只会认证为 default 用户,不能据此切换到其他 ACL 用户。
交互式认证与验证
前置条件:已安装 redis-cli,目标 Redis 服务可以连接,且已知有效的用户名和密码。以下假定本机 Redis 监听默认端口,default 用户已启用并配置密码。
先建立连接:
redis-cli -h 127.0.0.1 -p 6379预期结果:进入交互模式,出现 127.0.0.1:6379> 提示符。若服务器不可达,应先检查地址、端口、服务状态以及网络访问权限。
在交互提示符中依次执行以下命令,将 <PASSWORD> 替换成实际密码。此处仅用于受控测试环境,避免在会记录输入的生产终端直接键入真实凭证。
AUTH default <PASSWORD>
PING预期输出(假定凭证正确且当前用户具有 PING 权限):
OK
PONGOK 表示身份认证成功,PONG 表示当前连接能够正常执行 PING。如果 ACL 用户不具备 PING 权限,即使认证成功,后续也可能返回 NOPERM,不能因此判断密码错误。
AUTH 只影响当前连接,不会修改用户密码、ACL 配置或其他连接的认证状态。连接关闭后,新建连接必须按照服务器配置重新认证。
常见错误与恢复
| 返回信息 | 常见原因 | 处理方式 |
|---|---|---|
NOAUTH Authentication required. |
尚未完成认证 | 使用有效凭证执行 AUTH 后重试原命令 |
WRONGPASS |
用户名或密码错误,或者用户已禁用 | 核对用户名、凭证来源和 ACL 用户状态,再重新认证 |
NOPERM |
已认证用户不具备目标命令或键的访问权限 | 使用已授权操作验证,必要时请管理员检查 ACL 规则 |
ERR wrong number of arguments |
参数数量不符合命令语法 | 检查是否误传用户名,尤其是 Redis 6.0 之前的版本 |
遇到 WRONGPASS 时,应先确认账户和密码,不要连续猜测凭证。ACL 用户被禁用或没有有效密码时,需要具有相应管理权限的人员修复账户配置,重复执行 AUTH 无法解决。
如果认证成功但业务命令仍被拒绝,应检查 ACL 授权范围,而不是盲目切换到高权限用户。
凭证安全与使用边界
生产环境使用 redis-cli 时,优先考虑 --askpass 交互式隐藏输入密码,或通过受控凭证管理机制注入认证信息,避免使用带明文密码的 -a 命令行参数。访问要求加密传输的远程实例时,应配置 TLS 连接并正确验证服务端证书。
默认 Redis ACL 配置可能允许 default 用户无密码访问,此时新连接可以自动获得该用户身份,不需要执行 AUTH。不要把能够执行 PING 等同于实例已经开启密码保护。
速查:AUTH 返回 OK 确认身份认证成功;后续命令能否执行,仍取决于 ACL 权限。 具体版本行为可参考 Redis AUTH 官方文档。
SELECT index切换当前连接使用的逻辑数据库,常见于单机开发环境的隔离测试;Redis Cluster 仅支持数据库零,不应把逻辑库当作强租户隔离。
选择逻辑数据库
当单机开发环境需要切换测试数据集,或者查询某个键时怀疑当前连接选错数据库,可以使用 SELECT 指定逻辑数据库编号。执行成功后,当前连接的后续键操作都针对新选中的数据库,不会移动、复制或删除已有键。
基本语法
SELECT indexindex:目标逻辑数据库编号,必须是非负整数,且小于实例配置的databases数量。- 默认配置通常提供 16 个逻辑数据库,编号为
0~15;实际范围以服务器配置为准。 - 新连接默认选择数据库
0。成功执行SELECT返回OK,失败时保持原来的数据库选择。 - 切换只作用于当前连接,不会改变其他连接正在使用的数据库。
SELECT 0 是切回默认数据库的常用命令。逻辑数据库编号不是 Redis Cluster 的分片编号,也不是独立的 Redis 实例。
切换与验证
以下示例适用于本机可访问、无需认证的 Redis Open Source 单机实例。要求至少配置两个逻辑数据库,并使用 Redis 6.2 或更新版本,以便通过 CLIENT INFO 验证连接状态。
redis-cli <<'REDIS'
SELECT 1
CLIENT INFO
SELECT 0
CLIENT INFO
REDIS这组命令在同一条 Redis 连接中依次执行,避免每次重新调用 redis-cli 导致数据库选择恢复默认值。
预期结果:
- 第一次
SELECT 1返回OK,随后CLIENT INFO返回的连接信息包含db=1。 - 第二次
SELECT 0返回OK,随后CLIENT INFO返回的连接信息包含db=0。 CLIENT INFO还包含客户端 ID、地址及其他状态字段,实际内容可能不同,以其中的db字段为准。
SELECT 从 Redis 1.0.0 开始提供;CLIENT INFO 从 Redis 6.2.0 开始提供。旧版本可通过同一连接内的已知测试键验证数据库选择,但不要依赖重新建立的连接进行验证。
数据隔离范围
不同逻辑数据库具有独立的键空间,因此同一个键名可以分别存在于数据库 0 和数据库 1 中,且对应不同的值。切换后执行 GET、SET、DEL 或 SCAN 等键操作,访问的是当前选中的数据库。
但所有逻辑数据库仍属于同一个 Redis 实例,共享服务器资源和实例级配置。它们不能作为严格的租户安全边界,也不能代替独立实例或专门的权限隔离方案。
| 场景 | 使用建议 |
|---|---|
| 本地开发中分开临时测试数据 | 可以使用不同逻辑数据库 |
| 需要按环境或业务隔离键名 | 优先采用明确的键名前缀;必要时使用独立实例 |
| 多租户安全隔离 | 不依赖 SELECT,应设计独立的访问控制与资源边界 |
| Redis Cluster | 仅支持数据库 0,不使用 SELECT 切换数据库 |
部分托管 Redis 产品也可能不支持多个逻辑数据库,使用前应核对服务提供方的限制。
常见错误与恢复
- 数据库编号超出范围:可能返回
ERR DB index is out of range。检查服务器的databases配置,改用有效编号;没有配置权限时联系实例管理员。 - 集群模式不支持:Redis Cluster 不允许通过
SELECT切换逻辑数据库。改为使用数据库0,通过键名前缀或独立集群组织数据。 - 切换后找不到键:先用
CLIENT INFO检查db字段,再确认键所在的数据库。不同逻辑库里的同名键互不相同。 - 连接池中的数据库状态混乱:
SELECT属于连接级状态。归还连接时如果没有恢复预期数据库,下一位复用者可能访问错误的键空间。应在客户端连接配置中固定数据库,避免在共享连接上临时切换。 - 权限或连接失败:先确认连接目标、认证状态和命令权限。认证失败并不代表目标逻辑数据库不存在。
需要恢复默认选择时,在原连接执行 SELECT 0,成功后检查 db=0。这只能恢复连接的数据库选择,不能撤销先前在其他数据库执行的写入或删除。
速查:SELECT 0 切回默认库;SELECT 1 切换到数据库 1(前提是该数据库存在);Redis 6.2+ 可用 CLIENT INFO 的 db 字段确认当前连接选择。
EXISTS key [key ...]检查一个或多个键当前是否存在,适合缓存命中和清理前确认;多键结果是存在数量而非布尔值,重复传入同一个键也会重复计数。
判断键是否存在
需要确认缓存键是否仍然存在,或在清理前核对目标键时,使用 `EXISTS`。命令返回查询时存在的键参数数量,而不是布尔值;即使重复传入同一个键,也会按出现次数重复计数。
基本语法
`EXISTS key [key ...]`
- `key`:必填,待检查的 Redis 键名。
- `[key ...]`:可选,继续传入其他键;允许一次检查多个键,也允许重复键名。
返回值是整数:单键查询时,`1` 表示存在,`0` 表示不存在;多键查询时,返回存在的参数数量,范围为 `0` 到传入的参数总数。已经过期的键按不存在处理。
注意,多键返回 `1` 只能说明存在一个键参数,不能说明全部键都存在;返回值等于参数总数时,才表示本次传入的每个键参数都存在。
常用示例
前提是已安装 `redis-cli`,并且本机能够连接到测试 Redis。以下示例会创建、检查并删除临时键 `demo:exists:probe`,仅应在确认没有同名业务键的测试实例中执行。`--raw` 让整数结果以纯数字显示。
# 创建临时键,确保后续查询有确定结果
redis-cli --raw SET demo:exists:probe active
# 分别检查单键、多键和重复键
redis-cli --raw EXISTS demo:exists:probe
redis-cli --raw EXISTS demo:exists:probe demo:exists:missing
redis-cli --raw EXISTS demo:exists:probe demo:exists:probe
# 删除测试键,验证不存在时的返回值
redis-cli --raw DEL demo:exists:probe
redis-cli --raw EXISTS demo:exists:probe预期输出(按命令执行顺序):
OK
1
1
2
1
0单键查询返回 `1`,说明键存在。检查一个存在键和一个不存在键,结果仍然是 `1`。重复传入同一个存在键则返回 `2`,因为 Redis 按参数出现次数计数,而不是统计去重后的键名数量。
删除测试键时,`DEL` 返回 `1`,表示删除了一个键。随后 `EXISTS` 返回 `0`,表示该键当前已不存在。如果使用默认的交互式 `redis-cli` 输出模式,整数可能显示为 `(integer) 1` 等格式,数值含义不变。
使用边界与风险
- **只读检查**:`EXISTS` 本身不会修改键,但不能保证查询之后键仍然存在。键可能因 TTL 到期、其他客户端删除或并发写入而改变状态。
- **避免检查后读取的竞态**:先执行 `EXISTS`,再执行 `GET`,不是原子操作。读取字符串缓存时通常直接执行 `GET`,根据是否返回 nil 判断缓存是否命中,减少一次请求。
- **Redis Cluster 限制**:多键 `EXISTS` 要求所有键位于同一哈希槽,否则可能收到 `CROSSSLOT` 错误。跨槽检查应按槽分组执行,或分别查询后汇总结果。
- **不提供键的详细信息**:`EXISTS` 不能区分从未创建与已经过期的键,也不返回键类型、键值或剩余有效期。需要进一步确认时,分别使用 `TYPE`、`GET` 或 `TTL` 等命令。
TYPE key读取键的 Redis 数据类型,适合定位 WRONGTYPE 错误和核对数据模型;返回的是顶层类型名称,不提供集合元素结构或 JSON 内部字段类型。
识别键的数据类型
遇到 WRONGTYPE 错误,或需要确认某个键应该用哪组 Redis 命令读取时,使用 TYPE。它只查询键当前的顶层类型,不读取元素内容,时间复杂度为 O(1),适合先定位再检查。
基本语法
TYPE key 中的 key 是完整键名,命令一次只接收一个键。在 redis-cli 交互会话中直接输入;从系统终端调用时使用 redis-cli TYPE demo:user:42。确认连接的实例和逻辑数据库与业务程序一致,否则可能查询到同名但类型不同的键。
返回值与后续命令
| 返回值 | 含义 | 可选只读检查 |
|---|---|---|
string |
字符串;位图、HyperLogLog 等也可能使用这一底层类型 | GET(仅当值确为普通字符串) |
hash |
哈希 | HGET、HSCAN |
list |
列表 | LRANGE |
set |
无序集合 | SSCAN |
zset |
有序集合;地理空间索引也使用这一类型 | ZSCAN |
stream |
消息流 | XINFO STREAM |
vectorset |
向量集合,仅适用于支持该类型的 Redis 版本 | VCARD |
none |
当前数据库中键不存在或已过期 | 核对键名、数据库及过期状态 |
某些模块数据类型还可能显示模块专用标识。TYPE 不能揭示哈希字段、JSON 内部属性、集合元素的结构,也不表示键值一定能被直接当文本读取。
可复现示例
在独立的测试 Redis 实例中执行;下面的 SET 会覆盖同名键,不要在生产实例中直接照搬初始化操作。
# 用测试键创建一个明确的字符串值,再检查类型
redis-cli SET anystack:type:demo "ready"
redis-cli TYPE anystack:type:demo预期输出(依次对应两条命令):
OK
string检查业务键时只需运行 redis-cli TYPE demo:user:42,它不会修改数据。返回结果取决于实际存储的值;例如返回 hash 时,应检查业务代码是否误用了只接受字符串的 GET。
风险与排查边界
TYPE自身是只读命令,不会修正WRONGTYPE;要根据结果修改调用的读写命令,或核对是否发生同名键混用。- 返回
none时,先检查键名前缀、实例、逻辑数据库和 TTL;不要直接据此断言数据从未写入。 - 演示结束后,确认测试键没有被其他业务复用,再使用
DEL anystack:type:demo清理。若覆盖过原值,DEL无法恢复,必须从备份或原始数据源恢复。
命令定义及最新支持的类型以 Redis TYPE 官方文档 为准。
SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]通过游标分批遍历键空间,适合排查键名和批处理任务;必须持续迭代到游标归零,COUNT 只是提示,结果可能重复且单批可能为空。
渐进扫描键名
需要按前缀查找 Redis 键、排查异常数据或分批处理大量键名时,使用 SCAN 渐进遍历键空间。它每次返回一批键名和下一次扫描所需的游标,比直接使用 KEYS * 更适合生产环境。必须持续扫描到返回游标为 0,不能根据单批结果是否为空判断结束。
基本语法
SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]
| 参数 | 含义 | 默认值或约束 |
|---|---|---|
cursor |
扫描游标,首次传入 0,之后传入上次返回的游标 |
必填,不能自行递增 |
MATCH pattern |
按键名通配模式过滤结果 | 默认匹配全部键 |
COUNT count |
建议每次扫描的工作量 | 默认 10,不是严格返回数量 |
TYPE type |
只返回指定 Redis 数据类型的键 | Redis 6.0.0 起支持 |
MATCH 使用 Redis 通配模式,不是正则表达式。例如,demo:* 匹配以 demo: 开头的键,user:?:name 中的 ? 匹配单个字符。
TYPE 可以使用 string、hash、list、set、zset、stream 等类型名称。类型过滤依据 Redis 内部存储类型,例如 HyperLogLog 使用 string,不能通过独立的 hyperloglog 类型筛选。
扫描一批键名
前置条件是 Redis 服务可连接,且当前账号具有执行 SCAN 的权限。下面使用本机默认连接参数,读取当前所选数据库中以 demo: 开头的键。
# 只读取第一批键名,不修改 Redis 数据
redis-cli SCAN 0 MATCH 'demo:*' COUNT 100预期结果:返回一个包含两项的数组。第一项是下一游标,第二项是本批匹配到的键名列表。具体游标和键名取决于当前数据库,不能预先确定。
读取结果时遵循以下规则:
- 如果返回游标不是
0,将它原样作为下一次SCAN的第一个参数,保留相同的MATCH条件并继续执行。 - 如果本批没有键名,但游标不为
0,仍然继续扫描。 - 如果返回游标为
0,当前这一轮遍历结束;此时仍需要处理最后一批返回的键名。
COUNT 100 不代表一定返回 100 个键。Redis 可能返回少于 100 个、超过 100 个,甚至零个匹配结果。尤其在 MATCH 匹配范围很窄时,连续多批为空属于正常现象。
自动完成整轮扫描
不需要手工记录游标时,可以使用 redis-cli 的 --scan 模式。该模式内部重复执行 SCAN,直到游标回到 0。
# 自动迭代游标,逐行输出匹配的键名
redis-cli --scan --pattern 'demo:*' --count 100预期结果:终端逐行输出匹配到的键名;没有匹配结果时不输出键名。输出顺序不固定,部分键可能重复出现,因此不能直接把输出行数当作唯一键数量。
如果生产环境扫描造成明显负载,可以在 redis-cli --scan 模式中增加 -i 0.01,在扫描调用之间增加约 10 毫秒间隔。降低扫描频率会延长总耗时,但有助于减轻持续扫描的压力。
一致性与性能边界
SCAN 每次只推进一部分遍历工作,完整扫描的总体复杂度为 O(N),其中 N 是被遍历的键空间规模。它不是固定大小分页,也不提供数据库快照。
- 可能重复:同一个键可能在一轮扫描中出现多次。统计唯一键时需要去重;执行批处理时应保证操作可以安全重复。
- 可能遗漏变化中的键:整个扫描期间始终存在的键可以在完整迭代中被返回;扫描过程中新增、删除或过期的键不保证被返回。
- 过滤不代表跳过扫描:
MATCH和TYPE主要过滤返回结果,并不意味着只检查符合条件的键。 - 不保证顺序:扫描结果不是按键名、创建时间或数据类型排序的。
- 不保证立即结束:如果键空间持续快速增长,完整遍历可能无法及时完成。
Redis Cluster 中,SCAN 遍历的是当前连接节点持有的键空间,不能把单节点扫描结果视为整个集群的键清单。需要覆盖全量键时,应按集群拓扑扫描相关主节点,并考虑槽迁移、重复键和数据变化。
风险与恢复
SCAN 本身是只读命令,不会删除或修改键。风险主要来自过高的扫描频率,以及把扫描结果交给后续批量写入或删除程序。
如果手工扫描中断,可以保存最后一次返回的游标并继续;如果游标丢失,则从 0 重新开始,并通过去重或幂等处理避免重复操作。扫描本身无需回滚;若后续批处理修改了数据,恢复方式取决于该操作及已有备份,不能依靠 SCAN 撤销。
速查:从 0 开始、使用返回游标继续、到返回 0 结束;允许空批次,处理重复键。 官方参考:Redis SCAN 命令文档。
DBSIZE返回当前所选数据库的键总量,适合快速观察测试实例的数据规模;这是整体计数,不支持按前缀统计,也不能代替键空间的容量分析。
统计当前键数量
需要快速确认 Redis 当前逻辑数据库中有多少个键时,使用 DBSIZE。常见用途包括检查测试数据是否写入、清理操作后键数量是否下降,以及核对连接是否指向预期的数据库。命令返回一个非负整数,不返回键名,也不统计内存占用。
基本语法
DBSIZE在 Redis CLI 交互模式中直接执行,无需传入参数。
- 作用范围:当前连接选中的逻辑数据库,而不是 Redis 实例的所有数据库。
- 返回值:整数,表示当前数据库的键数量;空数据库通常返回
0。 - 时间复杂度:
O(1),直接读取键空间计数,不需要遍历所有键。 - 版本支持:Redis Open Source 1.0.0 及以后版本。
DBSIZE 没有 MATCH、COUNT 或数据库编号参数。需要切换逻辑数据库时,应先通过客户端选择目标数据库,再执行统计。
常用示例
前提是本机已安装 redis-cli,并且默认连接地址上的 Redis 服务正在运行。以下命令显式选择逻辑数据库 0,并输出当前键数量。
# --raw 只输出原始结果,-n 0 指定逻辑数据库 0
redis-cli --raw -n 0 DBSIZE预期输出(假设数据库中当前有 3 个键):
3实际输出取决于查询时的键数量。如果数据库为空,输出为 0。由于指定了 --raw,这里直接显示数字;普通交互式 Redis CLI 通常将整数显示为 (integer) 3。
-n 是 redis-cli 的客户端选项,不是 DBSIZE 的参数。在支持多个逻辑数据库的普通 Redis 实例上,可将 -n 0 改为 -n 1 等有效编号,分别检查不同数据库。
统计范围与结果判断
DBSIZE 统计整个当前数据库的键数量,不区分 String、Hash、List、Set、Sorted Set 等数据类型。一个 Hash 即使包含多个字段,也只作为一个 Redis 键计入总数。
| 需求 | 应采用的方式 |
|---|---|
| 查看当前数据库键总数 | DBSIZE |
| 查看各逻辑数据库的键数量摘要 | INFO keyspace |
| 查找指定前缀的键 | SCAN 配合 MATCH |
| 分析实例内存占用 | INFO memory |
例如,数据库中有 user:1、user:2 和 order:1 三个键,DBSIZE 返回 3,而不是 2。它无法直接回答 user:* 有多少个键;如果需要按前缀计数,应使用 SCAN 完成游标遍历,对匹配结果去重后统计。
异常排查与边界
如果结果与预期不符,优先检查以下情况:
- 连接目标错误:确认客户端连接的是预期的 Redis 主机和端口,而不是另一套测试或生产实例。
- 数据库选择错误:检查
-n或此前执行的SELECT。普通 Redis 连接默认选择数据库0。 - 键已过期或被淘汰:检查业务键的 TTL、过期策略和实例的内存淘汰配置。
- 权限不足:如出现
NOPERM,检查当前用户 ACL 是否允许执行DBSIZE。不要为了计数直接授予不必要的高权限。 - 集群统计范围不同:在 Redis Cluster 中,连接某个节点执行
DBSIZE不能直接得到整个集群所有分片的键总数。需要分别统计相关主节点,再进行汇总,并考虑数据迁移期间的变化。
速查:只想知道当前数据库有多少个键,执行 DBSIZE;要按前缀筛选、比较不同数据库或分析内存容量,应改用对应的扫描或统计命令。
字符串与缓存生命周期
SET key value [NX | XX | IFEQ ifeq-value | IFNE ifne-value | IFDEQ ifdeq-digest | IFDNE ifdne-digest] [GET] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL]写入字符串并可同时指定过期时间或条件更新,适合缓存和轻量状态;默认会覆盖已有值并清除原 TTL,条件写入应检查返回结果。
写入字符串或缓存
需要缓存页面结果、保存轻量状态或按条件更新已有值时,使用 SET 一次完成写入和过期时间设置。默认覆盖同名键,即使原键不是字符串类型,也会被替换;成功写入后原有 TTL 会被清除,除非明确指定新的过期时间或使用 KEEPTTL。
基本语法
SET key value [NX | XX | IFEQ ifeq-value | IFNE ifne-value | IFDEQ ifdeq-digest | IFDNE ifdne-digest] [GET] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL]key:要写入的 Redis 键名;不存在时默认创建。value:写入的字符串值,可以是普通文本、数字文本或序列化后的 JSON 字符串。- 不指定条件时,无论键是否存在都会写入;不指定过期选项时,成功写入的键没有过期时间。
命令的条件选项只能选择一种,过期选项也只能选择一种。GET 可以与允许的条件选项、过期选项组合使用,但必须根据服务器版本判断兼容性。
常用选项
| 选项 | 作用 | 适用场景 |
|---|---|---|
NX |
仅当键不存在时写入 | 首次初始化、避免覆盖已有缓存 |
XX |
仅当键存在时写入 | 只更新已有状态 |
IFEQ value |
当前值等于指定值才写入 | 比较后更新,避免覆盖已变化的状态 |
IFNE value |
当前值不等于指定值才写入;键不存在时允许创建 | 避免重复写入相同值 |
IFDEQ digest |
当前值的摘要等于指定摘要才写入 | 大字符串的条件更新 |
IFDNE digest |
当前值的摘要不等于指定摘要才写入;键不存在时允许创建 | 基于摘要的差异写入 |
GET |
返回写入前的旧字符串值 | 需要获取旧值的更新操作 |
EX seconds |
设置相对过期时间,单位秒 | 页面缓存、验证码等 |
PX milliseconds |
设置相对过期时间,单位毫秒 | 需要毫秒级 TTL 的临时状态 |
EXAT timestamp |
按 Unix 秒时间戳设置绝对过期时刻 | 固定截止时间的缓存 |
PXAT timestamp |
按 Unix 毫秒时间戳设置绝对过期时刻 | 毫秒级绝对过期时刻 |
KEEPTTL |
成功更新时保留原键的过期时间 | 更新内容但不延长缓存寿命 |
EX 和 PX 的过期时长必须为正整数。EXAT、PXAT 使用 Unix 时间戳,而不是持续时间;如果指定的时间已经过去,成功写入的键会立即过期。
IFEQ、IFNE、IFDEQ、IFDNE 从 Redis 8.4.0 开始支持。其中摘要由 DIGEST key 获取,采用 XXH3 算法,不能随意使用 MD5 或 SHA 摘要替代。
缓存写入与验证
以下示例使用本机默认地址和端口的 Redis,要求服务已启动并允许当前客户端访问。命令在操作系统终端执行;为了观察 TTL,请连续执行,避免超过 300 秒。
# 写入页面缓存,设置 300 秒自动过期
redis-cli SET demo:cache:page42 ready EX 300
redis-cli GET demo:cache:page42
redis-cli TTL demo:cache:page42
# 已有缓存存在时,NX 不允许覆盖,也不会刷新 TTL
redis-cli SET demo:cache:page42 queued NX EX 300
redis-cli GET demo:cache:page42预期结果:
- 第一次
SET返回OK,表示写入成功。 - 第一次
GET返回ready。 TTL返回剩余秒数,通常接近 300;在未过期时为 0~300,具体值取决于执行时间。- 第二次
SET因NX条件不满足,返回空回复,redis-cli通常显示(nil)。 - 最后一次
GET仍返回ready,说明条件写入没有覆盖原值。
如果执行期间缓存已经过期,NX 可能重新创建键并返回 OK。因此条件写入的成功与否必须根据实际返回值判断,不能假设键始终存在。
返回值与条件判断
不使用 GET 时,成功写入返回 OK;条件不满足时返回空回复,原有值和 TTL 均不改变。例如 NX 遇到已有键、XX 遇到不存在的键,以及比较条件不满足时,都不会完成写入。
使用 GET 时,返回的是写入前的旧字符串值,而不是 OK。如果旧键不存在则返回空回复;即使条件不满足而没有写入,存在的旧值仍可能被返回。因此不能仅凭 GET 返回了旧值就判断更新成功。
如果旧键保存的是列表、哈希等非字符串类型,带 GET 的 SET 会返回类型错误并取消写入;不带 GET 的普通 SET 则可以直接覆盖这些类型。
版本边界如下:
- Redis 2.6.12 起支持
EX、PX、NX、XX。 - Redis 6.0.0 起支持
KEEPTTL。 - Redis 6.2.0 起支持
GET、EXAT、PXAT。 - Redis 7.0.0 起允许组合
NX与GET。 - Redis 8.4.0 起支持四种
IF条件比较选项及DIGEST命令。
可通过 redis-cli INFO server 查看 redis_version,并根据实际版本选用参数。完整定义参见 Redis SET 官方文档。
风险与恢复
误清除 TTL:对已有缓存执行不带过期选项的 SET,会使成功写入的键变为永久有效。可以使用 TTL key 检查:-1 表示键存在但没有过期时间,-2 表示键不存在。需要恢复缓存寿命时,使用 EXPIRE key seconds 重新设置过期时间;后续更新可使用 KEEPTTL 保留剩余寿命。
误覆盖数据:普通 SET 不检查旧值,可能覆盖其他客户端刚写入的结果。Redis 8.4.0 及以上可使用 IFEQ 或 IFDEQ 进行原子条件更新;低版本若需要比较并更新,应采用 Lua 脚本等服务器端原子操作,避免客户端先 GET 后 SET 的竞态。
误写过期时间:将秒误写成毫秒,或把相对时间误写为已经过去的绝对时间,可能造成缓存提前失效。写入后用 TTL 或 PTTL 检查剩余时间;发现异常时,及时重新写入正确值并指定正确过期时间。
速查:普通缓存优先使用 SET key value EX seconds;只在不存在时创建使用 NX;更新已有键使用 XX;需要保留原过期时间使用 KEEPTTL。条件写入不带 GET 时,依据 OK 与空回复区分成功和跳过。
GET key读取指定键的字符串内容,适合缓存命中查询和简单状态检查;键不存在返回空值,键的实际类型不是字符串时会返回类型错误。
读取字符串值
需要检查页面缓存、会话标记或简单业务状态时,使用 GET 读取指定键的字符串内容。命令不会修改键值或刷新过期时间;如果键不存在,返回空值;如果键属于其他数据类型,则返回类型错误。
基本语法
GET key 读取一个字符串键,参数 key 是完整键名。在 redis-cli 交互模式中可以直接输入 GET demo:cache:page42;在操作系统终端中执行时,需要添加 redis-cli 前缀。
key:必填,目标键名,区分大小写。- 返回值:键存在且类型为字符串时,返回保存的字符串内容。
- 空值:键不存在时返回 Redis 空回复(nil),不等同于保存了空字符串。
- 类型限制:不支持直接读取 Hash、List、Set、Sorted Set 等非字符串键。
Redis 的字符串值可以保存普通文本、数字文本或序列化后的 JSON。GET 不负责解析内容;如果保存的是 JSON,应用程序需要在读取后自行反序列化。
常用示例
以下示例假设本机 Redis 服务已启动,且允许通过默认连接参数访问。先创建有效期为 300 秒的演示缓存,再读取内容、检查存在性和数据类型。
# 创建演示缓存,并设置 300 秒过期时间
redis-cli SET demo:cache:page42 "page-v1" EX 300
# 使用 --raw 获得便于脚本处理的原始文本
redis-cli --raw GET demo:cache:page42
# 检查键是否存在以及实际数据类型
redis-cli --raw EXISTS demo:cache:page42
redis-cli --raw TYPE demo:cache:page42预期输出(命令在缓存过期前执行):
OK
page-v1
1
stringOK 表示写入成功,page-v1 是读取到的缓存内容,1 表示键存在,string 表示键的数据类型符合 GET 要求。这里使用 SET 是为了构造可复现数据;日常检查已有缓存时只需执行读取命令。
返回值与异常判断
| 键的状态 | GET 的结果 |
判断方式 |
|---|---|---|
| 存在且为普通字符串 | 返回实际内容 | 与预期缓存值比较 |
| 存在且为空字符串 | 返回空字符串 | EXISTS 返回 1 |
| 不存在或已经过期 | 返回 nil | EXISTS 返回 0 |
| 存在但类型不是字符串 | 返回 WRONGTYPE 错误 |
使用 TYPE 确认类型 |
在 redis-cli 的常规交互显示模式下,不存在的键通常显示为 (nil),而空字符串显示为 ""。使用 --raw 时,两者都可能表现为空白输出,因此不能只凭终端上是否有文字判断缓存是否命中。
遇到 WRONGTYPE Operation against a key holding the wrong kind of value 时,应先确认键名与数据类型。对于 Hash,应使用 HGET 或 HGETALL 等相应命令,而不是强行通过 GET 读取。
过期时间与使用边界
GET 不会延长键的 TTL。如果缓存设置了 300 秒有效期,多次读取仍然可能在到期时得到 nil。需要检查剩余时间时,可以使用 TTL key:返回非负整数表示剩余秒数,-1 表示键没有设置过期时间,-2 表示键不存在。
排查缓存时还应注意以下边界:
GET本身是只读命令,但示例中的SET会覆盖同名键,不能直接用于已有生产缓存。- 大字符串会产生相应的网络传输与客户端内存开销,排查大对象时不宜反复读取完整内容。
GET与后续EXISTS、TYPE是独立命令;如果键在两次操作之间过期或被修改,检查结果可能不同。- 读取到 nil 时,应用可以按缓存未命中处理,但应区分正常过期、键名错误和缓存尚未写入等原因。
MSET key value [key value ...]一次写入多个字符串键,适合预热一组不需要单独 TTL 的缓存;已有值会被覆盖,集群环境下应确认多键操作的槽位约束。
批量写入多个键
需要一次初始化或更新多个字符串缓存键,并且允许覆盖已有值时,使用 MSET。它将多个键值对作为一条原子命令写入,成功后返回 OK,适合功能开关初始化、配置缓存预热等场景。执行前需要确认覆盖范围及集群槽位约束。
基本语法
MSET key value [key value ...]
| 参数 | 含义 | 约束 |
|---|---|---|
key |
要写入的 Redis 键 | 至少提供一个键 |
value |
对应的字符串值 | 每个键必须配一个值 |
[key value ...] |
后续键值对 | 可重复追加,必须成对出现 |
MSET 的时间复杂度为 O(N),其中 N 是写入的键数量。它不会逐键返回状态,也不支持 EX、PX、NX 或 XX 等选项。
命令执行具有原子性:其他客户端不会观察到本次命令只更新了部分键的中间状态。但原子性不代表数据自动持久化,也不代表误覆盖后可以直接回滚。
常用示例与预期结果
前置条件:本机已启动 Redis,redis-cli 可以通过默认连接访问实例,且当前账号具有写入和读取演示键的权限。以下命令在系统终端中执行,使用 --raw 统一输出格式。
# 一次写入两个功能开关键
redis-cli --raw MSET demo:flag:a on demo:flag:b off
# 按请求顺序读取两个键,确认写入结果
redis-cli --raw MGET demo:flag:a demo:flag:b
# 检查写入后的键是否设置过期时间
redis-cli --raw TTL demo:flag:a预期输出:
OK
on
off
-1其中 OK 表示批量写入成功;on 和 off 分别是两个键的当前值;TTL 返回 -1 表示键存在且没有设置过期时间。
即使这些键原本存在,MSET 也会直接覆盖其值。如果原来的键保存的是列表、哈希或其他数据类型,覆盖后也会变成字符串类型,因此不能把它当作仅更新已有字符串值的命令。
覆盖行为与 TTL
MSET 不提供过期时间参数。对于被覆盖的已有键,原先设置的 TTL 也会被清除。因此,批量更新缓存前必须确认是否允许这些键变成不过期状态。
| 使用需求 | 推荐方式 |
|---|---|
| 多个键同时写入,不需要 TTL | MSET |
| 单个键写入并设置 TTL | SET key value EX seconds |
| 多个键分别具有不同 TTL | 分别执行带过期参数的 SET |
| 所有目标键都不存在时才批量写入 | MSETNX |
MSETNX 与 MSET 的区别是:只有全部目标键都不存在时才写入,任意一个键已存在就不执行本次批量写入。它返回整数 1 或 0,而非 OK。
如果先使用 MSET,再逐键执行 EXPIRE,这些操作之间存在时间窗口,不能视作整体原子更新。需要将批量写入与 TTL 修改作为一个原子操作时,可以在适用的 Redis 环境中使用事务或 Lua 脚本,并确保所有相关键满足集群槽位约束。
集群环境的槽位约束
在 Redis Open Source Cluster 中,一条 MSET 命令涉及的所有键必须属于同一个哈希槽。即使两个键位于同一物理节点,只要槽位不同,也不能直接作为一条多键命令执行。
例如,demo:flag:a 与 demo:flag:b 不保证处于同一槽位,因此上面的演示命令适用于单实例,但在 Cluster 环境中可能遇到 CROSSSLOT 错误。
可以使用相同的 Hash Tag 规划键名:
demo:{flag}:ademo:{flag}:b
Redis Cluster 使用有效花括号中的 flag 计算这两个键的哈希槽,因此它们会落在同一槽位。
在已连接的集群环境中,可以通过下面的命令检查槽位:
# 检查两个共享 Hash Tag 的键是否处于同一槽位
redis-cli -c --raw CLUSTER KEYSLOT 'demo:{flag}:a'
redis-cli -c --raw CLUSTER KEYSLOT 'demo:{flag}:b'预期结果:两行输出均为相同的整数槽位编号,具体编号由 Redis 的哈希槽算法决定。确认一致后,再使用这两个键执行 MSET。
部分客户端库可能把跨槽批量操作拆成多条单键命令。此时即使客户端调用成功,也不能据此认为跨槽写入具备原始 MSET 的整体原子性,应检查实际客户端实现。
常见错误与恢复
- 键值参数不成对:会出现参数数量错误。检查
MSET后是否按键、值交替提供参数,包含空格的值应使用引号保护。 - 集群返回 CROSSSLOT:先检查各键槽位,再按业务归属调整 Hash Tag 或拆分操作。拆分写入会改变原子性保证,不应在未确认业务要求时自动重试。
- 缓存意外永久保留:使用
TTL检查是否返回-1。如果业务仍要求过期,可根据原定策略重新设置EXPIRE,但不要凭猜测填写过期秒数。 - 已有数据被覆盖:
MSET没有撤销功能。如果误覆盖,应从可信数据源或备份恢复原值,并重新确认数据类型与 TTL。
速查:无条件批量覆盖选 MSET;全部不存在才写入选 MSETNX;需要逐键 TTL 时优先考虑带过期参数的 SET。
MGET key [key ...]按传入顺序读取多个字符串键,适合减少批量缓存读取的往返次数;缺失或非字符串键的对应位置会返回空值,集群要注意跨槽限制。
批量读取多个键
需要一次读取多个字符串缓存键、减少网络往返时使用 MGET。它按传入键的顺序返回对应的值,即使部分键不存在,也能通过返回数组的位置判断哪个键未取得字符串值。适合批量读取功能开关、用户属性和缓存字段。
基本语法
MGET key [key ...]key:必填,至少一个 Redis 键名。[key ...]:可选,继续指定更多键;键名必须明确列出,不支持通配符匹配。- 无额外命令选项,返回数组长度始终与输入键数量相同。
- 时间复杂度为
O(N),其中N是请求的键数;实际传输开销还取决于返回值大小。
MGET 只读取字符串类型。对于不存在的键或存储类型不是字符串的键,对应位置返回 nil,而不是让整个命令报类型错误。返回结果不会附带键名,调用方必须保留请求顺序。
常用示例
前置条件:已安装 redis-cli,本地测试 Redis 服务可连接,示例键尚不存在。以下命令在独立测试实例中执行;前两条写入测试数据,最后一条完成批量读取。
# 准备两个字符串缓存键
redis-cli SET demo:flag:a on
redis-cli SET demo:flag:b off
# 强制使用易读格式,验证返回顺序和缺失键
redis-cli --no-raw MGET demo:flag:a demo:flag:b demo:flag:missing预期输出:
OK
OK
1) "on"
2) "off"
3) (nil)第三个键不存在,因此对应位置返回 (nil)。如果业务端传入两个键 demo:flag:a 和 demo:flag:b,返回值就依次是 on、off。应用代码需要根据请求键数组的索引关联结果,不能依赖返回值本身区分来源。
集群模式限制
在标准 Redis Cluster 中,MGET 的所有键必须属于同一个哈希槽。如果直接对不同槽的键执行批量读取,会收到 CROSSSLOT 错误;启用 redis-cli -c 自动重定向也不能消除这个限制。
对业务上需要共同读取的键,可以使用相同的哈希标签:
# 花括号中的 flag 决定两个键使用相同哈希槽
redis-cli -c SET 'demo:{flag}:a' on
redis-cli -c SET 'demo:{flag}:b' off
redis-cli -c --no-raw MGET 'demo:{flag}:a' 'demo:{flag}:b'预期输出:
OK
OK
1) "on"
2) "off"此示例要求连接到可用的 Redis Cluster 节点。如果出现 CROSSSLOT,应检查键名中的哈希标签是否一致;可通过 CLUSTER KEYSLOT 分别检查两个键的槽号。如果迁槽期间返回 TRYAGAIN,应在短暂退避后重试。
风险与恢复
MGET 是只读命令,不修改缓存,也不改变 TTL,因此读取本身不需要回滚。但前面示例中的 SET 会覆盖已有值并移除原有过期时间;不要直接在生产环境对未知键运行初始化示例。误覆盖后只能依据备份或业务源数据恢复。
批量读取减少请求次数,不代表键越多越好。大量键或大字符串会增加响应体积、服务器处理时间和客户端内存占用。业务中可根据实际负载分批读取,避免一次请求聚集过多数据。
速查要点:按输入顺序返回、缺失或非字符串值对应 nil、标准 Redis Cluster 要求同槽。如果键确实分散在不同槽,应在客户端按槽分组执行,或使用支持集群路由的客户端分别读取。
MSETEX numkeys key value [key value ...] [NX | XX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL]原子写入多个字符串并统一设置 TTL,适合需要一起生效的缓存快照;仅适用于 Redis 8.4 起的版本,集群多键仍须符合槽位约束。
批量写入并统一过期
当一组字符串缓存需要同时更新,并使用相同的过期时长或到期时间时,使用 MSETEX。它在单条命令中原子写入多个键,可以避免逐个执行 SET EX 时出现部分键已更新、部分键尚未更新的中间状态。该命令要求 Redis 8.4.0 或更高版本,集群环境还要求所有目标键属于同一哈希槽。
基本语法
MSETEX numkeys key value [key value ...] [NX | XX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL]numkeys:本次写入的键值对数量,必须与后续实际提供的键值对数量一致。key value:每个键后面紧跟对应的字符串值,可以连续提供多组。NX:仅当所有指定键都不存在时才执行写入。XX:仅当所有指定键都已经存在时才执行写入。
不提供 NX 或 XX 时,命令允许覆盖已有键。执行成功返回整数 1,条件不满足时返回整数 0,不会只更新部分键。NX 与 XX 互斥,不能同时指定。
过期选项
| 选项 | 含义 | 示例或约束 |
|---|---|---|
EX seconds |
设置统一的相对过期时间,单位为秒 | EX 300,五分钟后过期 |
PX milliseconds |
设置统一的相对过期时间,单位为毫秒 | PX 1500,1.5 秒后过期 |
EXAT unix-time-seconds |
设置统一的绝对过期时间,使用 Unix 秒时间戳 | 必须传入有效的正整数时间戳 |
PXAT unix-time-milliseconds |
设置统一的绝对过期时间,使用 Unix 毫秒时间戳 | 注意不能误传秒级时间戳 |
KEEPTTL |
保留各键原有的 TTL | 不会强制各键使用相同 TTL |
上述五种过期选项互斥,一次只能选择一种。需要统一过期时,应明确指定 EX、PX、EXAT 或 PXAT;不要使用 KEEPTTL 代替统一过期设置。
相对过期适合短期缓存快照,绝对过期适合所有缓存必须在某个业务截止时刻失效的场景。计算 EXAT、PXAT 时应使用正确的 Unix 时间单位,并确保目标时间符合预期。
常用示例与验证
前置条件:Redis 服务版本不低于 8.4.0,本机已安装 redis-cli,并允许覆盖示例中的测试键。以下命令适用于默认连接参数下可访问的独立 Redis 实例。
# 原子写入两个字符串键,统一设置 300 秒 TTL
redis-cli MSETEX 2 demo:flag:c on demo:flag:d off EX 300
# 验证两个值均已写入
redis-cli MGET demo:flag:c demo:flag:d
# 分别检查剩余生存时间
redis-cli TTL demo:flag:c
redis-cli TTL demo:flag:d预期结果:
MSETEX返回整数1,表示两个键全部写入成功。MGET按输入顺序返回on、off。- 两次
TTL查询均返回不大于300的非负整数,刚写入时通常接近300,随后逐秒递减。
如果 TTL 返回 -2,表示键不存在或已经过期;返回 -1 则表示键存在但没有设置过期时间。这两种结果都不符合本示例刚完成写入后的预期,应检查命令是否成功、目标键名是否正确以及是否存在其他客户端修改。
对于条件写入,若添加 NX 时任意目标键已经存在,或添加 XX 时任意目标键不存在,命令返回 0,原有键值和 TTL 均不会因这次失败的条件写入而改变。调用方应将 0 视为条件未通过,而不是部分成功。
集群限制与常见错误
Redis Cluster 中,一条 MSETEX 涉及的全部键必须映射到同一哈希槽。示例元数据中的 demo:flag:c、demo:flag:d 没有共同哈希标签,不适合直接作为集群多键操作的通用示例。
在集群中可以改用相同哈希标签,并启用 redis-cli 的集群重定向模式:
# 花括号内的 batch 相同,确保两个键处于同一哈希槽
redis-cli -c MSETEX 2 'demo:flag:{batch}:c' on 'demo:flag:{batch}:d' off EX 300
# 校验两键的槽号
redis-cli -c CLUSTER KEYSLOT 'demo:flag:{batch}:c'
redis-cli -c CLUSTER KEYSLOT 'demo:flag:{batch}:d'预期结果:第一条命令返回整数 1,后两条命令返回相同的槽号。实际槽号由 Redis 计算,不需要手工指定。若出现 CROSSSLOT,说明目标键不符合单槽约束;仅添加 -c 不能让跨槽原子写入成功,需要调整键名或重新设计缓存分组。
如果出现 ERR unknown command,首先确认服务端版本是否支持 MSETEX。如果出现参数数量或语法错误,检查 numkeys 与键值对数量是否一致、过期参数是否为合法数值,以及是否重复指定互斥选项。
风险与恢复
MSETEX 的原子性只保证一次命令中的写入整体生效,不代表自动保存历史值,也不提供执行成功后的撤销能力。未指定条件选项时会覆盖目标键;更换过期策略也可能改变原有缓存生命周期。
生产环境覆盖前,建议使用 MGET 读取旧值,并针对每个键使用 PTTL 记录剩余过期时间。若发生误覆盖,需要根据备份恢复值及过期策略;恢复操作本身不具有自动回滚能力,且剩余 TTL 会随着时间减少。若键可能被其他客户端并发修改,应先核对当前状态,避免使用过时备份覆盖新的有效数据。
命令时间复杂度为 ,其中 是写入的键数量。大批量写入会增加单次命令执行成本,应控制每批键数和数据总量。涉及跨槽数据时,应优先调整键的哈希标签或使用业务级版本切换方案,不要把多条独立写入误认为原子批量更新。
速查:统一 TTL 用 EX 或 PX;全部不存在才写用 NX;全部存在才写用 XX;保留各自原 TTL 用 KEEPTTL。 具体版本语义可参考 Redis MSETEX 官方文档。
GETEX key [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | PERSIST]在读取字符串的同时更新或移除其过期时间,适合滑动过期会话;这是带写入效果的命令,不适合需要严格只读的副本查询。
读取并刷新过期时间
需要实现“访问一次,会话再保留 300 秒”时使用 GETEX:它原子地读取字符串值并设置新的过期时间,避免把 GET 与 EXPIRE 拆成两条命令。适用于滑动过期的会话或缓存,但每次读取都会重新计算剩余寿命,而不是在旧 TTL 上累加。
基本语法
GETEX key [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | PERSIST]已有键必须是字符串类型;方括号中的过期策略最多选择一种。省略可选项时只读取值,原有 TTL 不变;不过 GETEX 整体仍被 Redis 归类为写命令。
关键选项
| 选项 | 效果 | 使用提醒 |
|---|---|---|
EX seconds |
从本次执行起设置秒级 TTL | 如 EX 300 表示重新倒计时 5 分钟 |
PX milliseconds |
设置毫秒级 TTL | 如 PX 1500 表示 1.5 秒 |
EXAT unix-time-seconds |
设置 Unix 秒级绝对过期时刻 | 传时间戳,不是持续秒数 |
PXAT unix-time-milliseconds |
设置 Unix 毫秒级绝对过期时刻 | 须确认单位是毫秒 |
PERSIST |
读取并移除过期时间 | 键将持续存在,直至被删除或重新设置过期时间 |
常用示例与预期结果
在测试 Redis 实例中执行以下命令,假设 redis-cli 已能连接到目标实例:
# 先创建一个 30 秒后过期的测试会话
redis-cli --raw SET demo:session:42 token-42 EX 30
# 读取值,并从本次访问起重新计时 300 秒
redis-cli --raw GETEX demo:session:42 EX 300
redis-cli --raw TTL demo:session:42预期输出(连续执行、无其他客户端修改该键时):
OK
token-42
300第三行是立即查询时的示意值,实际可能是 299 等略小的非负整数。再次执行 GETEX demo:session:42 EX 300 会再次重置 TTL,而非增加 300 秒。
返回值与检查
键存在且为字符串时返回原值;键不存在时返回空值,不会创建键。键类型不是字符串会报 WRONGTYPE。使用 TTL key 检查:正整数表示剩余秒数,-1 表示存在但无过期时间,-2 表示不存在;毫秒精度用 PTTL key。
风险与恢复
GETEX 自 Redis 6.2.0 可用,属于 @write ACL 类别;不能将它当作严格只读查询用于只读副本或仅有读取权限的账号。只想读值时用 GET。PERSIST 会意外取消自动清理;误用后可通过 EXPIRE demo:session:42 300 重新设置 300 秒 TTL,但无法凭这条命令恢复原到期时刻。
EXAT 或 PXAT 指向过去时,键可能立即过期并消失,需从业务源重新写入。执行前确认时间单位、目标键以及是否允许延长或缩短有效期;SET 初始化示例会覆盖同名测试键。
EXPIRE key seconds [NX | XX | GT | LT]为已有键设置秒级有效期,并可限制仅首次设置或仅延长缩短 TTL;适合补充缓存生命周期,键不存在时不会新建数据。
单独设置键过期
已有 Redis 键需要补充有效期、延长缓存生命周期或缩短过期时间时,使用 EXPIRE 设置秒级 TTL。命令不会创建不存在的键,成功返回 1;通过 NX、XX、GT、LT 可以限制何时允许修改过期时间,避免意外覆盖原有策略。
基本语法
EXPIRE key seconds [NX | XX | GT | LT]以上是 Redis 命令语法,在 redis-cli 交互终端中执行;在操作系统 Shell 中执行时,需要添加 redis-cli 前缀。
key:已存在的目标键,可以是字符串、哈希、列表、集合等 Redis 数据类型。seconds:以秒为单位的整数有效期,例如300表示从执行时起约 5 分钟后过期。- 可选条件:
NX、XX、GT、LT,同一次调用最多使用一种。
EXPIRE 修改的是整个键的过期时间,不会修改键中保存的数据,也不是针对哈希字段或列表元素单独设置有效期。
条件选项
| 选项 | 生效条件 | 典型用途 |
|---|---|---|
| 不指定 | 键存在,直接设置或覆盖 TTL | 普通缓存续期 |
NX |
键存在且尚无过期时间 | 只补充缺失的 TTL |
XX |
键存在且已经设置过期时间 | 只修改已有 TTL |
GT |
新过期时间晚于当前过期时间 | 只延长有效期 |
LT |
新过期时间早于当前过期时间 | 只缩短有效期 |
这里的 GT、LT 比较的是过期时间点,而不是比较两次命令中填写的秒数。对于已有 TTL 的键,执行时会将新有效期换算为新的过期时间点再比较。
没有过期时间的键在 GT、LT 比较中视为拥有无限 TTL。因此,GT 无法为这种键首次添加有限有效期,而 LT 可以。NX 与 XX 判断的是当前是否存在过期设置,并不检查历史上是否设置过 TTL。
常用示例与预期结果
前置条件:本机已有可连接的 Redis 服务,并安装 redis-cli。以下命令在操作系统 Shell 中执行,使用测试键 demo:session:42,会覆盖该键的原有内容;不要直接用于真实会话数据。
# 创建测试键,再设置 300 秒有效期
redis-cli --raw SET demo:session:42 active
redis-cli --raw EXPIRE demo:session:42 300
redis-cli --raw TTL demo:session:42
# 100 秒不能作为延长期限,但可以缩短现有 TTL
redis-cli --raw EXPIRE demo:session:42 100 GT
redis-cli --raw EXPIRE demo:session:42 100 LT
redis-cli --raw TTL demo:session:42预期输出(连续执行且耗时很短时的典型结果):
OK
1
300
0
1
100其中两个 TTL 结果是动态值,实际可能因执行耗时分别略低于 300 和 100,不能要求严格相等。更重要的验证点是:第一次 EXPIRE 返回 1,GT 返回 0,LT 返回 1,最后一次 TTL 应接近 100 秒。
如果希望只给未设置过期时间的键补充 300 秒 TTL,可以在 Redis 7.0 及以上使用 EXPIRE demo:session:42 300 NX。若该键已经有 TTL,则返回 0,不会覆盖原有过期时间。
返回值与状态检查
EXPIRE 的整数返回值与 TTL 的状态值含义不同,排查时应分别解读。
| 检查结果 | 含义 | 处理方式 |
|---|---|---|
EXPIRE 返回 1 |
已成功设置过期时间 | 使用 TTL 核对剩余时间 |
EXPIRE 返回 0 |
键不存在,或条件不满足 | 查询 EXISTS 和 TTL |
TTL 返回非负整数 |
剩余有效期,单位秒 | 判断是否符合预期 |
TTL 返回 -1 |
键存在,但没有过期时间 | 根据策略补充 TTL |
TTL 返回 -2 |
键不存在 | 检查键名或是否已过期 |
注意:EXPIRE 返回 1 不代表键一定还存在。例如将有效期设置为 0 或负数会使键立即删除。检查当前状态时,应以随后执行的 TTL、EXISTS 等命令为准。
风险与恢复
- 覆盖已有 TTL:不带条件的
EXPIRE会重新设置到期时间,可能意外延长或缩短数据生命周期。仅允许延长时使用GT,仅允许缩短时使用LT。 - 立即删除:
seconds为0或负数时,键会立即删除。已经删除的数据无法通过调整 TTL 恢复,需要依赖备份或业务数据源重新构建。 - 取消误设过期:如果键尚未过期,可以执行
PERSIST demo:session:42移除 TTL;返回1表示成功移除,随后TTL应返回-1。这会让键持续存在,恢复前应确认其原本是否应该有过期策略。 - 覆盖写入清除 TTL:普通
SET覆盖键值通常会清除现有过期时间。如果需要保留 TTL,Redis 6.0 及以上可使用SET key value KEEPTTL,或者在写入后重新设置有效期。 - 连接目标错误:生产环境执行前确认 Redis 地址、端口、数据库和键名;
redis-cli默认连接本机127.0.0.1:6379的数据库 0,实际连接参数可能不同。
速查:普通设置用 EXPIRE;只补充 TTL 用 NX;只修改已有 TTL 用 XX;只延长用 GT;只缩短用 LT。执行后使用 TTL key 验证,不要仅凭命令返回 1 推断剩余有效期。
TTL key读取指定键剩余的秒级生存时间,适合确认缓存是否意外失效;返回负值时要区分键不存在与没有设置过期时间,精细计时改用 PTTL。
检查键剩余寿命
当缓存提前失效、会话过期时间异常,或怀疑某个键没有设置有效期时,使用 TTL 查询剩余生存时间。该命令只读取过期状态,不会刷新有效期或修改键内容。
基本语法
redis-cli TTL demo:session:42预期结果:返回一个整数。若键已设置过期时间且尚未过期,返回非负的剩余秒数;若没有过期时间则返回 -1;若键不存在则返回 -2。
命令格式为 TTL key,其中 key 是待检查的 Redis 键名。命令没有额外选项,时间单位固定为秒,执行时间复杂度为 O(1)。
返回值判读
| 返回值 | 含义 | 排查方向 |
|---|---|---|
-2 |
键不存在或已经过期 | 检查键名、写入流程、过期与删除操作 |
-1 |
键存在,但没有设置过期时间 | 检查写入时是否遗漏过期参数 |
0 |
键仍存在,但剩余时间不足一秒 | 键即将过期,后续查询可能返回 -2 |
| 正整数 | 剩余生存时间,单位为秒 | 对照业务预期的缓存有效期 |
例如返回 45,表示查询时键大约还有 45 秒的生存时间。TTL 的结果不是固定的倒计时快照,多次执行可能得到不同数值。
可复现实验
前置条件:Redis 服务已经启动,redis-cli 能连接到目标实例。以下命令应在隔离的测试实例中执行,避免覆盖业务数据。
# 创建一个有效期为 60 秒的测试键
redis-cli SET demo:ttl:probe:42 active EX 60
redis-cli TTL demo:ttl:probe:42
# 取消过期时间,验证 -1
redis-cli PERSIST demo:ttl:probe:42
redis-cli TTL demo:ttl:probe:42
# 删除测试键,验证 -2
redis-cli DEL demo:ttl:probe:42
redis-cli TTL demo:ttl:probe:42预期结果:在 60 秒内连续执行时,各条命令依次返回:
OK
60
1
-1
1
-2其中 60 是理想的即时查询结果,实际可能是 59 或其他非负整数。PERSIST 返回 1 表示成功移除过期时间,DEL 返回 1 表示成功删除测试键。如果执行期间键已过期,相关命令的返回值也会改变。
排查过期异常
发现 TTL 返回 -1 时,应先检查键的写入方式。SET key value 默认会清除该键原有的过期时间;如果需要设置新有效期,可以使用 SET key value EX seconds,需要保留原有效期时可以使用支持 KEEPTTL 的 Redis 版本。
发现 TTL 返回 -2 时,不能直接认定是过期造成的。该返回值无法区分键从未创建、主动删除还是自然过期,需要结合应用写入记录、删除操作及业务日志进一步判断。
风险与恢复
TTL 是只读命令,可用于线上诊断,但不应为了观察倒计时而反复修改缓存寿命。
- 需要续期:确认业务允许后使用
EXPIRE key seconds重新设置有效期。 - 需要取消过期:使用
PERSIST key,注意这可能使缓存长期驻留。 - 键已经消失:
TTL无法恢复数据,应根据业务数据源重新构建缓存。
PERSIST key移除已有键上的过期时间,使其持续存在直到主动删除或被淘汰;适合将临时状态转为持久缓存,但需评估长期内存占用。
取消键过期设置
当 Redis 键原本设置了过期时间,但需要将其改为不自动过期时,使用 PERSIST 移除 TTL。命令不会改变键的值或数据类型,适合将临时缓存转为长期缓存。执行前应确认该键是否仍需要自动清理,避免会话失效或内存管理逻辑受到影响。
基本语法
PERSIST keykey:要移除过期时间的键名,必须指定一个键。- 命令只移除已有键的过期设置,不会创建键,也不会修改键值。
- 对没有过期时间的键执行命令不会产生实际变化。
PERSIST 是 Redis 原生命令。下面的终端示例使用 redis-cli 调用,默认连接本机 Redis 的 6379 端口和数据库 0;远程实例需要按实际环境配置连接参数。
常用示例与验证
先创建一个将在 300 秒后过期的测试键,再取消其过期设置,最后读取 TTL 确认状态。
# 创建带 300 秒过期时间的测试键
redis-cli SET demo:session:42 active EX 300
# 移除过期时间,保留原始键值
redis-cli PERSIST demo:session:42
# 检查键是否已经变为无过期时间
redis-cli TTL demo:session:42预期输出(依次对应三条命令):
OK
1
-1SET 返回 OK 表示写入成功;PERSIST 返回 1 表示成功移除了过期设置;TTL 返回 -1 表示键存在且没有过期时间。再次执行 PERSIST 将返回 0,因为该键已经没有可移除的过期设置。
返回值与异常判断
| 返回值 | 含义 | 后续处理 |
|---|---|---|
1 |
键存在,成功移除过期时间 | 使用 TTL 验证 |
0 |
键不存在,或者原本没有过期时间 | 使用 TTL 区分两种情况 |
当 PERSIST 返回 0 时,不能直接认定键不存在。可进一步检查 TTL key:
-1:键存在,但没有过期时间。-2:键不存在,可能已过期或被删除。- 非负整数:剩余过期时间,单位为秒;通常表示仍存在过期设置。
如果键在检查前已经自然过期,PERSIST 不会恢复其值;需要业务重新写入。权限不足或连接失败时,Redis 会返回相应错误,而不是正常的整数结果。
风险与恢复
对于登录会话、验证码、临时令牌和分布式锁等依赖 TTL 控制有效期的键,不应随意执行 PERSIST。取消过期时间可能造成会话长期有效、临时数据积压,或者破坏依赖超时释放的业务机制。
如果误取消过期时间,可通过 EXPIRE 重新设置。下面以重新设置 300 秒为例:
# 从当前执行时刻重新开始计算 300 秒有效期
redis-cli EXPIRE demo:session:42 300
redis-cli TTL demo:session:42预期结果:EXPIRE 返回 1 表示成功设置过期时间;随后 TTL 返回非负整数,通常接近 300,会随时间递减。如果键已经不存在,EXPIRE 返回 0,需要重新创建键。
速查:PERSIST key 返回 1 表示已移除过期时间,返回 0 时用 TTL 区分不存在与原本无过期设置;需要恢复自动过期时使用 EXPIRE。
INCR key将字符串整数计数器原子增加一,适合访问量、序号与轻量计数;不存在的键按零初始化,已有值不是可解析整数时会报错。
原子递增计数
需要记录访问次数、生成递增序号或维护轻量计数器时,使用 `INCR` 将指定键的整数值原子加一,并立即取得递增后的结果。多个客户端并发执行同一键的 `INCR` 不会发生普通读改写操作中的丢失更新。
基本语法
INCR key- `key`:计数器的 Redis 键名,例如 `demo:metrics:views`。
- 不存在的键视为整数 `0`,第一次递增返回 `1`。
- 已存在的键必须保存可解析为有符号 64 位整数的字符串值。
- 命令没有额外选项,每次固定增加 `1`;需要指定增量时使用 `INCRBY key increment`。
返回值与边界
成功时返回递增后的整数,而不是递增前的值。例如原值为 `41`,执行后返回 `42`,Redis 中保存的值也变为 `42`。
| 键的当前状态 | 执行结果 |
|---|---|
| 不存在 | 创建字符串计数器,返回 `1` |
| 值为 `41` | 更新为 `42`,返回 `42` |
| 值为 `-2` | 更新为 `-1`,返回 `-1` |
| 值为 `hello` | 返回整数解析错误,原值不变 |
| 键为 List 等非 String 类型 | 返回类型错误,原值不变 |
| 值为 `9223372036854775807` | 返回整数溢出错误,原值不变 |
有效整数范围为 `-9223372036854775808` 至 `9223372036854775807`。Redis 不会在达到最大值后自动从最小值重新计数。
常用示例与验证
前置条件:本机 Redis 服务正在运行,默认连接地址为 `127.0.0.1:6379`,且无需认证。以下使用独立演示键,避免修改真实业务计数器。
# 初始化演示键,确保结果可复现
redis-cli --raw SET demo:metrics:views:example 41
# 原子加一,再读取实际保存的值
redis-cli --raw INCR demo:metrics:views:example
redis-cli --raw GET demo:metrics:views:example
# 检查计数器是否设置过期时间
redis-cli --raw TTL demo:metrics:views:example预期输出:
OK
42
42
-1其中 `INCR` 返回 `42`,随后 `GET` 验证实际存储值为 `42`。`TTL` 返回 `-1` 表示键存在但没有过期时间。本例使用 `SET` 初始化,因而清除了该演示键可能已有的过期设置。
如果 Redis 不在默认地址或需要认证,应调整 `redis-cli` 的连接参数;认证信息不要直接写入共享脚本或命令历史。
过期时间与并发注意事项
`INCR` 不会刷新已有键的 TTL。原来剩余 30 秒的计数器递增后仍沿用原过期时间;不存在的键通过 `INCR` 创建时,默认没有过期时间。
按分钟统计访问量时,通常需要同时管理计数值与过期时间。直接连续执行 `INCR` 和 `EXPIRE` 是两条独立命令,客户端可能在两者之间断开连接。若要求首次创建和设置过期时间具有整体原子性,应使用 Redis Lua 脚本或服务端函数封装判断、递增和设置过期时间的逻辑。
风险与恢复
- **误操作业务键**:`INCR` 会真实修改计数。执行前确认键名、环境和业务命名空间,避免把演示命令用于生产键。
- **错误数据类型**:遇到整数解析错误或类型错误,先用 `TYPE key`、`GET key` 检查。非 String 类型不要使用 `GET` 读取,应采用对应类型的查询命令。
- **误增计数**:确认确实多执行了一次且业务允许补偿时,可使用 `DECR key` 减一。对于订单号、流水号等已经发放的序号,不应直接回退,以免产生重复编号。
- **整数溢出**:达到 64 位有符号整数上限后,`INCR` 会失败。需要更大范围或不同计数模型时,应重新设计数据表示,而不是依赖整数回绕。
速查:`INCR key` 返回加一后的值;不存在则从 `1` 开始,已有 TTL 保留,非整数、错误类型和溢出均会报错。
INCRBY key increment将整数计数器按指定增量原子调整,可使用负数实现扣减;适合库存候选计数与配额统计,但业务下界约束仍需另行保证。
按指定步长计数
需要把访问量、配额已用量或库存候选计数一次调整指定数量时,使用 INCRBY。命令将增量加到原值上,原子写回并返回更新后的整数。增量可以是负数,但命令本身不限制计数器的业务下界。
基本语法
INCRBY key incrementkey:Redis 字符串键,内容必须能解释为整数。键不存在时,以0为初始值执行运算,并创建该键。increment:有符号整数。5表示增加 5,-3表示减少 3,0表示增量为零。- 返回值:运算后的整数,而不是本次增加或减少的数量。
数值范围为有符号 64 位整数,即 -9223372036854775808 至 9223372036854775807。键类型不匹配、原值不是合法整数或计算结果溢出时,命令返回错误,该次调整不会生效。
INCRBY 的单次操作时间复杂度为 O(1),适合对同一个计数键进行频繁的整数累加。小数增量应使用 INCRBYFLOAT,不能直接交给 INCRBY。
常用示例与预期结果
前置条件:已安装 redis-cli,本地 Redis 服务正在运行且允许连接。以下使用独立测试键,先将计数设置为 10,再增加 5、减少 2,最后读取结果。初始键设置了 120 秒过期时间,避免测试数据长期残留。
# 使用独立测试键,避免修改正式业务计数
KEY=demo:metrics:views:incrby:example
redis-cli --raw SET "$KEY" 10 EX 120
redis-cli --raw INCRBY "$KEY" 5
redis-cli --raw INCRBY "$KEY" -2
redis-cli --raw GET "$KEY"预期输出(在 120 秒有效期内完成):
OK
15
13
13第一次 INCRBY 返回 15,第二次返回 13,最终 GET 也读取到 13。--raw 用于让 redis-cli 以简洁格式显示结果,不影响 Redis 内部数据类型或计算规则。
如果直接执行元数据中的 INCRBY demo:metrics:views 5,返回值取决于该键执行前的数值;不能假设一定返回 5。对于新建的计数键,首次增加 5 才会返回 5。
过期时间与计数边界
INCRBY 不会自动刷新已有键的过期时间。例如,测试键最初设置 EX 120,执行两次增减后仍沿用原来的过期截止时间,而不是每次重新获得 120 秒。
如果对不存在的键直接执行 INCRBY,新键默认没有过期时间。需要周期性清理的计数器,应在业务逻辑中明确设置过期策略,并处理初始化与并发写入之间的关系。
对于库存扣减,INCRBY stock:key -5 即使使库存变成负数也能成功,只要结果没有超出整数范围。因此它适合原子调整计数,却不能单独实现“库存必须大于等于零”的业务规则。
风险与恢复
- 并发下界约束:先
GET判断库存,再执行INCRBY,两个命令之间可能被其他请求修改。需要严格限制下界时,应通过 Lua 脚本将读取、比较和扣减作为一个原子操作执行。 - 重复请求:
INCRBY不具备请求幂等性,同一业务请求重复执行会重复累加或扣减。涉及订单、配额或库存时,应结合请求唯一标识和原子去重逻辑。 - 错误值类型:若键存储的是非整数字符串或其他 Redis 数据类型,命令会失败。排查时先确认键类型和原始值,不要为了消除错误直接覆盖业务数据。
- 误操作恢复:只有确认没有并发更新时,才能用相反增量抵消一次错误操作。例如误加
5后执行增量-5。存在并发业务写入时,应根据业务流水核对并修正实际计数,不能盲目回滚。
适用范围:Redis Open Source 1.0.0 及之后版本。命令参数及返回值可参考 Redis INCRBY 官方文档。
DEL key [key ...]同步移除指定键及其数据,适合明确的小型数据清理;删除大集合可能阻塞服务端,执行前应确认命名空间和目标键以防误删。
立即删除指定键
当缓存数据已失效、测试数据需要清理,或某个确定的键必须立即移除时,使用 DEL。命令会同步删除指定键及其关联数据,返回实际删除的键数。适合目标明确、数据规模可控的清理操作。
基本语法
DEL key [key ...]
key:必填,指定要删除的完整键名。[key ...]:可选,可继续指定多个键,使用空格分隔。- 返回值:整数,表示实际删除的键数,不存在的键不计入结果。
DEL 支持删除字符串、列表、集合、有序集合、哈希等类型的整个键,不需要事先判断数据类型。删除不存在的键不会报错,重复删除同一个键通常返回 0。
安全示例与预期结果
以下示例使用独立的 demo:del: 测试命名空间,在已启动 Redis、已安装 redis-cli 且允许本机连接的环境中执行。生产环境应先确认连接的实例、数据库编号和键名。
# 创建独立测试键,避免覆盖业务数据
redis-cli --raw SET demo:del:single temporary
redis-cli --raw EXISTS demo:del:single
# 同时删除存在和不存在的键
redis-cli --raw DEL demo:del:single demo:del:missing
redis-cli --raw EXISTS demo:del:single
# 再次删除,验证不存在的键不会重复计数
redis-cli --raw DEL demo:del:single预期输出(按命令执行顺序):
OK
1
1
0
0第一行表示测试键创建成功。第二行的 1 表示键存在;第三行的 1 表示两个目标中只有一个键被实际删除;第四行的 0 表示目标键已经不存在;最后一个 0 表示再次删除没有产生新的删除结果。
示例中的 --raw 用于输出简洁结果,不改变 Redis 命令的执行语义。未指定连接参数时,redis-cli 默认连接本机 Redis 的常用端口 6379、数据库 0,实际连接配置可能不同。
执行前检查
生产环境执行删除前,建议按照以下顺序核对:
- 确认 Redis 实例、连接地址和目标数据库,避免在错误环境中执行。
- 核对完整键名与业务命名空间,必要时先通过
TYPE key检查类型,通过EXISTS key检查存在性。 - 对重要数据确认已有可用备份,或确认业务可以从数据库、消息源等上游系统重建数据。
- 对大集合或批量删除任务评估执行耗时,必要时改用
UNLINK或分批处理。 - 执行后通过返回的删除数量与
EXISTS检查实际结果。
DEL 不会解析键名中的通配符。例如,DEL cache:* 不会自动删除所有以 cache: 开头的键,而是尝试删除名称恰好为 cache:* 的键。需要按模式清理时,应先使用 SCAN 分批发现目标键,再经过核对执行删除,避免直接使用 KEYS 扫描大型生产数据库。
同步删除与性能边界
DEL 会在命令执行过程中完成键的删除及相关内存释放工作。删除单个字符串键通常为 ;对于列表、集合、哈希和有序集合等容器,删除成本可能随容器元素数量增长。大对象删除可能导致 Redis 主线程出现明显延迟。
对于包含大量元素的键,可考虑使用 Redis 4.0 起提供的 UNLINK。它先从键空间中移除目标键,再将相关内存回收工作交给后台线程处理,通常能减轻大对象删除造成的主线程阻塞,但内存不会保证在命令返回时全部释放。
在 Redis Cluster 中,跨多个哈希槽的多键 DEL 可能因跨槽限制而失败。需要跨槽删除时,应按槽拆分操作,或对每个键分别执行删除。
风险与恢复
- 误删业务键:先停止相关清理任务,再根据已有备份或上游权威数据恢复。恢复前确认数据版本,避免旧备份覆盖更新的数据。
- 误删缓存键:如果业务支持缓存未命中回源,可通过正常读取请求重新填充缓存;注意集中回源可能增加后端负载。
- 执行后返回
0:检查键名、大小写、数据库和连接实例,也可能是键已过期或此前已经删除。 - 删除引起延迟升高:停止继续批量执行同步删除,检查慢日志及延迟指标,后续优先评估
UNLINK和分批清理。
速查:DEL 用于立即删除已明确确认的完整键;返回值是实际删除的键数。对于大对象,优先评估 UNLINK;对于重要数据,必须在删除前确认恢复来源。