RedisSCAN游标解读：如何理解和使用返回值
Redis SCAN 游标解读：如何理解和使用返回值
Redis 的 SCAN 命令及其衍生命令（HSCAN、SSCAN、ZSCAN）提供了一种增量迭代 Redis 键空间（或集合/哈希/有序集合的元素）的方法，避免了 KEYS 命令可能导致的阻塞。SCAN 的核心在于使用游标（cursor）来跟踪迭代状态，理解游标和 SCAN 的返回值是正确使用它的关键。
1. SCAN 命令的基本语法和返回值
SCAN 命令的基本语法如下：
SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]
cursor: 游标，一个整数值。第一次迭代时，游标应设置为 0。Redis 会在每次迭代后返回一个新的游标，用于下一次迭代。当游标返回 0 时，表示迭代完成。MATCH pattern: 可选参数，用于指定匹配的键的模式，支持glob-style模式匹配（例如*,?,[]）。COUNT count: 可选参数，用于指定每次迭代返回的键的数量的提示。Redis 不保证每次都精确返回count个键，这只是一个提示。TYPE type: (Redis >= 6.0) 可选参数，过滤指定数据类型的键。例如，TYPE string只扫描字符串类型的键。
SCAN 命令的返回值是一个包含两个元素的数组：
- 下一个游标的值 (字符串)：用于下一次迭代的游标。如果这个值为 "0"，表示迭代完成。
- 键的数组 (数组)：本次迭代返回的键的列表。这个数组可能为空，即使游标不为 0。
2. 理解游标的含义
游标并非简单的线性递增的整数。它是 Redis 内部用于跟踪迭代状态的一个标识符。 它与 Redis 内部的哈希表结构和 rehash 过程密切相关。
- 非线性递增: 游标值可能看起来是随机的，并且不保证是递增的。你不能依赖于游标值的顺序来推断键的存储顺序或任何其他信息。
- 无状态的迭代器: Redis 服务器本身不保存任何关于
SCAN迭代的客户端状态。所有的状态都包含在游标中。这意味着你可以随时停止和恢复SCAN迭代，只需要使用上次返回的游标即可。 - 可能返回重复的键: 在迭代过程中，如果 Redis 进行了 rehash（哈希表大小调整），可能会导致某些键被重复返回。这是因为 rehash 可能会改变键在哈希表中的位置，导致
SCAN在不同的哈希表桶中扫描到同一个键。 - 不保证返回所有键, 除非完整迭代: 在迭代未完成时（游标不为0），
SCAN不保证能返回所有匹配的键。 只有当完整迭代 (游标回到 0) 后，才能保证所有匹配的键都至少被返回过一次 (可能多次)。 - COUNT只是提示:
COUNT参数仅仅是给 Redis 的一个提示，告诉它每次迭代大概希望返回多少个键。Redis 不保证每次迭代返回的键的数量正好等于COUNT。在键的数量很少或者哈希表比较稀疏的情况下，Redis 可能会返回少于COUNT个键，甚至可能返回空数组。
3. 为什么游标不是简单的线性递增？
为了理解这一点，我们需要稍微了解一下 Redis 哈希表的实现。Redis 使用哈希表来存储键值对。哈希表由多个桶（bucket）组成，每个桶可以存储多个键值对（使用链表或其他数据结构解决哈希冲突）。
当 Redis 需要扩展哈希表时（例如，当键的数量增加到一定程度时），它会执行 rehash 操作。Rehash 会创建一个更大的哈希表，并将旧哈希表中的键值对逐步迁移到新哈希表中。
SCAN 命令在迭代过程中可能会遇到 rehash 操作。如果 SCAN 使用简单的线性递增的游标，那么在 rehash 期间，它可能会丢失一些键或重复扫描一些键。
为了解决这个问题，Redis 使用了一种特殊的游标算法，称为反向二进制迭代（Reverse Binary Iteration）。这种算法可以保证在 rehash 期间，SCAN 仍然能够遍历所有键，并且尽可能减少重复扫描的次数。 简单来说，它不是按照桶的物理顺序(0,1,2,3...)扫描，而是一种特殊的二进制位反转的顺序。
4. SCAN 衍生命令 (HSCAN, SSCAN, ZSCAN)
除了 SCAN 用于迭代所有键，Redis 还提供了针对特定数据结构的衍生命令：
HSCAN: 用于迭代哈希表中的字段和值。SSCAN: 用于迭代集合中的元素。ZSCAN: 用于迭代有序集合中的成员和分数。
这些命令的语法和返回值与 SCAN 类似，只是迭代的对象不同。
HSCAN返回的是字段-值对的数组。SSCAN返回的是集合元素的数组。ZSCAN返回的是成员-分数对的数组。
5. 如何正确使用 SCAN 命令
以下是一个使用 Python 和 redis-py 库进行 SCAN 迭代的示例：
```python
import redis
r = redis.Redis(host='localhost', port=6379)
cursor = '0' # 初始游标为 '0'
while cursor != '0':
cursor, keys = r.scan(cursor=cursor, match='prefix:*', count=100)
for key in keys:
# 处理每个键
print(key)
print("Iteration complete.")
```
关键点：
- 初始化游标: 第一次迭代时，游标必须设置为
'0'（字符串形式的零，而不是整数 0）。 - 循环迭代: 使用
while循环，直到返回的游标为'0'。 - 处理返回值:
scan返回的是一个元组, 第一个元素是下一次迭代的游标(字符串), 第二个元素是本次迭代返回的键的列表(list). - 处理重复键 (可选): 如果需要确保每个键只被处理一次，可以在应用层进行去重（例如，使用集合或字典）。
- MATCH的效率: 尽量减少全量
*匹配, 使用更精确的前缀匹配可以显著提高效率.
6. 总结
SCAN 命令及其衍生命令是 Redis 中进行键空间迭代的重要工具。理解游标的含义和 SCAN 的返回值对于正确使用这些命令至关重要。记住以下几点：
- 游标是用于跟踪迭代状态的标识符，不是简单的线性递增的整数。
SCAN不保证每次返回的键的数量，也不保证在迭代过程中不返回重复的键。- 只有当游标返回 0 时，才表示迭代完成。
- 在应用层处理重复键（如果需要）。
- 使用合适的
MATCH模式和COUNT值来优化性能.
通过正确理解和使用 SCAN，你可以安全高效地处理大型 Redis 数据集，避免 KEYS 命令带来的阻塞风险。