Java-219 RocketMQ Spring Boot 集成指南：生产者与消费者实战

TL;DR

• 场景：Spring Boot 项目集成 Apache RocketMQ 实现消息队列的生产与消费
• 结论：通过 RocketMQTemplate 简化消息发送，使用 @RocketMQMessageListener 注解实现消费者，完整支持普通/顺序/事务消息
• 产出：可直接运行的 Producer 配置类、Consumer 监听器示例及 YAML 配置

版本矩阵

功能	状态	说明
Spring Boot 2.x 集成	✅ 已验证	基于 2.7.x 测试通过
Spring Boot 3.x 集成	✅ 已验证	兼容 3.x 系列
JDK 8+ 支持	✅ 已验证	推荐 JDK 8 或更高版本
RocketMQ 4.x	✅ 已验证	4.5.1+ 测试通过
RocketMQ 5.x	✅ 已验证	兼容
普通消息发送	✅ 已验证	convertAndSend 接口
顺序消息消费	✅ 已验证	ConsumeMode.ORDERLY
事务消息	✅ 已验证	RocketMQTemplate 支持
集群消费模式	✅ 已验证	默认模式
广播消费模式	✅ 已验证	MessageModel.BROADCASTING
死信队列 DLQ	✅ 已验证	超过最大重试次数后进入

---

RocketMQ Spring 使用

本文将详细介绍如何在 Spring Boot 项目中集成 Apache RocketMQ，实现消息的生产与消费。通过本教程，你将快速掌握 RocketMQ 与 Spring Boot 的整合方式。

1. 环境准备

在开始之前，请确保你的开发环境满足以下条件：

• JDK 1.8+：推荐使用 JDK 8 或更高版本。
• Spring Boot 2.x / 3.x：本示例基于 Spring Boot 2.7.x 测试，同样兼容 3.x 系列。
• RocketMQ 服务：需要有一个可用的 RocketMQ 服务端（NameServer + Broker），可以是本地部署或远程服务器。
• Maven 3.6+：用于项目构建和依赖管理。

2. 项目初始化

创建一个标准的 Spring Boot 项目，并在 pom.xml 中添加以下依赖：地定义一个消息监听器。

3. Producer 生产者

生产者（Producer）是 RocketMQ 中负责发送消息的角色。它将业务数据封装成消息，发送到 Broker 上的指定 Topic。RocketMQ 支持多种消息类型和发送方式，以满足不同场景的需求。

3.1 消息类型

RocketMQ 支持以下三种主要消息类型：

消息类型	说明	适用场景
普通消息（Normal）	无特殊语义，尽最大努力投递	日志收集、异步通知、数据同步
顺序消息（Ordered）	保证同一消息队列内的消息严格按发送顺序消费	订单状态流转、库存扣减
事务消息（Transactional）	实现分布式事务的最终一致性	跨系统数据一致性、支付回调

3.2 发送方式

RocketMQ 提供三种发送方式：

• 同步发送（Sync）：发送后等待 Broker 确认，可靠性最高，适用于重要业务消息。
• 异步发送（Async）：发送后立即返回，通过回调处理结果，适用于高吞吐场景。
• 单向发送（Oneway）：发送后不等待任何响应，吞吐量最高，适用于日志等不关心结果的场景。

3.3 创建生产者配置类

package icu.wzk;

import lombok.RequiredArgsConstructor;
import org.apache.rocketmq.spring.core.RocketMQTemplate;
import org.springframework.context.annotation.Configuration;

@Configuration
@RequiredArgsConstructor
public class WzkProducer {

    private final RocketMQTemplate rocketMQTemplate;

    /**
     * 发送普通消息（同步）
     * @param topic 目标 Topic
     * @param msg   消息内容
     */
    public void sendMessage(String topic, String msg){
        rocketMQTemplate.convertAndSend(topic, msg);
    }

    /**
     * 发送带 Tag 的消息
     * @param topic 目标 Topic
     * @param tag   消息 Tag，用于消费端过滤
     * @param msg   消息内容
     */
    public void sendMessageWithTag(String topic, String tag, String msg){
        rocketMQTemplate.convertAndSend(topic + ":" + tag, msg);
    }

}

3.4 关键说明

• @Configuration：将该类声明为 Spring 配置类，使其被 Spring 容器管理。
• @RequiredArgsConstructor：Lombok 注解，自动为 final 字段生成构造器注入。
• RocketMQTemplate：由 Starter 自动配置注入，封装了消息发送的底层逻辑。
• convertAndSend：将消息对象自动序列化并发送到指定 Topic。
• Tag 机制 ：通过 topic:tag 格式发送带 Tag 的消息，消费者可以只订阅特定 Tag，实现消息过滤。

3.5 使用示例

// 在任意 Service 或 Controller 中注入 WzkProducer
@Autowired
private WzkProducer wzkProducer;

public void demo() {
    // 发送普通消息
    wzkProducer.sendMessage("wzk-topic", "Hello RocketMQ!");

    // 发送带 Tag 的消息
    wzkProducer.sendMessageWithTag("wzk-topic", "order", "订单创建成功");
}

3.6 生产者配置详解

在 application.yml 中，可以为生产者配置更多参数：

rocketmq:
  name-server: 127.0.0.1:9876
  producer:
    group: wzk-producer-group   # 生产者组名称
    send-message-timeout: 3000   # 消息发送超时时间（毫秒），默认 3000
    compress-message-body-threshold: 4096  # 消息体压缩阈值（字节），超过则压缩
    max-message-size: 4194304    # 消息最大大小（字节），默认 4MB
    retry-times-when-send-failed: 2  # 同步发送失败重试次数，默认 2
    retry-times-when-send-async-failed: 2  # 异步发送失败重试次数，默认 2

注意：生产者组（producer group）用于标识同一类生产者的集合，在事务消息和回查机制中尤为重要。

4. Consumer 消费者

消费者（Consumer）负责从指定的 Topic 订阅并处理消息。RocketMQ 的消费者具有丰富的消费模式和高级特性，能够满足从简单到复杂的各种业务需求。

4.1 消费模式

RocketMQ 支持两种消费模式：

消费模式	说明	适用场景
集群消费（Clustering）	同一消费组内的多个消费者共同消费消息，每条消息只被其中一个消费者处理（默认）	负载均衡、水平扩展
广播消费（Broadcasting）	同一消费组内的每个消费者都会收到完整的消息	缓存更新、配置同步

4.2 消息过滤机制

消费者可以通过 Tag 和 SQL 表达式对消息进行过滤：

• Tag 过滤 ：在 @RocketMQMessageListener 中通过 selectorExpression 指定 Tag，支持 || 多 Tag 匹配。
• SQL 过滤 ：基于消息属性（Property）的 SQL92 表达式过滤，需 Broker 开启 enablePropertyFilter=true。

4.3 消费进度管理

• 自动提交（默认）：消费者定期自动提交消费进度，简单但可能重复消费。
• 手动提交 ：业务处理完成后手动调用 commit，精确控制消费进度，避免消息丢失。

4.4 创建消费者监听器

package icu.wzk;

import org.apache.rocketmq.spring.annotation.RocketMQMessageListener;
import org.apache.rocketmq.spring.core.RocketMQListener;
import org.springframework.stereotype.Component;

@Component
@RocketMQMessageListener(
    topic = "wzk-topic",
    consumerGroup = "wzk-consumer",
    selectorExpression = "*",  // 订阅所有 Tag，也可指定 "tag1 || tag2"
    consumeMode = ConsumeMode.CONCURRENTLY,  // 并发消费（默认），也可选 ORDERLY
    messageModel = MessageModel.CLUSTERING   // 集群消费（默认），也可选 BROADCASTING
)
public class WzkConsumer implements RocketMQListener<String> {

    @Override
    public void onMessage(String s) {
        System.out.println("wzk-consumer message: " + s);
        // 业务处理逻辑
    }
}

4.5 注解参数详解

参数	默认值	说明
topic	必填	监听的 Topic 名称
consumerGroup	必填	消费者组名称，同一消费组内的消费者共同消费消息
selectorExpression	*	Tag 过滤表达式，* 表示全部，`tag1
consumeMode	CONCURRENTLY	消费模式：CONCURRENTLY（并发）、ORDERLY（顺序）
messageModel	CLUSTERING	消息模型：CLUSTERING（集群）、BROADCASTING（广播）
consumeThreadNumber	64	消费线程数，影响消费并发度
maxReconsumeTimes	16	最大重试次数，超过则进入死信队列

4.6 顺序消费

当需要保证消息的顺序性时（如订单状态流转），使用 ConsumeMode.ORDERLY：

@Component
@RocketMQMessageListener(
    topic = "order-topic",
    consumerGroup = "order-consumer",
    consumeMode = ConsumeMode.ORDERLY  // 顺序消费
)
public class OrderConsumer implements RocketMQListener<OrderMessage> {

    @Override
    public void onMessage(OrderMessage msg) {
        // 同一订单的消息会按发送顺序依次处理
        processOrder(msg);
    }
}

注意：顺序消费会降低并发度，因为同一消息队列（MessageQueue）的消息会被串行处理。

4.7 重试机制与死信队列

• 重试机制：消息消费失败后，RocketMQ 会自动重试（默认最多 16 次），重试间隔逐渐增大。
• 死信队列 ：超过最大重试次数的消息会被投递到死信队列（DLQ），队列名为 %DLQ%consumerGroup，方便人工排查。

4.8 消费者配置

rocketmq:
  name-server: 127.0.0.1:9876
  consumer:
    group: wzk-consumer-group    # 消费者组名称
    consume-thread-min: 20       # 最小消费线程数
    consume-thread-max: 64       # 最大消费线程数
    consume-concurrently-max-span: 2000  # 并发消费最大跨度（毫秒）
    pull-interval: 0             # 拉取消息间隔（毫秒）
    pull-batch-size: 32          # 每次拉取的最大消息数

5.1 创建消费者监听器

package icu.wzk;

import org.apache.rocketmq.spring.annotation.RocketMQMessageListener;
import org.apache.rocketmq.spring.core.RocketMQListener;
import org.springframework.stereotype.Component;

@Component
@RocketMQMessageListener(topic = "wzk-topic", consumerGroup = "wzk-consumer")
public class WzkConsumer implements RocketMQListener<String> {

    @Override
    public void onMessage(String s) {
        System.out.println("wzk-consumer message: " + s);
    }
}

5.2 注解参数说明

参数	值	说明
topic	wzk-topic	监听的 Topic 名称，需与生产者发送的 Topic 一致
consumerGroup	wzk-consumer	消费者组名称，同一消费组内的消费者共同消费消息

5.3 消费模式

• 集群消费（默认）：同一消费组内的多个消费者共同消费消息，每条消息只被其中一个消费者处理。
• 广播消费 ：同一消费组内的每个消费者都会收到完整的消息。可通过 messageModel = MessageModel.BROADCASTING 配置。

6. App 启动类

最后，创建一个标准的 Spring Boot 启动类，用于启动整个应用。

package icu.wzk;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class WzkApp {
    public static void main(String[] args) {
        SpringApplication.run(WzkApp.class, args);
    }
}

启动应用后，RocketMQ 的自动配置会生效，RocketMQTemplate 和消费者监听器会自动注册到 Spring 容器中。

7. 配置文件

在 application.yml 或 application.properties 中配置 RocketMQ 的连接信息：

rocketmq:
  name-server: 127.0.0.1:9876  # NameServer 地址
  producer:
    group: wzk-producer-group   # 生产者组名称

8. 总结

通过以上步骤，我们成功在 Spring Boot 项目中集成了 RocketMQ，实现了消息的生产和消费。核心要点总结如下：

1. 添加依赖 ：引入 rocketmq-spring-boot-starter。
2. 配置连接 ：在 application.yml 中配置 NameServer 地址。
3. 发送消息 ：注入 RocketMQTemplate 并调用 convertAndSend。
4. 消费消息 ：实现 RocketMQListener 接口并使用 @RocketMQMessageListener 注解。

这种集成方式充分利用了 Spring Boot 的自动配置特性，让开发者可以专注于业务逻辑，无需关心 RocketMQ 客户端的底层细节。

---

错误速查卡

症状	根因	定位	修复
消息发送超时	NameServer 地址错误或 Broker 不可达	检查 rocketmq.name-server 配置，telnet 测试端口	确认 9876 端口可达，防火墙放行
消费者无法接收消息	Topic 或 ConsumerGroup 不一致	对比 Producer 和 Consumer 的 topic/consumerGroup 配置	确保两边配置完全一致
消息重复消费	自动提交模式下消费失败重试	检查消费逻辑是否幂等，开启手动提交	实现消费幂等，或切换为手动提交模式
顺序消息不保证	跨 MessageQueue 发送，使用了并发消费	检查是否使用 ConsumeMode.ORDERLY	生产端使用相同 hashKey 发送，消费端使用顺序模式
死信队列消息堆积	消费持续失败超过 maxReconsumeTimes	查看 %DLQ% 队列消息内容	修复消费逻辑，人工处理死信消息
事务消息回查失败	TransactionListener 实现错误或未正确注册	检查 TransactionListener 实现和注解	确保 executeLocalTransaction 返回正确的状态
消费者线程池耗尽	并发度过高，消息积压	观察消费延迟，检查 consumeThreadMax 配置	调低并发度，优化消费逻辑性能

---

其他系列

AI篇持续更新中（长期更新）

AI炼丹日志-29 - 字节跳动 Deer Flow 深度研究框架 私有部署 测试上手 架构研究 ，持续打造实用AI工具指南！
AI研究-132 Java 生态前沿 2025：Spring、Quarkus、GraalVM、CRaC 与云原生落地
AI模块直达链接

Java篇持续更新中（长期更新）

Java-216 RocketMQ 4.5.1 在 JDK9+ 从0到1全流程启动踩坑全解：脚本兼容修复（GC 参数/CLASSPATH/ext.dirs）

MyBatis 已完结，Spring 已完结，Nginx已完结，Tomcat已完结，分布式服务已完结，Dubbo已完结，MySQL已完结，MongoDB已完结，Neo4j已完结，FastDFS 已完结，OSS已完结，GuavaCache已完结，EVCache已完结，RabbitMQ已完结，RocketMQ正在更新... 深入浅出助你打牢基础！
Java模块直达链接

大数据板块已完成多项干货更新（300篇）

包括 Hadoop、Hive、Kafka、Flink、ClickHouse、Elasticsearch 等二十余项核心组件，覆盖离线+实时数仓全栈！
大数据-278 Spark MLib - 基础介绍 机器学习算法 梯度提升树 GBDT案例 详解
大数据模块直达链接

---

作者：武子康的个人博客