# redis-queue-service

**Repository Path**: aopmin/redis-queue-service

## Basic Information

- **Project Name**: redis-queue-service
- **Description**: SpringBoot Redis消息队列组件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 一、项目名称（简洁、专业、好记）
## 正式名称
**SpringBoot Redis 可靠消息队列服务**


---

# 二、场景设计文档（可直接交付给团队/写进方案）
# 1. 项目概述
## 1.1 项目背景
在微服务架构中，存在**跨服务异步消息通知、任务异步处理**场景：
- 消息由其他微服务发送
- 需支持高并发、消息堆积
- 项目重启、发版、容器重建**不丢失消息**
- 不引入重型 MQ（RabbitMQ/RocketMQ）
- 内存队列满时需自动降级，避免阻塞或丢失数据

## 1.2 实现目标
- 实现**主队列 + 备用队列**两级缓冲
- 主队列满自动转入备用队列
- 基于 Redis 实现持久化，重启不丢消息
- 提供通用接口供其他服务调用发送消息
- 后台线程异步监听消费，不阻塞主线程
- 高可用、高性能、轻量无侵入

## 1.3 技术栈
- JDK 17
- SpringBoot 3.2.x
- Redis（List 结构）
- Spring Data Redis
- 异步线程消费

---

# 2. 整体架构设计
## 2.1 架构图
```
其他微服务
        ↓
HTTP 接口 / RPC
        ↓
Redis 主队列（queue:main）→ 满 → Redis 备用队列（queue:backup）
        ↓
后台异步消费者
优先消费主队列 → 主空消费备用
        ↓
业务逻辑处理
```

## 2.2 队列设计
- **主队列**：正常流量使用，设置最大长度，控制内存与并发压力
- **备用队列**：主队列满时自动转入，用于削峰、兜底、堆积
- 消费策略：**先主后备**，保证正常消息优先处理

## 2.3 可靠性保证
- Redis 开启 AOF + RDB 持久化
- 服务重启、发版、容器重建，消息不丢失
- 多实例部署不重复消费（Redis 单线程原子出队）

---

# 3. 核心流程设计
## 3.1 消息入队流程
1. 其他服务调用 `/send` 接口发送消息
2. 系统判断主队列长度
3. 未满 → 写入主队列 `queue:main`
4. 已满 → 自动写入备用队列 `queue:backup`
5. 返回成功，不阻塞调用方

## 3.2 消息消费流程
1. 项目启动后，后台异步线程无限循环监听
2. 优先从主队列左弹出消息（FIFO）
3. 主队列为空时，从备用队列取消息
4. 取到消息后执行业务逻辑
5. 无消息时休眠 100ms，避免空轮询占用 CPU

## 3.3 队列满处理策略
- 不丢弃消息
- 不阻塞生产者
- 自动平滑切换到备用队列
- 消费能力恢复后继续消费堆积消息

---

# 4. 核心功能清单
- [x] 外部服务消息发送接口
- [x] 主队列 + 备用队列自动切换
- [x] 重启/发版不丢失消息
- [x] 异步监听消费
- [x] 高并发支撑
- [x] 多实例安全消费
- [x] 无专业 MQ 依赖

---

# 5. 关键配置说明
```yaml
# 主队列最大长度（可根据业务调整）
MAIN_QUEUE_MAX_SIZE = 200

# Redis Key
主队列：queue:main
备用队列：queue:backup
```

---

# 6. 优缺点分析
## 优点
- 轻量、易维护、无需运维 MQ
- 高性能，Redis 单机支持 10W+/s 入队
- 重启不丢消息
- 队列满自动兜底，不丢数据
- 多实例部署安全
- 代码简洁，易于二次开发

## 缺点
- 不支持严格事务消息
- 不支持死信、延迟、重试高级特性（可扩展）
- 极端超大规模消息需考虑 Redis 内存

---

# 7. 适用场景
- 微服务异步通知
- 日志收集、事件上报
- 订单状态变更、任务延迟处理
- 流量削峰、消息缓冲
- 不希望引入重型 MQ 的中小规模项目

---

# 8. 扩展方向（可选）
- 消费失败自动重试
- 死信队列
- 消息确认机制（ACK）
- 多线程消费
- 队列长度监控接口
- 消息序列化与对象传输
- 消费限流、黑白名单

---