Redis RPUSHX 命令详细教程RPUSHX将一个或多个元素追加到列表的表尾右侧与 RPUSH 的唯一区别是只有当 Key 已存在且持有列表时才执行推入Key 不存在时不创建、不报错静默返回0。它从 Redis 2.2.0 起提供4.0.0 起支持一次推入多个元素适合只更新、不新建的保护性写入场景。资料合集https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338一、概览与语法RPUSHX key element [element ...]项目说明数据类型List支持版本Redis 2.2.0 起4.0.0 起接受多个 elementkey目标列表 Key必须已存在element一个或多个要追加的元素按书写顺序依次追加到表尾返回值推入后的列表长度Key 不存在时返回 0时间复杂度每个元素 O(1)一次推 N 个为 O(N)ACLwrite、list、fast命令标记write、fast、denyoom官方说明当 key 已存在且持有列表时RPUSHX 将所有指定值插入到存储于 key 的列表尾部与 RPUSH 相反当 key 尚不存在时不执行任何操作。$TRAE_REF二、基础示例以下命令在测试实例的 redis-cli 中执行。文中结果是预期说明未实际连接 Redis 运行。示例沿用官方文档的数据与结果。DEL tutorial:{rpushx}:mylist tutorial:{rpushx}:myotherlist RPUSH tutorial:{rpushx}:mylist World RPUSHX tutorial:{rpushx}:mylist Hello RPUSHX tutorial:{rpushx}:myotherlist Hello LRANGE tutorial:{rpushx}:mylist 0 -1 EXISTS tutorial:{rpushx}:myotherlist预期结果RPUSH 返回1对已存在的 mylist 追加返回2对不存在的 myotherlist 追加返回0LRANGE 返回World、Hello参数顺序即列表顺序EXISTS 返回0确认 myotherlist 未被创建。三、与 RPUSH 的核心差异对比项RPUSHRPUSHXKey 存在且为列表追加并返回新长度追加并返回新长度Key 不存在先创建空列表再追加不创建返回 0副作用可能凭空产生新 Key无绝不新建 Key支持多元素2.4.0 起4.0.0 起这个差异决定了两者的适用面RPUSH 适合初始化与常规写入RPUSHX 把判断存在和追加合并成一次原子操作避免先 EXISTS 检查再 RPUSH这种两步流程在并发下产生的竞态。四、多元素推入顺序与 RPUSH 一致多个元素按参数顺序依次追加到表尾参数的书写顺序即最终列表顺序DEL tutorial:{rpushx}:order RPUSH tutorial:{rpushx}:order seed RPUSHX tutorial:{rpushx}:order a b c LRANGE tutorial:{rpushx}:order 0 -1预期结果RPUSHX 返回4LRANGE 返回seed、a、b、c。版本注意Redis 4.0 之前的 RPUSHX 每次只接受一个元素。五、Key 不存在与类型错误RPUSHX 返回0只有一种正常情形Key 当前不存在含刚被弹出最后一个元素而删除的情况。列表类型不会以空列表形式存在元素弹完 Key 即被删除。场景行为Key 不存在不创建返回 0Key 是其他类型报 WRONGTYPEKey 已存在且为列表追加返回新长度Key 设置过 TTL追加不清除过期时间到期仍会被删除SET tutorial:{rpushx}:str text RPUSHX tutorial:{rpushx}:str x预期结果对 String 类型执行报 WRONGTYPE类型检查先于任何写入。六、与相近命令的区别命令推入位置Key 不存在时支持多元素RPUSHX表尾右侧不创建返回 04.0.0 起RPUSH表尾右侧创建列表后推入2.4.0 起LPUSHX表头左侧不创建返回 04.0.0 起LPUSH表头左侧创建列表后推入2.4.0 起LINSERT指定 pivot 前后不创建返回 0不支持四个命令的分工很清晰普通命令负责有则推、无则建X 命令负责有则推、无则放弃。RPUSHX 与 LPUSHX 的区别仅在推入端前者追加到表尾后者插到表头。七、边界情况与错误处理场景行为未提供任何 element参数数量不足报语法错误element 为空字符串允许正常推入Key 不存在返回 0静默成功Key 类型不是 List报 WRONGTYPE返回值语义0 表示未推入Key 不存在正数表示推入后的长度RPUSHX tutorial:{rpushx}:err预期结果缺少元素参数报ERR wrong number of arguments for rpushx command。业务代码需要注意RPUSHX 返回 0 不是错误但通常意味着列表尚未初始化调用方应据此决定是否先执行初始化而不是把它当成失败重试。八、客户端示例前提为已安装 redis-py 并准备好本地测试实例。redis-py 的rpushx(name, *values)返回推入后的长度Key 不存在时返回 0。importredis rredis.Redis(hostlocalhost,port6379,decode_responsesTrue)keytutorial:{rpushx}:pytry:r.delete(key)print(r.rpushx(key,a,b,c))# 0Key 不存在不创建r.rpush(key,seed)print(r.rpushx(key,a,b,c))# 4print(r.lrange(key,0,-1))# [seed, a, b, c]finally:r.delete(key)r.close()JavaJedis示例rpushx同样支持可变参数try(JedisjedisnewJedis(localhost,6379)){Stringkeytutorial:{rpushx}:java;jedis.del(key);System.out.println(jedis.rpushx(key,a));// 0Key 不存在不创建jedis.rpush(key,seed);System.out.println(jedis.rpushx(key,a,b,c));// 4System.out.println(jedis.lrange(key,0,-1));// [seed, a, b, c]jedis.del(key);}九、原子性与使用注意事项检查与写入合一EXISTS key加RPUSH key x是两步流程中间可能被其他客户端删除 Key 或改变类型RPUSHX 把必须已存在作为前置条件在服务端一次性校验是天然原子的。TTL 不受影响对已设置过期时间的 Key 执行 RPUSHX 不会清除 TTL。若业务期望写入后重新计时需要显式重设 EXPIRE。Pipeline 与事务RPUSHX 可正常用于管道与 MULTI/EXEC返回值语义不变批量追加用管道减少网络往返。性能每个元素 O(1)只操作表尾与列表长度无关。十、典型业务场景保护性追加时序日志、审计流水、事件流等由专门的初始化逻辑写入元数据、设置 TTL创建 Key 后后续写入全部走 RPUSHX防止下游异常调用凭空造出没有 TTL、没有元数据的孤儿 Key。会话期流水用户会话存在才继续记录操作流水会话过期后自然停止追加无需额外判断。并发初始化保护多个服务实例同时写同一个列表时用 RPUSHX 保证谁负责创建、谁才能写入的语义清晰。追加已有集合的明细主记录存在才追加其明细项避免产生孤立明细。十一、练习、排错与总结练习新建tutorial:{rpushx}:ex1与tutorial:{rpushx}:ex2对不存在的 ex1 执行RPUSHX ex1 a确认返回0且 EXISTS 为0执行RPUSH ex1 seed后执行RPUSHX ex1 b c确认返回3且 LRANGE 得到seed,b,c用 SET 把 ex1 改成 String 后再 RPUSHX确认报 WRONGTYPE最后对 ex2 重复验证 Key 不存在时的静默行为。排错要点RPUSHX 返回 0 时先怀疑 Key 未初始化用 EXISTS、TYPE 确认本想初始化列表时不要误用 RPUSHX改用 RPUSH报 WRONGTYPE 时检查 Key 是否被 String 等类型占用老版本4.0 前报语法错误时检查是否使用了多元素写法追加顺序与预期不符时确认元素是否被追加到表尾RPUSHX 参数顺序即列表顺序。清理使用DEL tutorial:{rpushx}:mylist tutorial:{rpushx}:myotherlist tutorial:{rpushx}:order tutorial:{rpushx}:str tutorial:{rpushx}:py tutorial:{rpushx}:java tutorial:{rpushx}:ex1 tutorial:{rpushx}:ex2。速记2.2 起支持、4.0 起可推多个、只在 Key 已存在时追加到表尾、Key 不存在返回 0 且不创建、返回值为推入后的长度、不清除已有 TTL、与 RPUSH 的区别就在是否创建、X 系列命令都是有则推无则弃。