Redis HSCAN 如何渐进清理大 Hash：COUNT 提示、游标归零与删除风险

线上缓存里有一个持续变大的 Hash，直接执行 HGETALL 会把整份字段和值一次性搬到客户端，清理任务很容易把 Redis 延迟和应用内存一起推高。更稳妥的做法是让 HSCAN 按游标渐进遍历，每次只拿一小批候选字段，再用 HDEL 删除已经确认过期的字段。

HSCAN 的 COUNT 只是本轮返回数量的提示，不是严格分页大小；真正的结束标志是 Redis 返回的游标变回 0。清理时应按批收集字段、核对业务条件后调用 HDEL，不要把一次扫描结果当成全量快照。

为什么大 Hash 不该用 HGETALL 清理

假设订单摘要被放在 order:summary 这个 Hash 中，字段名是订单号，值里保存状态和更新时间。HGETALL order:summary 会把所有字段和值都返回；Hash 越大，单次响应越重，客户端还要额外分配一份结果空间。

HSCAN order:summary 0 COUNT 100 返回两部分：新的游标和本轮字段列表。它适合把一次长任务拆成多次短调用。这里的“渐进”不等于严格快照，扫描期间如果业务继续写入，清理器必须接受集合会发生变化。

HSCAN 的游标、MATCH 与 COUNT 怎么配合

下面这段 Redis CLI 片段只做遍历，不直接删除字段。先观察返回格式，再决定清理条件，能避免把误命中的字段直接删掉。

HSCAN order:summary 0 MATCH order:* COUNT 100
HSCAN order:summary 18432 MATCH order:* COUNT 100
HSCAN order:summary 0 MATCH order:* COUNT 100

第二个位置是游标，下一次调用要原样带上 Redis 返回的值。最后一次返回游标 0，也就是图中的“游标0”，才说明本轮从头到尾走完。即使 COUNT 100 写得很明确，Redis 也可能返回少于或多于这个数量，因此程序不能用“返回数量小于100”判断结束。

用 MATCH 缩小候选，不要把它当成索引

MATCH order:* 是对扫描结果做模式过滤，不会把 Hash 变成按字段名定位的索引。字段命名稳定时它很有用，但清理任务仍然要完整走完游标；如果只扫描一次，留下的字段可能正好在后续游标范围里。

按批确认过期字段，再调用 HDEL

真正的删除边界在业务判断，而不是 HSCAN 本身。下面示例约定 Hash 值保存 JSON，清理器先解析 expires_at，只把已经过期的字段放入 expired_fields，然后分批调用 HDEL。

cursor = "0"
while True:
    cursor, pairs = redis.hscan(
        "order:summary", cursor=cursor, match="order:*", count=100
    )
    expired_fields = []
    for field, value in pairs.items():
        if is_expired(value):
            expired_fields.append(field)
    if expired_fields:
        redis.hdel("order:summary", *expired_fields)
    if cursor == "0":
        break

这里有两个容易漏掉的点：第一，cursor 必须来自本次响应，不能自行递增；第二，HDEL 的返回值是实际删除的字段数量，不存在的字段不会计数。清理器可以记录“发现数量”和“删除数量”两个指标，二者不相等时再检查并发写入或重复扫描。

并发写入时，为什么还要复查

扫描与删除不是一个业务事务。扫描后，订单服务可能更新同一个字段；如果值里的版本或更新时间已经变化，清理器应该在加入 expired_fields 前再次核对，必要时把“发现过期”与“执行删除”之间的间隔压缩到一个小批次内。

如果业务对“不能删掉刚更新的字段”要求很高，可以把版本条件放进 Lua 脚本中做原子校验；但这会改变文章里的简单清理路径，脚本还需要严格限制访问的 Hash 键和单批字段数量。不要仅因为看到并发，就把所有清理逻辑改成一个超大脚本。

游标归零后如何验收清理结果

一轮任务结束时，至少记录 Hash 键、扫描轮次、发现字段数、HDEL 返回总数和最后游标。可用下面的检查确认键是否仍存在：

HLEN order:summary
EXISTS order:summary

如果最后一批删除了 Hash 中剩余的全部字段，Redis 会删除这个 Hash，EXISTS order:summary 会返回 0。这不是异常；需要保留空容器时，应由业务明确决定是否写入占位字段，而不是依赖清理任务偷偷保留。

三个最容易误判的边界

• 把 COUNT 当硬上限：它是提示值，不能用来推断结束，也不能据此精确估算每轮耗时。
• 只调用一次 HSCAN：一次返回只是一个游标片段，必须循环直到游标归零。
• 用发现数量代替删除数量：并发更新、重复清理或字段已不存在时，HDEL 返回值可能更小。

相关问答

HSCAN 会阻塞 Redis 很久吗？

单次调用的工作量通常较小，但完整遍历仍与 Hash 大小相关。把 COUNT 调得很大并不能免费获得更快速度，应该结合实例延迟和清理窗口调整。

HSCAN 返回空字段就能结束吗？

不能。返回列表为空不代表遍历结束，只有游标回到 0 才能结束这一轮。

HDEL 删除不存在的字段会报错吗？

不会。不存在的字段不计入删除数量；如果 Hash 也不存在，返回值为 0。

小结

大 Hash 清理的核心是把“遍历”和“删除”拆开：HSCAN 负责带着游标找候选字段，业务逻辑确认 expires_at 后，再用小批量 HDEL 完成删除。把游标归零作为结束条件，把 COUNT 当作提示，把发现数和删除数分开记录，清理任务才更容易在并发写入下复查和回滚。