Redis ZSET实现延迟队列并控制重复任务的做法

Redis ZSET 做延迟队列时，建议把“什么时候可以取”放在 score，把业务任务 ID 放在 member，再用一条长期保留的幂等记录限制重复入队。领取阶段不要先查后删，而是用 Lua 在 Redis 内一次完成“取出到期成员并移除”；任务处理则用租约和重试时间重新排队。这样既能按时间取任务，也能把重复入队、重复执行、消费者崩溃三个问题分开处理。

Redis 官方地址：https://redis.io/docs/latest/

先把延迟队列拆成三个数据对象

一个可维护的实现至少需要三个对象：delay:payment:ready 是 ZSET，score 记录任务可执行的 Unix 秒数；task:payment:1001 是任务内容和状态；dedupe:payment:order-1001 是业务去重记录。不要把完整 JSON 直接塞进 ZSET member，否则更新内容、记录重试次数和清理敏感字段都会变得困难。

用 ZADD NX 控制入队重复，再补一层业务幂等

写入时先使用稳定的业务任务 ID，例如订单号加动作类型，而不是每次请求都生成随机 UUID。下面的命令用 NX 保证当前待执行集合已有同名 member 时不更新 score；幂等键则让任务已经被领取、删除后，重复请求仍能被识别。

# 业务幂等键保留到业务允许重试的最长时间
redis-cli SET dedupe:payment:order-1001 1 NX EX 86400

# 只有首次写入成功才把任务放入延迟集合；score 是可执行时间
redis-cli ZADD delay:payment:ready NX 1789871400 payment:order-1001

# 读取任务内容，避免把大 payload 混在 ZSET member 中
redis-cli HSET task:payment:1001 status pending attempt 0 payload '{"order_id":"1001"}'

这三条命令在示例中是分开写的，生产代码应把“幂等键成功”和“任务写入”放在同一个 Lua 脚本或事务边界里，否则客户端在两条命令之间断线，可能留下幂等键却没有队列成员。需要允许重新安排同一任务时，不要简单删除幂等键，而是明确区分业务任务 ID、重试轮次和可重复执行的动作。

用原子领取避免多个消费者拿到同一个到期任务

消费者只取 score 小于等于当前时间的成员，并限制每批数量。Redis 6.2 以后可以用 ZRANGE key min max BYSCORE 表达按分数查询；真正领取时，应在同一个 Lua 脚本内查询、删除并给任务写入租约。单独执行“先 ZRANGE、再 ZREM”会留下并发窗口。

-- 在 Redis 内一次完成取数和移除，避免两个消费者看到同一批任务
local ids = redis.call('ZRANGE', KEYS[1], '-inf', ARGV[1], 'BYSCORE', 'LIMIT', 0, ARGV[2])
for _, id in ipairs(ids) do
  -- 只有移除成功才把任务交给当前消费者
  if redis.call('ZREM', KEYS[1], id) == 1 then
    redis.call('HSET', 'task:payment:' .. id, 'status', 'processing', 'lease_until', ARGV[3])
  end
end
return ids

示例中的 ARGV[1] 是当前时间，ARGV[2] 是批量上限，ARGV[3] 是租约截止时间。脚本返回任务 ID 后，应用再读取对应 Hash 并执行业务动作。租约不是成功标记：只有业务动作完成且幂等写入成功，才把状态改成 done；否则要按失败原因重新设置 score。

失败重排要有租约、退避和死信边界

消费者拿到任务后，如果进程崩溃，任务已经从 ready ZSET 删除，必须由租约扫描器找出 lease_until 且仍为 processing 的任务，再把它按退避时间放回 ZSET。重试次数应写在 Hash 中，超过上限就转为 dead 状态并保留错误摘要，不能让失败任务在每次扫描时立即重排。

# 重试任务使用未来时间，避免故障期间形成紧密重试风暴
redis-cli ZADD delay:payment:ready NX 1789871520 payment:order-1001

# 业务完成后保留结果状态；DEL 只适用于明确允许再次创建的临时任务
redis-cli HSET task:payment:1001 status done attempt 1 finished_at 1789871500

还要注意三个时间问题：所有生产节点使用同步后的 Unix 时间；score 只表示“最早可执行时间”，不代表任务一定在这一秒完成；同一个 score 下不同 member 会按字典序排列，不能把它当成严格的提交顺序。

上线前检查重复任务和延迟漂移

验证时不要只看 ZCARD。至少抽查同一业务号的幂等键、任务 Hash 状态和 ZSET 成员是否一致，并记录领取延迟、处理耗时、重试次数和死信数量。一个简短的排查表如下：

常见问题

ZSET 能不能单独保证任务只执行一次？

不能。ZSET 能保证 member 在集合中唯一，但任务出队后仍可能因超时、重试或客户端重复提交再次执行。一次性执行要靠业务幂等键、状态机或数据库唯一约束共同完成。

为什么不直接使用 Redis List 做延迟队列？

List 适合先进先出，但不擅长按未来时间筛选任务。ZSET 可以用 score 表示到期时间，并按分数范围取出到期成员，更适合延迟任务；如果还需要消息确认和消费组语义，应评估 Redis Streams。

领取后处理时间超过租约怎么办？

为长任务续租，或把租约设计成可检测的任务令牌。不要只延长固定 TTL，否则旧消费者恢复后可能与新消费者同时提交结果，最终仍要由业务幂等判断胜负。