RedisUtil 使用文档

基础操作

1. 设置过期时间 `expire(String key, long time)`

设置指定键的过期时间。

// 设置键"user:123"在3600秒后过期
boolean result = redisUtil.expire("user:123", 3600);
// time必须大于0，否则不设置过期时间

约定：

time 必须大于 0，否则不设置过期时间
如果设置过程中发生异常，返回 false

2. 获取过期时间 `getExpire(String key)`

获取指定键的剩余过期时间。

// 获取键"user:123"的剩余过期时间
long ttl = redisUtil.getExpire("user:123");
// 返回值单位：秒

返回值说明：

> 0: 剩余过期时间（秒）
-1: 键存在但没有设置过期时间（永久有效）
-2: 键不存在或已过期

3. 判断键是否存在 `hasKey(String key)`

判断缓存中是否存在指定的键。

// 检查键"user:123"是否存在
boolean exists = redisUtil.hasKey("user:123");
if (exists) {
    System.out.println("键存在");
}

4. 删除键 `del(String... key)`

删除一个或多个键。

// 删除单个键
redisUtil.del("user:123");

// 删除多个键
redisUtil.del("user:123", "user:456", "user:789");

String 操作

1. 获取值 `get(String key)`

获取指定键的值。

// 获取键"user:123"的值
Object value = redisUtil.get("user:123");
// 如果键不存在或key为null，返回null

2. 设置值 `set(String key, Object value)`

存储键值对，永久有效。

// 存储字符串
redisUtil.set("username", "zhangsan");

// 存储对象
User user = new User("zhangsan", 25);
redisUtil.set("user:123", user);

3. 设置值并设置过期时间 `set(String key, Object value, long time)`

存储键值对并设置过期时间。

// 存储60秒后过期
redisUtil.set("verificationCode", "123456", 60);

// 存储1小时后过期（3600秒）
redisUtil.set("token", "abc123xyz", 3600);

约定：

time > 0: 设置过期时间
time <= 0: 永久有效

4. 递增 `incr(String key, long delta)`

将指定键的值递增指定增量。

// 自增1
long count = redisUtil.incr("article:views", 1);

// 自增10
long count2 = redisUtil.incr("stock", 10);

// 如果键不存在，初始化为0后再递增

异常：

delta < 0 时抛出 RuntimeException: 递增因子必须大于0

5. 递减 `decr(String key, long delta)`

将指定键的值递减指定增量。

// 自减1
long count = redisUtil.decr("stock", 1);

// 自减5
long count2 = redisUtil.decr("stock", 5);

异常：

delta < 0 时抛出 RuntimeException: 递减因子必须大于0

Hash 操作

1. 获取单个字段值 `hget(String key, String item)`

获取 Hash 中指定字段的值。

// 获取用户信息中的name字段
String name = (String) redisUtil.hget("user:123", "name");

// 获取用户信息中的age字段
Integer age = (Integer) redisUtil.hget("user:123", "age");

2. 获取所有字段 `hmget(String key)`

获取 Hash 中所有键值对。

// 获取用户的所有信息
Map<Object, Object> userInfo = redisUtil.hmget("user:123");
// 返回: {name=zhangsan, age=25, email=test@example.com}

3. 存储多个字段 `hmset(String key, Map<String, Object> map)`

批量存储 Hash 字段，永久有效。

Map<String, Object> userInfo = new HashMap<>();
userInfo.put("name", "zhangsan");
userInfo.put("age", 25);
userInfo.put("email", "test@example.com");

redisUtil.hmset("user:123", userInfo);

4. 存储多个字段并设置过期时间 `hmset(String key, Map<String, Object> map, long time)`

批量存储 Hash 字段并设置过期时间。

Map<String, Object> userInfo = new HashMap<>();
userInfo.put("name", "zhangsan");
userInfo.put("age", 25);

// 存储1小时后过期
redisUtil.hmset("user:123", userInfo, 3600);

5. 存储单个字段 `hset(String key, String item, Object value)`

存储单个 Hash 字段，永久有效。

// 设置用户名
redisUtil.hset("user:123", "name", "zhangsan");

// 更新年龄
redisUtil.hset("user:123", "age", 26);

6. 存储单个字段并设置过期时间 `hset(String key, String item, Object value, long time)`

存储单个 Hash 字段并设置过期时间。

// 存储字段并设置30分钟后过期
redisUtil.hset("user:123", "token", "abc123", 1800);

7. 删除字段 `hdel(String key, Object... item)`

删除 Hash 中的一个或多个字段。

// 删除单个字段
redisUtil.hdel("user:123", "email");

// 删除多个字段
redisUtil.hdel("user:123", "phone", "address");

8. 判断字段是否存在 `hHasKey(String key, String item)`

判断 Hash 中是否存在指定字段。

boolean hasName = redisUtil.hHasKey("user:123", "name");
if (hasName) {
    System.out.println("name字段存在");
}

9. 字段值递增 `hincr(String key, String item, double by)`

将 Hash 中指定字段的值递增指定增量。

// 文章浏览次数+1
double views = redisUtil.hincr("article:1001", "views", 1);

// 积分+10.5
double points = redisUtil.hincr("user:123", "points", 10.5);

10. 字段值递减 `hdecr(String key, String item, double by)`

将 Hash 中指定字段的值递减指定增量。

// 库存-5
double stock = redisUtil.hdecr("product:1001", "stock", 5);

Set 操作

1. 获取所有成员 `sGet(String key)`

获取 Set 中的所有成员。

// 获取所有标签
Set<Object> tags = redisUtil.sGet("article:1001:tags");
// 返回: [Java, Spring, Redis]

2. 判断成员是否存在 `sHasKey(String key, Object value)`

判断 Set 中是否存在指定成员。

boolean hasTag = redisUtil.sHasKey("article:1001:tags", "Java");
if (hasTag) {
    System.out.println("标签存在");
}

3. 添加成员 `sSet(String key, Object... values)`

向 Set 中添加一个或多个成员，永久有效。

// 添加单个成员
long count = redisUtil.sSet("article:1001:tags", "Java");

// 添加多个成员
long count2 = redisUtil.sSet("article:1001:tags", "Spring", "Redis", "MySQL");
// 返回值: 实际添加的成员数量（不包含已存在的）

特性：

自动去重，已存在的成员不会被重复添加

4. 添加成员并设置过期时间 `sSetAndTime(String key, long time, Object... values)`

向 Set 中添加成员并设置过期时间。

// 添加标签并设置1小时后过期
redisUtil.sSetAndTime("article:1001:tags", 3600, "Java", "Spring");

5. 获取成员数量 `sGetSetSize(String key)`

获取 Set 中的成员数量。

// 获取标签数量
long size = redisUtil.sGetSetSize("article:1001:tags");

6. 移除成员 `setRemove(String key, Object... values)`

从 Set 中移除一个或多个成员。

// 移除单个成员
long count = redisUtil.setRemove("article:1001:tags", "Java");

// 移除多个成员
long count2 = redisUtil.setRemove("article:1001:tags", "Spring", "Redis");
// 返回值: 实际移除的成员数量

List 操作

1. 获取范围元素 `lGet(String key, long start, long end)`

获取 List 中指定范围的元素。

// 获取前10个元素
List<Object> items = redisUtil.lGet("news:list", 0, 9);

// 获取所有元素
List<Object> allItems = redisUtil.lGet("news:list", 0, -1);

// 获取最后一个元素
List<Object> lastItem = redisUtil.lGet("news:list", -1, -1);

索引说明：

start = 0, end = -1: 获取所有元素
start = 0, end = 0: 获取第一个元素
start = -1, end = -1: 获取最后一个元素

2. 获取列表长度 `lGetListSize(String key)`

获取 List 中的元素数量。

long size = redisUtil.lGetListSize("news:list");

3. 通过索引获取元素 `lGetIndex(String key, long index)`

通过索引获取 List 中的元素。

// 获取第一个元素（索引0）
Object first = redisUtil.lGetIndex("news:list", 0);

// 获取最后一个元素（索引-1）
Object last = redisUtil.lGetIndex("news:list", -1);

// 获取倒数第二个元素（索引-2）
Object secondLast = redisUtil.lGetIndex("news:list", -2);

4. 添加元素到尾部 `lSet(String key, Object value)`

将元素添加到 List 的尾部，永久有效。

// 添加单个元素
redisUtil.lSet("news:list", "新闻标题1");

5. 添加元素到尾部并设置过期时间 `lSet(String key, Object value, long time)`

将元素添加到 List 的尾部并设置过期时间。

// 添加元素并设置1小时后过期
redisUtil.lSet("news:list", "新闻标题1", 3600);

6. 批量添加元素到尾部 `lSet(String key, List<Object> value)`

将多个元素批量添加到 List 的尾部，永久有效。

List<Object> newsList = new ArrayList<>();
newsList.add("新闻标题1");
newsList.add("新闻标题2");
newsList.add("新闻标题3");

redisUtil.lSet("news:list", newsList);

7. 批量添加元素并设置过期时间 `lSet(String key, List<Object> value, long time)`

将多个元素批量添加到 List 的尾部并设置过期时间。

List<Object> newsList = new ArrayList<>();
newsList.add("新闻标题1");
newsList.add("新闻标题2");

// 批量添加并设置30分钟后过期
redisUtil.lSet("news:list", newsList, 1800);

8. 修改指定索引的元素 `lUpdateIndex(String key, long index, Object value)`

通过索引修改 List 中的元素。

// 修改第一个元素
redisUtil.lUpdateIndex("news:list", 0, "新的新闻标题");

// 修改最后一个元素
redisUtil.lUpdateIndex("news:list", -1, "最后一个标题");

9. 移除元素 `lRemove(String key, long count, Object value)`

从 List 中移除指定数量的元素。

// 移除第一个匹配的元素（从表头）
long count = redisUtil.lRemove("news:list", 1, "新闻标题1");

// 移除所有匹配的元素
long count2 = redisUtil.lRemove("news:list", 0, "新闻标题1");

// 移除最后一个匹配的元素（从表尾）
long count3 = redisUtil.lRemove("news:list", -1, "新闻标题1");

count 说明：

count > 0: 从表头向表尾方向移除
count < 0: 从表尾向表头方向移除
count = 0: 移除所有匹配的元素

ZSet 操作

1. 添加元素 `zSet(String key, Object value, double score)`

向有序集合中添加元素。

// 添加排行榜元素
redisUtil.zSet("leaderboard", "user1", 100);
redisUtil.zSet("leaderboard", "user2", 95);
redisUtil.zSet("leaderboard", "user3", 88);

// 如果元素已存在，则更新其score值
redisUtil.zSet("leaderboard", "user1", 105);

2. 批量添加元素 `batchZSet(String key, Set<ZSetOperations.TypedTuple> typles)`

批量向有序集合中添加元素。

Set<ZSetOperations.TypedTuple> tuples = new HashSet<>();
tuples.add(new DefaultTypedTuple("user1", 100.0));
tuples.add(new DefaultTypedTuple("user2", 95.0));
tuples.add(new DefaultTypedTuple("user3", 88.0));

long count = redisUtil.batchZSet("leaderboard", tuples);

3. 增加分数 `zIncrementScore(String key, Object value, long delta)`

将有序集合中指定元素的分数增加指定值。

// user1的分数增加10分
redisUtil.zIncrementScore("leaderboard", "user1", 10);

// user2的分数减少5分
redisUtil.zIncrementScore("leaderboard", "user2", -5);

4. 并集存储 `zUnionAndStore(String key, Collection otherKeys, String destKey)`

计算多个有序集合的并集并存储到目标集合。

List<String> keys = Arrays.asList("leaderboard:day1", "leaderboard:day2", "leaderboard:day3");

// 计算三天排行榜的并集，存储到leaderboard:total
redisUtil.zUnionAndStore("leaderboard:day1", keys, "leaderboard:total");

5. 获取元素分数 `getZsetScore(String key, Object value)`

获取有序集合中指定元素的分数。

// 获取user1的分数
long score = redisUtil.getZsetScore("leaderboard", "user1");
System.out.println("user1的分数: " + score);

返回值：

元素存在时：返回分数值
元素不存在时：返回 0

6. 获取排名范围内的元素 `getZSetRank(String key, long start, long end)`

获取有序集合中指定范围内的元素及其分数，按分数递减排序。

// 获取前10名
Set<ZSetOperations.TypedTuple> top10 = redisUtil.getZSetRank("leaderboard", 0, 9);

// 获取所有成员及其分数
Set<ZSetOperations.TypedTuple> all = redisUtil.getZSetRank("leaderboard", 0, -1);

// 遍历结果
for (ZSetOperations.TypedTuple tuple : top10) {
    System.out.println("成员: " + tuple.getValue() + ", 分数: " + tuple.getScore());
}

排序规则：

按 score 值递减（从大到小）排序
start = 0: 表示排名第一
end = -1: 表示最后一名

使用场景示例

场景1：用户登录Token管理

// 用户登录成功后存储Token，设置2小时过期
String token = generateToken(userId);
redisUtil.set("token:" + userId, token, 7200);

// 验证Token
String storedToken = (String) redisUtil.get("token:" + userId);
if (token.equals(storedToken)) {
    // Token有效
}

// 用户登出时删除Token
redisUtil.del("token:" + userId);

场景2：文章点赞计数

// 增加点赞数
redisUtil.hincr("article:1001", "likes", 1);

// 获取点赞数
Integer likes = (Integer) redisUtil.hget("article:1001", "likes");

// 取消点赞
redisUtil.hdecr("article:1001", "likes", 1);

场景3：排行榜实现

// 更新用户分数
redisUtil.zSet("game:leaderboard", "user123", 1500);

// 获取前10名
Set<ZSetOperations.TypedTuple> top10 = redisUtil.getZSetRank("game:leaderboard", 0, 9);

// 获取特定用户分数
long score = redisUtil.getZsetScore("game:leaderboard", "user123");

场景4：验证码存储

// 发送验证码，5分钟内有效
String code = "123456";
redisUtil.set("verify:email:" + email, code, 300);

// 验证验证码
String storedCode = (String) redisUtil.get("verify:email:" + email);
if (code.equals(storedCode)) {
    // 验证成功，删除验证码
    redisUtil.del("verify:email:" + email);
}

场景5：文章标签管理

// 添加标签到文章
redisUtil.sSet("article:1001:tags", "Java", "Spring", "Redis");

// 获取所有标签
Set<Object> tags = redisUtil.sGet("article:1001:tags");

// 判断是否有某个标签
boolean hasTag = redisUtil.sHasKey("article:1001:tags", "Java");

// 移除标签
redisUtil.setRemove("article:1001:tags", "Java");

注意事项

空值处理：方法返回的 Object 类型需要根据实际使用场景进行类型转换
过期时间单位：所有过期时间的单位均为秒
异常处理：大部分方法内部已捕获异常并打印堆栈，根据业务需求可能需要额外处理
线程安全：RedisTemplate 本身是线程安全的，可以在多线程环境中使用
键命名规范：建议使用冒号分隔层级，如 user:123:info
内存管理：及时设置过期时间，避免缓存数据堆积占用过多内存

作者

KiRi
版本：1.0
日期：2026-03-19

KiRi

开发之Redis工具类

RedisUtil 使用文档

目录

基础操作

1. 设置过期时间 expire(String key, long time)

2. 获取过期时间 getExpire(String key)

3. 判断键是否存在 hasKey(String key)

4. 删除键 del(String... key)

String 操作

1. 获取值 get(String key)

2. 设置值 set(String key, Object value)

3. 设置值并设置过期时间 set(String key, Object value, long time)

4. 递增 incr(String key, long delta)

5. 递减 decr(String key, long delta)

Hash 操作

1. 获取单个字段值 hget(String key, String item)

2. 获取所有字段 hmget(String key)

3. 存储多个字段 hmset(String key, Map<String, Object> map)

4. 存储多个字段并设置过期时间 hmset(String key, Map<String, Object> map, long time)

5. 存储单个字段 hset(String key, String item, Object value)

6. 存储单个字段并设置过期时间 hset(String key, String item, Object value, long time)

7. 删除字段 hdel(String key, Object... item)

8. 判断字段是否存在 hHasKey(String key, String item)

9. 字段值递增 hincr(String key, String item, double by)

10. 字段值递减 hdecr(String key, String item, double by)

Set 操作

1. 获取所有成员 sGet(String key)

2. 判断成员是否存在 sHasKey(String key, Object value)

3. 添加成员 sSet(String key, Object... values)

4. 添加成员并设置过期时间 sSetAndTime(String key, long time, Object... values)

5. 获取成员数量 sGetSetSize(String key)

6. 移除成员 setRemove(String key, Object... values)