# easy-mq
**Repository Path**: workwq/easy-mq
## Basic Information
- **Project Name**: easy-mq
- **Description**: Easy-MQ 是一个基于 Spring Boot 的轻量级消息队列中间件 SDK，旨在简化消息队列的开发和使用。它提供了统一的消息发送和消费接口，支持多种消息队列（RocketMQ、RabbitMQ），并内置了幂等控制、监控追踪、故障诊断等企业级功能。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 7
- **Forks**: 1
- **Created**: 2025-06-25
- **Last Updated**: 2025-08-26
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Easy-MQ 消息队列中间件
**轻量级消息队列中间件 SDK，让消息队列开发变得简单高效**
[快速开始](#快速开始) • [功能特性](#功能特性) • [架构设计](#架构设计) • [使用指南](#使用指南) • [文档](#文档)
## 📖 项目简介
Easy-MQ 是一个基于 Spring Boot 的轻量级消息队列中间件 SDK，旨在简化消息队列的开发和使用。它提供了统一的消息发送和消费接口，支持多种消息队列（RocketMQ、RabbitMQ），并内置了幂等控制、监控追踪、故障诊断等企业级功能。
### 🎯 设计目标
- **简单易用**：通过注解驱动，零配置集成
- **功能完整**：涵盖消息队列开发的所有核心需求
- **高性能**：优化的序列化和存储机制
- **可扩展**：插件式架构，支持多种 MQ 适配
- **运维友好**：内置监控、诊断、控制台等运维工具
## ✨ 功能特性
### 🚀 核心功能
- **统一消息接口**：支持同步/异步发送，统一 API 适配多 MQ
- **注解驱动消费**：`@MQListener` 注解简化消息消费开发
- **自动序列化**：支持 JSON/Protobuf 序列化，自动检测类型
- **幂等控制**：内置 Caffeine/Redis 双模式幂等控制
- **全链路追踪**：基于 traceId 的消息全生命周期追踪
### 🛡️ 企业级特性
- **故障诊断**：完整的故障排查和诊断工具
- **性能监控**：SQLite 嵌入式存储 + Prometheus 指标收集
- **健康检查**：自动健康检查和告警机制
- **Web 控制台**：可视化监控和管理界面
- **配置管理**：灵活的配置体系和环境适配
### 🔧 开发体验
- **零配置启动**：Spring Boot 自动配置，开箱即用
- **Client 封装**：统一的对外调用接口，屏蔽内部复杂性
- **丰富示例**：完整的 Demo 应用和测试用例
- **详细文档**：全面的使用指南和 API 文档
## 🏗️ 架构设计
### 整体架构
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 应用层 │ │ Client 层 │ │ Service 层 │
│ │ │ │ │ │
│ Controller │───▶│ EasyMqClient │───▶│ MessageService │
│ Service │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Core 层 │ │ Mapper 层 │
│ │ │ │
│ IdempotentHandler│ │ MessageMapper │
│ MonitorService │ │ │
│ MessageSerializer│ └─────────────────┘
└─────────────────┘
│
▼
┌─────────────────┐
│ Adapter 层 │
│ │
│ RocketMQ │
│ RabbitMQ │
│ 其他 MQ... │
└─────────────────┘
```
### 核心组件
- **EasyMqClient**：对外统一调用接口
- **MessageService**：内部消息服务实现
- **IdempotentHandler**：幂等控制处理器
- **MonitorService**：监控和追踪服务
- **MessageSerializer**：消息序列化器
- **MQ Adapter**：多 MQ 适配器
## 🚀 快速开始
### 环境要求
- JDK 21+
- Maven 3.6+
- Spring Boot 3.0+
### 1. 添加依赖
```xml
com.klm
easy-mq-tools
1.0.0
```
### 2. 配置启用
```yaml
# application.yml
easy-mq:
enabled: true
idempotent:
enabled: true
storage: caffeine
monitor:
enabled: true
storage: sqlite
```
### 3. 发送消息
```java
@RestController
public class MessageController {
@Autowired
private EasyMqClient easyMqClient;
@PostMapping("/send")
public String sendMessage(@RequestBody Message message) {
boolean success = easyMqClient.sendMessage(
message.getTopic(),
message.getContent(),
message.getBusinessKey()
);
return success ? "发送成功" : "发送失败";
}
}
```
### 4. 消费消息
```java
@Component
public class OrderMessageListener {
@MQListener(topic = "order-topic", group = "order-group")
public void handleOrderMessage(String message) {
// 处理订单消息
System.out.println("收到订单消息: " + message);
}
}
```
## 📚 使用指南
### 基础使用
- **[注解使用指南](easy-mq-tools/ANNOTATION_USAGE.md)**：详细说明 `@MQListener`、`@MQProducer` 等注解的使用方法
- **[配置指南](easy-mq-tools/CONFIGURATION_GUIDE.md)**：完整的配置参数说明和最佳实践
- **[健康检查和指标](easy-mq-tools/HEALTH_METRICS_USAGE.md)**：监控、健康检查和性能指标的使用方法
### 高级功能
- **幂等控制**：支持 SpEL 表达式指定业务键，防止重复消费
- **故障诊断**：内置故障排查工具，快速定位问题
- **性能优化**：批量发送、异步处理、连接池优化
- **监控告警**：实时监控、异常告警、性能分析
## 📁 项目结构
```
easy-mq/
├── easy-mq-tools/ # SDK 核心模块
│ ├── src/main/java/
│ │ └── com/klm/easymq/
│ │ ├── client/ # 对外客户端接口
│ │ ├── core/ # 核心组件
│ │ ├── service/ # 内部服务
│ │ ├── config/ # 自动配置
│ │ ├── aspect/ # AOP 切面
│ │ └── controller/ # 内置控制器
│ ├── README.md # SDK 详细文档
│ └── pom.xml
├── easy-mq-demo/ # 演示应用
│ ├── src/main/java/
│ │ └── com/klm/easymq/demo/
│ │ ├── controller/ # 示例控制器
│ │ ├── service/ # 示例服务
│ │ └── entity/ # 示例实体
│ ├── README.md # Demo 使用指南
│ └── pom.xml
├── README.md # 项目概览（本文档）
└── pom.xml # 父 POM
```
## 🔧 配置说明
### 基础配置
```yaml
easy-mq:
enabled: true # 启用 Easy-MQ
idempotent:
enabled: true # 启用幂等控制
storage: caffeine # 存储类型：caffeine/redis
monitor:
enabled: true # 启用监控
storage: sqlite # 存储类型：sqlite/memory
serialization:
type: json # 序列化类型：json/protobuf
console:
enabled: true # 启用 Web 控制台
```
### 高级配置
详细配置参数请参考：[配置指南](easy-mq-tools/CONFIGURATION_GUIDE.md)
## 📊 监控和运维
### Web 控制台
访问 `http://localhost:8080/easymq` 查看：
- 消息发送/消费统计
- 实时监控数据
- 故障诊断报告
- 性能指标分析
### 健康检查
```bash
# 健康检查
GET /actuator/health
# Prometheus 指标
GET /actuator/prometheus
```
### 故障诊断
详细故障排查方法请参考：[健康检查和指标](easy-mq-tools/HEALTH_METRICS_USAGE.md)
## 🎯 最佳实践
### 1. 消息设计
- 使用有意义的 topic 名称
- 合理设置消息大小
- 添加业务键用于幂等控制
### 2. 消费处理
- 实现幂等性处理
- 添加异常处理机制
- 合理设置并发度
### 3. 监控运维
- 启用监控和追踪
- 定期检查健康状态
- 设置合理的告警阈值
## 🤝 贡献指南
我们欢迎所有形式的贡献，包括但不限于：
1. **Bug 报告**：通过 [Issues](https://gitee.com/your-repo/easy-mq/issues) 提交
2. **功能建议**：在 Issues 中提出新功能建议
3. **代码贡献**：提交 Pull Request
4. **文档改进**：完善文档和示例
### 开发环境搭建
```bash
# 克隆项目
git clone https://gitee.com/your-repo/easy-mq.git
cd easy-mq
# 编译项目
mvn clean compile
# 运行测试
mvn test
# 启动 Demo
cd easy-mq-demo
mvn spring-boot:run
```
## 📄 许可证
本项目采用 [MIT 许可证](LICENSE)，详见 LICENSE 文件。
## 📞 联系方式
- **项目地址**：https://gitee.com/your-repo/easy-mq
- **问题反馈**：https://gitee.com/your-repo/easy-mq/issues
- **邮箱**：your-email@example.com
- **QQ 群**：123456789
## 🙏 致谢
感谢以下开源项目的支持：
- [Spring Boot](https://spring.io/projects/spring-boot)
- [MyBatis Plus](https://mybatis.plus/)
- [Caffeine](https://github.com/ben-manes/caffeine)
- [SQLite](https://www.sqlite.org/)
- [RocketMQ](https://rocketmq.apache.org/)
---
**如果这个项目对你有帮助，请给它一个 ⭐ Star**
Made with ❤️ by [Your Name]