如何基于Spring Data Redis实现Redis哈希缓存的分页查询

刚好做过类似的需求，我来给你拆解一下实现思路。首先得明确：Spring Data Redis的HashOperations本身并没有直接提供分页查询的API，因为Redis的Hash结构本身是无序的（或者说没有内置的排序分页机制），所以我们需要借助Redis的HSCAN命令来实现，或者根据场景优化成更高效的方案。

方案一：基于HSCAN的基础分页（适合小数据量） #

如果你的Hash数据量不算特别大（比如几万条以内），直接用HSCAN迭代结合游标来实现分页是最直接的方式，不需要额外维护其他数据结构。

具体实现代码 #

首先你需要注入RedisTemplate（因为HashOperations没有暴露scan的游标操作，得通过RedisTemplate来调用）：

@Autowired
private RedisTemplate<String, Object> redisTemplate;

然后写分页查询方法：

public List<SomeObject> getHashPage(String hashKey, int pageNum, int pageSize) {
    // 计算需要跳过的元素数量：(页码-1)*每页大小
    long skipCount = (long) (pageNum - 1) * pageSize;
    long currentCount = 0;
    List<SomeObject> pageData = new ArrayList<>(pageSize);

    // 配置Scan选项：count参数是给Redis的提示，让它尽量返回足够的元素
    ScanOptions scanOptions = ScanOptions.scanOptions()
            .count(skipCount + pageSize)
            .build();

    // 获取Hash的迭代游标
    Cursor<Map.Entry<Long, SomeObject>> cursor = redisTemplate.opsForHash().scan(hashKey, scanOptions);

    try {
        while (cursor.hasNext()) {
            Map.Entry<Long, SomeObject> entry = cursor.next();
            // 跳过前面的元素，只收集当前页的内容
            if (currentCount >= skipCount) {
                pageData.add(entry.getValue());
                // 收集够一页就停止遍历
                if (pageData.size() == pageSize) {
                    break;
                }
            }
            currentCount++;
        }
    } catch (Exception e) {
        // 这里可以根据业务做异常处理，比如打日志
        log.error("分页查询Redis Hash失败", e);
    } finally {
        // 务必关闭游标，避免资源泄漏
        if (cursor != null) {
            try {
                cursor.close();
            } catch (IOException e) {
                log.error("关闭Redis游标失败", e);
            }
        }
    }

    return pageData;
}

注意点 #

• ScanOptions.count()只是Redis的一个提示参数，不是严格限制返回数量，所以实际返回的元素可能比设置的多，不过我们在遍历的时候自己做截断就好；
• 这种方式每次分页都需要从头开始扫描Hash，数据量大的时候效率会下降，所以适合小数据量场景。

方案二：结合ZSet实现高效分页（适合大数据量） #

如果你的Hash数据量很大，或者分页查询很频繁，上面的扫描方式就不够高效了。这时候可以额外维护一个ZSet来记录Hash的field顺序，通过ZSet的有序性来快速定位分页的field，再从Hash中批量获取value。

步骤1：存入数据时同步维护ZSet #

当你往Hash中存数据的时候，同时把field存入ZSet，用一个有序的score（比如插入时间戳、自增ID）来保证顺序：

@Autowired
private HashOperations<String, Long, Object> hashOperations;
@Autowired
private ZSetOperations<String, Long> zSetOperations;

public void saveToHash(Long field, SomeObject obj) {
    String hashKey = "Key";
    String zSetKey = "Key:fieldOrder";
    
    // 存入Hash
    hashOperations.put(hashKey, field, obj);
    // 存入ZSet，用当前时间戳作为score，保证新数据排在后面（如果需要倒序可以用负的时间戳）
    zSetOperations.add(zSetKey, field, System.currentTimeMillis());
}

步骤2：分页查询时先从ZSet取field，再批量查Hash #

public List<SomeObject> getHashPageWithZSet(String hashKey, String zSetKey, int pageNum, int pageSize) {
    long start = (long) (pageNum - 1) * pageSize;
    long end = start + pageSize - 1;

    // 从ZSet中获取当前页的field集合
    Set<Long> targetFields = zSetOperations.range(zSetKey, start, end);
    if (targetFields == null || targetFields.isEmpty()) {
        return Collections.emptyList();
    }

    // 批量从Hash中获取对应的value
    List<Object> values = hashOperations.multiGet(hashKey, targetFields);
    
    // 转换为目标类型，同时过滤可能的null值（比如field已被删除但ZSet没同步的情况）
    return values.stream()
            .filter(Objects::nonNull)
            .map(val -> (SomeObject) val)
            .collect(Collectors.toList());
}

优势 #

• ZSet的range操作时间复杂度是O(logN + K)，N是ZSet元素总数，K是当前页的元素数，效率非常高；
• 分页查询不需要从头扫描Hash，适合大数据量和高频分页场景。

注意点 #

• 需要保证ZSet和Hash的数据一致性，比如删除Hash中的field时，也要同步删除ZSet中的对应member；
• 如果需要按其他维度排序（比如字段值排序），可以把对应的字段值作为ZSet的score存入，不过要注意score的唯一性问题（如果有相同score，Redis会按member字典序排序）。

内容的提问来源于stack exchange，提问作者TheNightsWatch