ZSCAN 是 Redis 为有序集合专门设计的增量迭代命令，与 SCAN 系列命令保持相同的游标机制。它的存在是为了解决直接使用 ZRANGE、ZRANGEBYSCORE 等命令遍历大集合时引发的服务端阻塞问题。当有序集合包含的元素数量达到百万级别时，ZRANGE 需要一次性将所有满足条件的元素连同分数返回，这不仅会消耗大量的网络带宽，还会导致 Redis 主线程长时间被占用，进而造成命令队列堆积、客户端超时。ZSCAN 则通过“一次只取一小批”的方式，将遍历拆解为多次请求，把压力平摊到多次交互中。
ZSCAN 命令的基本构成与参数含义
ZSCAN 命令的标准语法为：ZSCAN key cursor [MATCH pattern] [COUNT count]。第一个参数是键名，第二个参数是游标，第一次调用时游标必须设置为 0。返回结果是一个包含两个元素的数组：第一个元素是下一次遍历需要使用的游标值（字符串形式），第二个元素是一个数组，里面是本次迭代到的成员及其对应的分数，格式为 [member1, score1, member2, score2, ...]。
MATCH 选项用于对成员进行模式匹配，支持 glob 风格的通配符，例如 user:*、*2024 等。需要注意的是，MATCH 并不是在服务端对数据进行预先过滤，而是先将当前游标范围内的元素取出，再逐一比较成员名是否符合模式。因此，即使使用了 MATCH，每次调用返回的元素数量也可能远少于 COUNT 指定的数量，甚至可能为空，但游标仍然不会结束。COUNT 参数只是一个提示，告诉 Redis 每次迭代尽量返回多少个元素，Redis 并不会严格遵守，实际返回的数量可能会略多或略少，默认值为 10。
下面是一个简单的示例，假设有序集合 players 中存放了数万条玩家积分数据，我们想遍历所有成员名为 rank: 开头的元素：
# 第一次遍历 127.0.0.1:6379> ZSCAN players 0 MATCH rank:* COUNT 100 1) "2048" # 下一次遍历的游标 2) 1) "rank:1001" 2) "982" 3) "rank:1002" 4) "875" ...
如果返回的游标是 "0"，则表示整个集合已经遍历完毕。注意游标值是字符串，不能直接用来做数值比较，即使服务器返回 "2048"，它也可能并不是一个简单的整数偏移量，而是一种内部编码的状态标识。
游标的内部机制与迭代状态管理
ZSCAN 的游标并不是简单的数组下标或链表节点位置。Redis 使用了一种逆二进制迭代算法，游标值的变化与底层数据结构（压缩列表或跳表）无关，而是通过反转游标的二进制位并从高位向低位加一的方式，确保在 Rehash 过程中仍能完整遍历所有元素。这意味着遍历过程中即使有序集合因其他客户端指令发生了扩容或收缩，ZSCAN 也不会遗漏元素，但可能会返回重复元素。
重复元素的产生是 ZSCAN 去重问题的一大难点。因为游标算法本身不记录已返回元素的快照，如果遍历过程中有序集合发生了变化，比如删除了某些成员后又新增了其他成员，某些元素可能会在一次遍历中被多次返回。客户端必须自己具备去重能力，通常使用 Set 或本地字典来记录已处理的成员。不要试图通过 Redis 的某个命令自动去重，Redis 没有为 ZSCAN 提供去重保证。
COUNT 参数对迭代效率的影响也需要重点关注。如果 COUNT 值设得太小，可能需要数百次甚至上千次往返才能遍历完一个集合，网络延迟会显著拖慢整体耗时；反之如果 COUNT 设得过大，单次 ZSCAN 的执行时间变长，仍然可能对 Redis 性能造成短暂波动。比较合理的做法是，根据集合总大小和业务容忍度，将 COUNT 调整到每次返回 50~200 个元素左右，并搭配合理的 SLEEP 间隔，避免短时间内连续密集调用。
生产环境中的 ZSCAN 安全实践
很多开发者在使用 ZSCAN 时会忽略游标结束时返回 0 的判断逻辑，直接把返回的游标作为下一次调用的参数，却没有校验是否真的遍历完毕。正确的循环应该严格检查返回游标是否为字符串 "0"，而不是简单地依赖计数器或超时退出。同时，客户端必须设置超时时间，防止因为网络闪断导致无限等待。建议在循环体中使用 try-catch 捕获异常，并将当前游标保存下来，以便重试时能够继续，而不是从头开始。
对于带 MATCH 的遍历，可能会出现某次调用返回空数组但游标不为 0 的情况。这是完全正常的，因为 Redis 在内部扫描了一批元素但没有匹配到模式，此时应该继续使用返回的游标进行下一次调用，直到游标返回 "0"。千万不能在看到空数组时就认为遍历完成，这会导致只遍历了一部分元素就提前退出。
还需要注意的是 ZSCAN 的时间复杂度。虽然它是增量命令，但每次调用的时间复杂度仍然是 O(N)，N 为该次迭代实际扫描的元素数量，而非返回的元素数量。这是因为即使在遇到 MATCH 不匹配时，Redis 也已经从底层数据结构中取出元素做了比较。因此，集合越大，单次 ZSCAN 的开销仍然可能不小。建议对超大集合的遍历放在业务低峰期执行，并尽量通过业务设计减少全量遍历的需求，例如将数据拆分到多个较小的有序集合中，或者使用 Redis 的 Stream 作为事件驱动，避免周期性全量扫描。
ZSCAN 是处理大容量有序集合必备的工具，理解其游标语义和边界情况，才能构建出健壮的数据遍历模块。当遇到疑似 ZRANGE 阻塞告警时，优先考虑将同步遍历切换为 ZSCAN 渐进式加载，配合合理的 COUNT 参数和延时策略，可以在保障服务稳定性的同时完成数据批量处理任务。