*Redis HSCAN 命令

以游标方式分批遍历 Hash 中的 field-value 对。

*语法

HSCAN key cursor [MATCH pattern] [COUNT count]

*参数说明

参数	类型	必填	说明
key	String	是	Hash 的键名
cursor	Integer	是	游标，首次为 0
MATCH	String	否	匹配 field 名，glob 风格
COUNT	Integer	否	每次扫描提示数量，默认 10

*返回值

返回 [next_cursor, [field1, value1, field2, value2, ...]]。

*时间复杂度

O(1) 每次调用 + O(N) 返回 N 个元素。单步不阻塞。

*示例

> HSET user:1001 name Alice age 30 city Beijing email alice@test.com
(integer) 4

> HSCAN user:1001 0
1) "0"
2) 1) "name"
   2) "Alice"
   3) "age"
   4) "30"
   5) "city"
   6) "Beijing"
   7) "email"
   8) "alice@test.com"

# 带 MATCH
> HSCAN user:1001 0 MATCH a*
1) "0"
2) 1) "age"
   2) "30"

*常见错误

对非 Hash 使用：返回 WRONGTYPE。
游标理解错误：同 SCAN，游标非递增，必须用上一次返回值。

*最佳实践

大 Hash 替代 HGETALL：field > 5000 时，用 HSCAN 分批读取，避免阻塞。
过滤遍历：MATCH 过滤 field 名，但过滤是在返回前做的，COUNT 提示的是扫描数量不是返回数量。

*FAQ

Q: HSCAN 会返回重复的 field 吗？ A: 完整遍历中可能返回重复，业务层需去重或幂等处理。

Q: HSCAN 遍历期间 Hash 被修改？ A: 可能遗漏或重复，但不影响绝大多数场景。