# RedissonUtils

**Repository Path**: chen934298133/redisson-utils

## Basic Information

- **Project Name**: RedissonUtils
- **Description**: RedissonUtils最佳实践：专注于提供Redisson框架的扩展工具和实用方法，简化开发流程，提高效率，适合Java开发者使用。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-08-26
- **Last Updated**: 2025-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RedissonUtils - 企业级 Redis 缓存工具库 - 二级缓存

[![Java](https://img.shields.io/badge/Java-8+-orange.svg)](https://www.oracle.com/java/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.0+-green.svg)](https://spring.io/projects/spring-boot)
[![Redisson](https://img.shields.io/badge/Redisson-3.0+-red.svg)](https://redisson.org/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## 📖 项目简介

RedissonUtils 是一个基于 Redisson 的企业级 Redis 缓存工具库，提供了完整的缓存操作解决方案。该项目采用模块化设计，将不同类型的缓存操作分离到专门的工具类中，提供了简洁易用的 API 接口。

## ✨ 核心特性

- 🚀 **高性能**: 基于 Redisson 客户端，支持异步操作和连接池
- 🔧 **模块化设计**: 按功能分类的工具类，职责清晰
- 💾 **本地缓存**: 集成 Caffeine 本地缓存，减轻 Redis 负担
- 🔒 **分布式锁**: 完整的分布式锁解决方案
- 📊 **限流控制**: 基于令牌桶的分布式限流
- 🔄 **原子操作**: 支持原子计数器和原子值操作
- 📦 **集合操作**: 完整的 List、Set、Map 缓存操作
- 📨 **消息队列**: 支持发布订阅、阻塞队列、可靠队列、优先级队列等
- 🎯 **高级队列**: 支持可靠队列(RReliableQueue)、优先级队列(RPriorityQueue)、传输队列(RTransferQueue)、环形缓冲区(RRingBuffer)
- ⚡ **现代化 API**: 使用 Duration 替代过时的 TimeUnit

## 🏗️ 架构设计

```
RedissonUtils (主入口)
├── RedissonObjectUtils      # 基础对象缓存操作
├── RedissonCollectionUtils  # 集合类型缓存操作
├── RedissonLockUtils        # 分布式锁操作
├── RedissonAtomicUtils      # 原子操作
├── RedissonQueueUtils       # 队列和消息操作
├── RedissonRateLimiterUtils # 限流操作
└── RedissonLocalCacheUtils  # 本地缓存管理
```

## 🚀 快速开始

### 1. 添加依赖

```xml
<dependency>
    <groupId>org.nehc.algorithm</groupId>
    <artifactId>redisson-utils</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 2. 配置 Redisson

```yaml
# application.yml
spring:
  redis:
    host: localhost
    port: 6379
    password: your_password
    database: 0
```

### 3. 基本使用

```java
// 基础缓存操作
RedissonObjectUtils.setCacheObject("user", "123", userObject, Duration.ofHours(1));
User user = RedissonObjectUtils.getCacheObject("user", "123");

// 分布式锁
if (RedissonLockUtils.tryLock("order", "123", Duration.ofSeconds(10), Duration.ofMinutes(1))) {
    try {
        // 业务逻辑
    } finally {
        RedissonLockUtils.unLock("order", "123");
    }
}

// 限流控制
if (RedissonRateLimiterUtils.tryAcquire("api:user:123")) {
    // 执行业务逻辑
}

// 可靠队列操作
RedissonQueueUtils.addReliableQueueMessage("task_queue", taskMessage);
List<Message> messages = RedissonQueueUtils.pollReliableQueueMessage("task_queue", 5);
RedissonQueueUtils.acknowledgeMessage("task_queue", messageId);

// 优先级队列操作
RedissonQueueUtils.addPriorityQueueElement("priority_queue", priorityTask);
Task task = RedissonQueueUtils.pollPriorityQueueElement("priority_queue");

// 环形缓冲区操作
RedissonQueueUtils.setRingBufferCapacity("metrics", 1000);
RedissonQueueUtils.addRingBufferElement("metrics", metricData);
```

## 📚 API 文档

### RedissonObjectUtils - 基础对象操作

📋 **[查看完整测试用例](src/test/java/org/nehc/algorithm/redissonutils/RedissonObjectUtilsTest.java)**

| 方法 | 描述 | 示例 |
|------|------|------|
| `setCacheObject(cacheName, key, value)` | 设置缓存对象 | `setCacheObject("user", "123", user)` |
| `setCacheObject(cacheName, key, value, duration)` | 设置带过期时间的缓存 | `setCacheObject("user", "123", user, Duration.ofHours(1))` |
| `getCacheObject(cacheName, key)` | 获取缓存对象 | `getCacheObject("user", "123")` |
| `deleteObject(cacheName, key)` | 删除缓存对象 | `deleteObject("user", "123")` |
| `isExistsObject(cacheName, key)` | 判断缓存是否存在 | `isExistsObject("user", "123")` |
| `expire(cacheName, key, duration)` | 设置过期时间 | `expire("user", "123", Duration.ofHours(2))` |

### RedissonLockUtils - 分布式锁操作

📋 **[查看完整测试用例](src/test/java/org/nehc/algorithm/redissonutils/RedissonLockUtilsTest.java)**

| 方法 | 描述 | 示例 |
|------|------|------|
| `tryLock(cacheName, key, waitTime, leaseTime)` | 尝试获取锁 | `tryLock("order", "123", Duration.ofSeconds(5), Duration.ofMinutes(1))` |
| `tryLock(cacheName, key, timeoutMills)` | 尝试获取锁(毫秒) | `tryLock("order", "123", 5000)` |
| `unLock(cacheName, key)` | 释放锁 | `unLock("order", "123")` |
| `isLocked(cacheName, key)` | 判断是否被锁定 | `isLocked("order", "123")` |
| `forceUnlock(cacheName, key)` | 强制释放锁 | `forceUnlock("order", "123")` |

### RedissonRateLimiterUtils - 限流操作

📋 **[查看完整测试用例](src/test/java/org/nehc/algorithm/redissonutils/RedissonRateLimiterUtilsTest.java)**

| 方法 | 描述 | 示例 |
|------|------|------|
| `initRateLimiter(key, rateType, rate, rateInterval)` | 初始化限流器 | `initRateLimiter("api:user", RateType.OVERALL, 100, Duration.ofMinutes(1))` |
| `tryAcquire(key)` | 尝试获取许可 | `tryAcquire("api:user:123")` |
| `tryAcquire(key, permits)` | 尝试获取指定数量许可 | `tryAcquire("api:user:123", 5)` |
| `availablePermits(key)` | 获取可用许可数 | `availablePermits("api:user:123")` |

### RedissonAtomicUtils - 原子操作

📋 **[查看完整测试用例](src/test/java/org/nehc/algorithm/redissonutils/RedissonAtomicUtilsTest.java)**

| 方法 | 描述 | 示例 |
|------|------|------|
| `setAtomicValue(cacheName, key, value)` | 设置原子值 | `setAtomicValue("counter", "page_view", 1000)` |
| `getAtomicValue(cacheName, key)` | 获取原子值 | `getAtomicValue("counter", "page_view")` |
| `incrAtomicValue(cacheName, key)` | 原子递增 | `incrAtomicValue("counter", "page_view")` |
| `decrAtomicValue(cacheName, key)` | 原子递减 | `decrAtomicValue("counter", "page_view")` |

### RedissonCollectionUtils - 集合操作

📋 **[查看完整测试用例](src/test/java/org/nehc/algorithm/redissonutils/RedissonCollectionUtilsTest.java)**

#### List 操作
| 方法 | 描述 | 示例 |
|------|------|------|
| `setCacheList(cacheName, key, list)` | 设置 List 缓存 | `setCacheList("user", "friends:123", friendsList)` |
| `getCacheList(cacheName, key)` | 获取 List 缓存 | `getCacheList("user", "friends:123")` |
| `listRightPush(cacheName, key, value, maxSize)` | 右侧添加元素 | `listRightPush("log", "user:123", logEntry, 1000)` |

#### Set 操作
| 方法 | 描述 | 示例 |
|------|------|------|
| `setCacheSet(cacheName, key, set)` | 设置 Set 缓存 | `setCacheSet("user", "tags:123", tagsSet)` |
| `getCacheSet(cacheName, key)` | 获取 Set 缓存 | `getCacheSet("user", "tags:123")` |

#### Map 操作
| 方法 | 描述 | 示例 |
|------|------|------|
| `setCacheMap(cacheName, key, map)` | 设置 Map 缓存 | `setCacheMap("user", "profile:123", profileMap)` |
| `getCacheMap(cacheName, key)` | 获取 Map 缓存 | `getCacheMap("user", "profile:123")` |
| `setCacheMapValue(cacheName, key, hKey, value)` | 设置 Map 中的值 | `setCacheMapValue("user", "profile:123", "name", "张三")` |
| `getCacheMapValue(cacheName, key, hKey)` | 获取 Map 中的值 | `getCacheMapValue("user", "profile:123", "name")` |

### RedissonQueueUtils - 队列和消息操作

📋 **[查看完整测试用例](src/test/java/org/nehc/algorithm/redissonutils/RedissonQueueUtilsTest.java)**

#### 基础队列操作
| 方法 | 描述 | 示例 |
|------|------|------|
| `addQueueObject(queueName, data)` | 添加队列元素 | `addQueueObject("task_queue", taskData)` |
| `pollQueueObject(queueName)` | 获取并移除队列头部元素 | `pollQueueObject("task_queue")` |
| `publish(channelKey, message)` | 发布消息 | `publish("user:notification", notification)` |
| `subscribe(channelKey, clazz, consumer)` | 订阅消息 | `subscribe("user:notification", Notification.class, this::handleNotification)` |

#### 可靠队列 (RReliableQueue) 操作
| 方法 | 描述 | 示例 |
|------|------|------|
| `getReliableQueue(queueName)` | 获取可靠队列实例 | `getReliableQueue("reliable_task_queue")` |
| `setReliableQueueConfig(queueName, config)` | 设置可靠队列配置 | `setReliableQueueConfig("queue", config)` |
| `addReliableQueueMessage(queueName, message)` | 添加可靠队列消息 | `addReliableQueueMessage("queue", message)` |
| `pollReliableQueueMessage(queueName, count)` | 批量获取可靠队列消息 | `pollReliableQueueMessage("queue", 10)` |
| `acknowledgeMessage(queueName, messageId)` | 确认消息处理完成 | `acknowledgeMessage("queue", "msg123")` |
| `rejectMessage(queueName, messageId)` | 拒绝消息并移至死信队列 | `rejectMessage("queue", "msg123")` |
| `isReliableQueueEmpty(queueName)` | 检查可靠队列是否为空 | `isReliableQueueEmpty("queue")` |
| `getReliableQueueSize(queueName)` | 获取可靠队列大小 | `getReliableQueueSize("queue")` |

#### 优先级队列 (RPriorityQueue) 操作
| 方法 | 描述 | 示例 |
|------|------|------|
| `getPriorityQueue(queueName)` | 获取优先级队列实例 | `getPriorityQueue("priority_task_queue")` |
| `addPriorityQueueElement(queueName, element)` | 添加优先级队列元素 | `addPriorityQueueElement("queue", task)` |
| `pollPriorityQueueElement(queueName)` | 获取并移除最高优先级元素 | `pollPriorityQueueElement("queue")` |
| `peekPriorityQueueElement(queueName)` | 查看最高优先级元素 | `peekPriorityQueueElement("queue")` |

#### 传输队列 (RTransferQueue) 操作
| 方法 | 描述 | 示例 |
|------|------|------|
| `getTransferQueue(queueName)` | 获取传输队列实例 | `getTransferQueue("transfer_queue")` |
| `transferElement(queueName, element)` | 传输元素到等待的消费者 | `transferElement("queue", data)` |
| `tryTransferElement(queueName, element)` | 尝试传输元素 | `tryTransferElement("queue", data)` |
| `hasWaitingConsumer(queueName)` | 检查是否有等待的消费者 | `hasWaitingConsumer("queue")` |

#### 环形缓冲区 (RRingBuffer) 操作
| 方法 | 描述 | 示例 |
|------|------|------|
| `getRingBuffer(bufferName)` | 获取环形缓冲区实例 | `getRingBuffer("ring_buffer")` |
| `setRingBufferCapacity(bufferName, capacity)` | 设置环形缓冲区容量 | `setRingBufferCapacity("buffer", 1000)` |
| `addRingBufferElement(bufferName, element)` | 添加元素到环形缓冲区 | `addRingBufferElement("buffer", data)` |
| `getRingBufferCapacity(bufferName)` | 获取环形缓冲区容量 | `getRingBufferCapacity("buffer")` |
| `getRingBufferRemainingCapacity(bufferName)` | 获取剩余容量 | `getRingBufferRemainingCapacity("buffer")` |

### RedissonLocalCacheUtils - 本地缓存管理

📋 **[查看完整测试用例](src/test/java/org/nehc/algorithm/redissonutils/RedissonLocalCacheUtilsTest.java)**

| 方法 | 描述 | 示例 |
|------|------|------|
| `getOrCreateCache(cacheName, maxSize, expireAfterWrite, expireAfterAccess)` | 创建本地缓存 | `getOrCreateCache("user", 1000, Duration.ofMinutes(30), Duration.ofMinutes(10))` |
| `set(key, value)` | 设置本地缓存 | `set("user:123", user)` |
| `get(key)` | 获取本地缓存 | `get("user:123")` |

## 🔧 高级配置

### 缓存域配置

```java
public enum CacheScope {
    APPLICATION("app"),     // 应用级缓存
    SESSION("session"),     // 会话级缓存
    USER("user"),          // 用户级缓存
    TEMP("temp");          // 临时缓存
    
    private final String cacheName;
}
```

### 本地缓存配置

```java
// 自定义本地缓存配置
Cache<String, Object> customCache = RedissonLocalCacheUtils.getOrCreateCache(
    "custom", 
    5000,                           // 最大缓存数量
    Duration.ofMinutes(30),         // 写入后过期时间
    Duration.ofMinutes(10)          // 访问后过期时间
);
```

## 🎯 最佳实践

### 1. 缓存键命名规范

```java
// 推荐的命名方式
RedissonObjectUtils.setCacheObject("user", "profile:123", userProfile);
RedissonObjectUtils.setCacheObject("order", "detail:456", orderDetail);
```

### 2. 分布式锁使用

```java
// 推荐的锁使用模式
String lockKey = "order:" + orderId;
if (RedissonLockUtils.tryLock("business", lockKey, Duration.ofSeconds(5), Duration.ofMinutes(1))) {
    try {
        // 执行需要同步的业务逻辑
        processOrder(orderId);
    } finally {
        RedissonLockUtils.unLock("business", lockKey);
    }
} else {
    throw new BusinessException("系统繁忙，请稍后重试");
}
```

### 3. 限流配置

```java
// API 限流示例
String rateLimiterKey = "api:" + apiPath + ":" + userId;

// 初始化限流器：每分钟最多 100 次请求
RedissonRateLimiterUtils.initRateLimiter(
    rateLimiterKey, 
    RateType.OVERALL, 
    100, 
    Duration.ofMinutes(1)
);

// 检查限流
if (!RedissonRateLimiterUtils.tryAcquire(rateLimiterKey)) {
    throw new RateLimitException("请求过于频繁，请稍后重试");
}
```

### 4. 缓存过期策略

```java
// 不同类型数据的推荐过期时间
RedissonObjectUtils.setCacheObject("user", "profile:" + userId, userProfile, Duration.ofHours(2));     // 用户信息
RedissonObjectUtils.setCacheObject("config", "system", systemConfig, Duration.ofMinutes(30));          // 系统配置
RedissonObjectUtils.setCacheObject("temp", "captcha:" + sessionId, captcha, Duration.ofMinutes(5));     // 验证码
```

### 5. 队列使用最佳实践

```java
// 可靠队列使用示例
String queueName = "order_processing";

// 配置可靠队列
QueueConfigParams config = QueueConfigParams.defaults()
    .maxSize(10000)
    .messageMaxSize(1024 * 1024)  // 1MB
    .messageExpiration(Duration.ofHours(24))
    .visibilityTimeout(Duration.ofMinutes(5))
    .deliveryLimit(3);

RedissonQueueUtils.setReliableQueueConfig(queueName, config);

// 生产者：添加消息
OrderTask task = new OrderTask(orderId, userId);
RedissonQueueUtils.addReliableQueueMessage(queueName, task);

// 消费者：处理消息
List<Message> messages = RedissonQueueUtils.pollReliableQueueMessage(queueName, 10);
for (Message message : messages) {
    try {
        // 处理业务逻辑
        processOrder(message.getPayload());
        
        // 确认消息处理完成
        RedissonQueueUtils.acknowledgeMessage(queueName, message.getId());
    } catch (Exception e) {
        // 处理失败，拒绝消息
        RedissonQueueUtils.rejectMessage(queueName, message.getId());
        log.error("处理订单失败: {}", message.getId(), e);
    }
}
```

```java
// 优先级队列使用示例
String priorityQueueName = "task_priority_queue";

// 添加不同优先级的任务
RedissonQueueUtils.addPriorityQueueElement(priorityQueueName, new PriorityTask("urgent", 1));
RedissonQueueUtils.addPriorityQueueElement(priorityQueueName, new PriorityTask("normal", 5));
RedissonQueueUtils.addPriorityQueueElement(priorityQueueName, new PriorityTask("low", 10));

// 按优先级处理任务
PriorityTask task = RedissonQueueUtils.pollPriorityQueueElement(priorityQueueName);
if (task != null) {
    processTask(task);
}
```

```java
// 环形缓冲区使用示例
String bufferName = "metrics_buffer";

// 设置缓冲区容量
RedissonQueueUtils.setRingBufferCapacity(bufferName, 1000);

// 添加指标数据（自动覆盖旧数据）
Metric metric = new Metric("cpu_usage", 85.5, System.currentTimeMillis());
RedissonQueueUtils.addRingBufferElement(bufferName, metric);

// 检查剩余容量
long remaining = RedissonQueueUtils.getRingBufferRemainingCapacity(bufferName);
log.info("缓冲区剩余容量: {}", remaining);
```

## 🔍 监控和调试

### 缓存统计

```java
// 获取本地缓存统计信息
CacheStats stats = RedissonLocalCacheUtils.stats();
log.info("缓存命中率: {}", stats.hitRate());
log.info("缓存大小: {}", RedissonLocalCacheUtils.size());
```

### 锁状态检查

```java
// 检查锁状态
boolean isLocked = RedissonLockUtils.isLocked("business", lockKey);
boolean isHeldByCurrentThread = RedissonLockUtils.isHeldByCurrentThread("business", lockKey);
long remainTime = RedissonLockUtils.remainTimeToLive("business", lockKey);
```

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 联系方式

- 项目地址: [hhttps://gitee.com/chen934298133/redisson-utils](https://gitee.com/chen934298133/redisson-utils)
- 问题反馈: [Issues](https://gitee.com/chen934298133/redisson-utils/issues)
- 邮箱: chen934298133@163.com

## 🙏 致谢

感谢以下开源项目的支持：

- [Redisson](https://redisson.org/) - Redis Java 客户端
- [Caffeine](https://github.com/ben-manes/caffeine) - 高性能本地缓存
- [Spring Boot](https://spring.io/projects/spring-boot) - 应用框架

---

⭐ 如果这个项目对你有帮助，请给我们一个 Star！