在 Redis 中，HSCAN 命令用于增量地迭代（incrementally iterate）哈希（Hash）类型键中的字段（field）和值（value）。它非常适合在大型哈希表上进行遍历，避免因一次性获取所有数据而阻塞服务器。

基本语法

HSCAN key cursor [MATCH pattern] [COUNT count]

• key：要迭代的哈希键名。
• cursor：游标（cursor），用于表示迭代的位置。开始时使用 0，之后使用上一次返回的游标，直到返回 0 表示迭代完成。
• MATCH pattern（可选）：只返回匹配给定模式的字段名。
• COUNT count（可选）：建议每次返回的元素数量（只是一个提示，不是精确值）。

返回值

HSCAN 返回一个数组，包含两个元素：

1. 下一个游标（next cursor）：用于下一次调用的游标值。当为 0 时，表示迭代完成。
2. 字段-值对列表（field-value list）：当前批次返回的哈希字段和对应的值。

使用示例

假设有一个哈希键 user:1001，包含以下数据：

HSET user:1001 name Alice
HSET user:1001 age 30
HSET user:1001 city Beijing
HSET user:1001 email alice@example.com

1. 基本迭代

HSCAN user:1001 0

返回：

1) "0"
2) 1) "name"
   2) "Alice"
   3) "age"
   4) "30"
   5) "city"
   6) "Beijing"
   7) "email"
   8) "alice@example.com"

游标为 0，表示已迭代完成。

2. 使用 MATCH 模式匹配

只查找字段名以 e 结尾的项：

HSCAN user:1001 0 MATCH "*e"

可能返回：

1) "0"
2) 1) "name"
   2) "Alice"
   3) "email"
   4) "alice@example.com"

3. 使用 COUNT 控制返回数量

建议每次返回 2 个字段（实际可能更多或更少）：

HSCAN user:1001 0 COUNT 2

第一次返回：

1) "5"          # 下一个游标
2) 1) "name"    # 字段
   2) "Alice"
   3) "age"
   4) "30"

继续使用游标 5：

HSCAN user:1001 5 COUNT 2

第二次返回：

1) "0"
2) 1) "city"
   2) "Beijing"
   3) "email"
   4) "alice@example.com"

游标为 0，迭代结束。

注意事项

1. 非阻塞：HSCAN 是增量迭代，不会像 HGETALL 那样一次性加载所有数据，适合大数据量场景。
2. 可能重复：在迭代过程中如果哈希发生变化（如添加/删除字段），某些字段可能被重复返回。
3. 不保证顺序：返回的字段顺序是不确定的。
4. MATCH 模式：
   • * 匹配任意字符
   • ? 匹配单个字符
   • [abc] 匹配括号内的任意字符
5. COUNT 是提示：Redis 只是“建议”返回这么多元素，实际数量可能不同。

适用场景

• 遍历大型用户信息哈希表。
• 批量处理哈希中的某些字段（如清理过期字段）。
• 在不阻塞 Redis 的情况下进行数据导出或监控。

与其它 SCAN 命令对比

• SCAN：用于迭代整个键空间。
• SSCAN：用于迭代集合（Set）。
• ZSCAN：用于迭代有序集合（Sorted Set）。
• HSCAN：用于迭代哈希（Hash）。

它们都采用相同的游标机制，保证了 Redis 在大数据量下的稳定性。

✅ 总结：HSCAN 是安全、高效地遍历 Redis 哈希结构的推荐方式，尤其适用于生产环境中的大数据量场景。