Redis命令：BZPOPMIN

Redis BZPOPMIN 命令详细教程

BZPOPMIN 从多个有序集合中移除并返回分值最低的成员，若所有给定集合都为空则阻塞连接，直到有数据写入或超时。它从 Redis 5.0.0 起提供，复杂度为 O(log(N))，一次只弹出一个成员，返回三元组 [键名, 成员, 分值]。它和 BZPOPMAX 完全对称（只差取值方向），语义与 BLPOP 一致、只是数据结构不同，因此是"延迟任务到期处理""最低分优先消费"这类场景的经典工具。Redis 7.0 引入 BZMPOP 后，新代码更推荐 BZMPOP … MIN（支持 COUNT 批量弹出），但 BZPOPMIN 仍然可用、未被标记为弃用。

资料合集：https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338

一、概览与语法

BZPOPMIN key [key …] timeout

官方说明：从首个非空的有序集合中弹出分值最低的成员；全部为空时阻塞，直到有数据写入或 timeout 到期，超时返回 nil。多个 Key 按传入顺序依次检查。$TRAE_REF

参数顺序是 Key 在前、timeout 在最后，与 BZMPOP（timeout 在最前）相反，手写命令时最容易在这里出错。

二、基础示例

以下命令在测试实例的 redis-cli 中执行。文中结果是预期说明，未实际连接 Redis 运行。

DEL tutorial:{bzpopmin}:z1 tutorial:{bzpopmin}:z2
ZADD tutorial:{bzpopmin}:z1 1 "a" 2 "b" 3 "c"
BZPOPMIN tutorial:{bzpopmin}:z1 tutorial:{bzpopmin}:z2 1
BZPOPMIN tutorial:{bzpopmin}:z1 tutorial:{bzpopmin}:z2 1
EXISTS tutorial:{bzpopmin}:z1

预期结果：ZADD 返回 3；第一条返回三元组 1) "tutorial:{bzpopmin}:z1"、2) "a"、3) "1"；第二条返回 z1、b、2；EXISTS 返回 1（此时还剩 c）。

有数据时命令立即返回，示例里的 timeout 1 只是上限，并未真正等待。

阻塞路径需要一个空集合和较短超时：

DEL tutorial:{bzpopmin}:empty
BZPOPMIN tutorial:{bzpopmin}:empty 0.1

预期结果：等待约 0.1 秒后返回 (nil)。若 timeout 写 0，命令会一直挂起，直到其他客户端向该 Key 写入数据。

三、返回值结构

要点：

• 扁平三元组，不是嵌套结构（BZMPOP 返回的是 [key, [[member, score], …]]）。
• 分值以字符串返回，"1" 与 "1.0" 表示同一个数，直接做字符串比较会出错。
• 一次只返回一个成员，没有 COUNT 参数；需要批量请用 BZMPOP … MIN COUNT n 或 ZPOPMIN key count。
• 第一项是 Key 名，多队列场景据此分支处理。

四、timeout 与阻塞语义

超时链路要对齐：Redis 侧 timeout 建议略小于客户端 socket 读超时（如客户端 3 秒、Redis 2 秒）。否则客户端先断开而服务端仍在阻塞，客户端的连接池里会堆积"幽灵阻塞客户端"。

阻塞不烧 CPU：客户端被挂起在阻塞队列里，不空转，也不会影响其他客户端。但它独占一个连接，消费者数量多时连接池要单独规划。

FIFO 唤醒：多个客户端阻塞在同一批 Key 上，按进入阻塞的先后顺序被唤醒。

五、同分排序与"最低分"的定义

有序集合的排序规则是：先按分值升序，分值相同时按成员字节序升序。因此"分值最低的成员"在存在多个同分成员时，取的是其中字典序最小的那个。

DEL tutorial:{bzpopmin}:tie
ZADD tutorial:{bzpopmin}:tie 5 "b" 5 "a" 5 "c"
BZPOPMIN tutorial:{bzpopmin}:tie 1
BZPOPMIN tutorial:{bzpopmin}:tie 1

预期结果：第一条弹出 "a"（同分中字典序最小），第二条弹出 "b"，最后剩 "c"。

这意味着相同分值的弹出顺序与插入顺序无关。若业务要求"同优先级先进先出"，必须把时间戳或自增序号编入分值（例如 毫秒时间戳 + 序号/1000），不能依赖插入顺序。

六、多 Key 的检查顺序

Key 按参数顺序依次检查，命中的第一个非空集合就是数据来源：

DEL tutorial:{bzpopmin}:k1 tutorial:{bzpopmin}:k2
ZADD tutorial:{bzpopmin}:k2 5 "x" 6 "y"
BZPOPMIN tutorial:{bzpopmin}:k1 tutorial:{bzpopmin}:k2 1

预期结果：返回 tutorial:{bzpopmin}:k2、x、5。k1 不存在（视为空集合）被跳过。

顺序特性可用来表达优先级：高优先级队列放在前面，一次调用即实现"先高后低"的消费。注意每次调用都从第一个 Key 重新检查，这恰好符合优先级语义——只要前面的队列有数据，后面的队列就不会被消费。

集群限制：多个 Key 必须落在同一哈希槽，否则报 CROSSSLOT。用相同哈希标签（如 {delay}）可保证同槽，代价是这些队列集中在一个节点。

七、与相近命令的区别

DEL tutorial:{bzpopmin}:cmp
ZADD tutorial:{bzpopmin}:cmp 1 "p" 2 "q"
BZPOPMIN tutorial:{bzpopmin}:cmp 1
ZPOPMIN tutorial:{bzpopmin}:cmp

预期结果：BZPOPMIN 返回 [key, "p", "1"]；ZPOPMIN 返回 "q"、"2"（单 Key 操作，不含 Key 名，RESP2 下成员与分值平铺）。

选择要点：

• 要等数据、按最低分优先：BZPOPMIN（Redis 7.0+ 优先 BZMPOP … MIN）。
• 要一次弹多个：BZMPOP timeout numkeys key… MIN COUNT n。
• 不需要阻塞：ZPOPMIN/ZMPOP，不占连接。
• 只要按优先级排序、由客户端自行调度：直接用 ZRANGE … LIMIT 查看，再决定是否 ZREM（非原子，存在并发抢单风险）。

八、边界情况与错误处理

BZPOPMIN tutorial:{bzpopmin}:z1 -1
BZPOPMIN tutorial:{bzpopmin}:z1 abc
SET tutorial:{bzpopmin}:str text
BZPOPMIN tutorial:{bzpopmin}:str 0.1

预期结果：第一条因 timeout 为负报 ERR timeout is negative；第二条 timeout 非数字，报 ERR timeout is not a float or out of range；第三条对 String 类型报 WRONGTYPE（立即失败，不会阻塞）。

把 timeout 写在 Key 之前（BZPOPMIN 1 zset）会被解析成"Key 名为 1、timeout 为 zset"，从而报 timeout 非数字，容易误判为语法问题。

九、客户端示例

前提为已安装 redis-py 并准备好本地测试实例。redis-py 的签名是 bzpopmin(keys, timeout=0)，返回 (key, member, score) 元组，超时返回 None。

import redis

r = redis.Redis(host="localhost", port=6379, decode_responses=True)
k1 = "tutorial:{bzpopmin}:py1"
k2 = "tutorial:{bzpopmin}:py2"
try:
r.delete(k1, k2)
r.zadd(k1, {"a": 1, "b": 2, "c": 3})

print(r.bzpopmin([k1, k2], timeout=1)) # (k1, 'a', 1.0)，立即返回
print(r.bzpopmin([k1, k2], timeout=1)) # (k1, 'b', 2.0)
print(r.bzpopmin([k1, k2], timeout=1)) # (k1, 'c', 3.0)，集合被弹空后 Key 删除
print(r.bzpopmin([k1], timeout=0.2)) # None，等待 0.2 秒后超时
finally:
r.delete(k1, k2)
r.close()

Java（Jedis）示例，bzpopmin(double timeout, keys…) 在 Jedis 5 中返回 KeyValue<String, Tuple>（4.x 为 KeyedZSetElement，以所用版本为准）：

try (Jedis jedis = new Jedis("localhost", 6379)) {
String k1 = "tutorial:{bzpopmin}:java1";
String k2 = "tutorial:{bzpopmin}:java2";
jedis.del(k1, k2);
jedis.zadd(k1, 1.0, "a");
jedis.zadd(k1, 2.0, "b");

System.out.println(jedis.bzpopmin(1.0, k1, k2)); // KeyValue{key=k1, value=[a, 1.0]}
System.out.println(jedis.bzpopmin(1.0, k1, k2)); // KeyValue{key=k1, value=[b, 2.0]}
System.out.println(jedis.bzpopmin(0.2, k1)); // null，超时
jedis.del(k1, k2);
}

注意参数顺序差异：Jedis 的 bzpopmin(timeout, keys…) 把 timeout 放最前，而 Redis 协议里 timeout 在最后；redis-py 的 bzpopmin(keys, timeout) 与协议一致。

十、原子性与并发

单命令原子：选择集合、弹出成员、必要时删除空集合都在一条命令内完成。多个消费者并发阻塞时，同一个成员只会被一个客户端拿到。

阻塞不丢数据：成员在弹出时即写入复制流，客户端拿到响应前断线也不会回滚。对"绝不能丢"的任务队列，需要 ACK 机制（弹出后写入 processing 集合，处理完再删除）。

FIFO 唤醒：多个客户端阻塞在同一批 Key 上，按阻塞顺序依次被唤醒。

事务与脚本内退化为非阻塞：在 MULTI/EXEC 或 Lua 中不阻塞，空集合立即返回 nil，不能靠它实现"等有数据再处理"。

与 ZADD 并发：弹出与写入不会交错。消费者阻塞时，生产者一次 ZADD 多个成员，多消费者会按原子性依次拿到不同成员，不会重复消费。

十一、性能与使用注意事项

O(log(N))：从跳表头部取元素并删一个节点，与集合规模成对数关系，非常轻量。

阻塞占连接不占 CPU：连接池需按消费者数量预留，尤其是"每请求一个阻塞消费者"的架构容易打满连接。

timeout 0 是运维陷阱：永久阻塞的消费者下线后可能长期挂着，CLIENT LIST 中表现为 cmd=bzpopmin 且 b=1。生产建议有限超时 + 外层循环。

不要放进长 Pipeline：阻塞会让后续命令一起等待，Pipeline 的吞吐优势消失，还易触发客户端超时。

单条弹出意味着高往返：批量消费改用 BZMPOP … MIN COUNT n，或消费者内部用 ZPOPMIN key count。

监控 blocked_clients：突增通常说明生产端停止写入、消费者过多或 timeout 误设为 0。

同分顺序依赖成员名：严格要求 FIFO 时把时间戳/序号编入分值。

十二、典型业务场景

延迟任务队列：把"执行时间戳"作为分值写入，消费者用 BZPOPMIN 阻塞等待——但要注意它是"分值最小的先出"，不会自动等待到执行时间，必须在取到任务后比较当前时间，未到期则重新 ZADD 回去（或用 ZADD GT 保留较大分值）。这是该模式最容易被忽略的正确性细节。

超时订单/会话回收：过期时间作为分值，定期 BZPOPMIN 取出已到期项处理。

最低价优先撮合：卖盘按最低售价存分值，买方用 BZPOPMIN 阻塞取最优卖价。

降级淘汰：分数越低优先级越低的缓存项，按最低分批量淘汰（配合 BZMPOP … MIN COUNT n）。

定时轮询调度：多个队列按参数顺序表达优先级，最低分代表最紧急任务。

限流令牌回收：令牌到期时间作为分值，BZPOPMIN 逐个回收过期令牌。