# backend-mq

**Repository Path**: MetaLite/backend-mq

## Basic Information

- **Project Name**: backend-mq
- **Description**: 【可选jar包依赖】元界MetaLite后端应用的消息队列依赖库，封装Kafka、RocketMq的消息生产和消费，支持多集群配置，整合最佳实践。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-22
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# backend-mq

## 简介

`backend-mq` 是 MetaLite 微服务框架的**消息队列封装模块**，提供RocketMQ和Kafka的统一封装，简化消息生产和消费开发，是所有后端服务的**可选jar包依赖**。

### 定位与职责

| 定位 | 职责 |
|------|------|
| 消息队列封装 | 统一RocketMQ和Kafka的API |
| 按需引入 | 业务服务需要MQ时引入 |
| 简化开发 | 继承基类实现消费者，注入Producer发送消息 |
| 消息类型支持 | 普通/顺序/延迟消息 |

---

## 设计思想

### 消费者实现方式

通过继承抽象基类实现消费者：

```java
// RocketMQ消费者
@Component
public class OrderConsumer extends BaseRocketMQConsumer<OrderMessageDto> {
    
    @Override
    public String group() {
        return "order-consumer-group";  // 消费者组名称
    }

    @Override
    public boolean handleMessage(OrderMessageDto dto) {
        // 业务处理
        return true;  // true-成功，false-失败重试
    }
}

// Kafka消费者
@Component
public class OrderConsumer extends BaseKafkaConsumer<OrderMessageDto> {
    
    @Override
    public String group() {
        return "order-consumer-group";
    }

    @Override
    public boolean handleMessage(OrderMessageDto dto) {
        return true;
    }
}
```

### 生产者使用方式

注入Producer类发送消息：

```java
@Resource
private RocketMQProducer rocketProducer;

@Resource
private KafkaProducer kafkaProducer;

// RocketMQ发送
rocketProducer.sendNormal("default-cluster", messageDto);
rocketProducer.sendDelay("default-cluster", messageDto, Duration.ofMinutes(5));
rocketProducer.sendOrdered("default-cluster", messageDto);

// Kafka发送
kafkaProducer.sendASync("default-cluster", messageDto);
kafkaProducer.sendSync("default-cluster", messageDto);
```

### 核心优势

| 优势 | 说明 |
|------|------|
| 继承基类 | 继承BaseConsumer，只需实现group()和handleMessage() |
| 配置驱动 | 消费者在配置文件中配置clusterList、topic等 |
| 统一API | RocketMQ和Kafka使用方式一致 |
| 自动管理 | 生产者延迟初始化、消费者自动启动 |

---

## 核心能力

| 能力 | 说明 |
|------|------|
| 普通消息 | sendNormal/sendASync/sendSync |
| 延迟消息 | sendDelay，指定时间投递（RocketMQ） |
| 顺序消息 | sendOrdered，相同messageKey进入同一队列 |
| 集群消费 | 默认模式，消息只被一个实例消费 |
| 广播消费 | 配置messageModel为BROADCASTING |
| 顺序消费 | 配置consumeOrderly为true |
| 消费重试 | handleMessage返回false触发重试 |
| 死信队列 | 超过重试次数进入死信队列（RocketMQ） |
| 消息轨迹 | 自动记录发送和消费日志 |
| 分区消费 | Kafka每个分区独立线程池处理 |

---

## 模块结构

```
backend-mq/
├── backend-mq-common/       # 消息队列通用接口
│   ├── dto/                 # MessageDto消息对象
│   └── aspect/              # 发送/消费日志切面
│
├── backend-mq-rocketmq/     # RocketMQ实现
│   ├── BaseRocketMQConsumer # 消费者抽象基类
│   ├── RocketMQProducer     # 生产者
│   └── config/              # 配置类
│
└── backend-mq-kafka/        # Kafka实现
    ├── BaseKafkaConsumer    # 消费者抽象基类
    ├── KafkaProducer        # 生产者
    └── config/              # 配置类
```

---

## 许可证

MIT License