Why Use RocketMQ with Spring Boot? A Complete Integration Guide

1. Why Use MQ?

Even though Spring Boot Event can achieve in‑process event‑driven decoupling via Guava or Spring’s own listeners, the events remain within the same JVM, so only the current process can consume them. Using a message queue pushes events to an external broker, enabling consumption across multiple instances or distributed services, maximizing idle service utilization.

Source code repository: https://gitee.com/sparkle3021/springboot3-study

2. Integrating RocketMQ

Dependency Versions

JDK 17

Spring Boot 3.2.0

RocketMQ-Client 5.0.4

RocketMQ-Starter 2.2.0

Spring Boot 3.x no longer supports spring.factories, so the RocketMQ configuration class must be imported manually.

Adding RocketMQ Dependencies

<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-client-java</artifactId>
    <version>5.0.4</version>
</dependency>
<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-spring-boot-starter</artifactId>
    <version>2.2.0</version>
</dependency>

Resolving Spring Boot 3 incompatibility with spring.factories

In rocketmq-spring-boot-starter:2.2.2 the auto‑configuration is provided via META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports containing org.apache.rocketmq.spring.autoconfigure.RocketMQAutoConfiguration. You can either import this class with @Import(RocketMQAutoConfiguration.class) or create the file under resources/META-INF/spring/.

3. RocketMQ Usage

Configuration File

# RocketMQ configuration
rocketmq:
  name-server: 127.0.0.1:9876
  consumer:
    group: event-mq-group
    pull-batch-size: 1
  producer:
    group: event-mq-group
    sendMessageTimeout: 10000
    retryTimesWhenSendFailed: 2
    retryTimesWhenSendAsyncFailed: 2
    maxMessageSize: 4096
    compressMessageBodyThreshold: 4096
    retryNextServer: false

RocketMQ Message Entity

import cn.hutool.core.util.IdUtil;
import jakarta.validation.constraints.NotBlank;
import lombok.*;
import java.io.Serializable;
import java.util.List;
/**
 * RocketMQ message wrapper
 */
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class RocketMQMessage<T> implements Serializable {
    @NotBlank(message = "MQ Topic cannot be empty")
    private String topic;
    @Builder.Default
    private DelayLevel delayLevel = DelayLevel.OFF;
    private T message;
    private List<T> messages;
    private String hashKey;
    @Builder.Default
    private String taskId = IdUtil.fastSimpleUUID();
}

RocketMQ Service (Producer)

... (producer code from source) ...

Consumer Definition

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

@Component
@RocketMQMessageListener(topic = MQConfig.EVENT_TOPIC, consumerGroup = MQConfig.EVENT_CONSUMER_GROUP)
public class MQListener implements RocketMQListener<String> {
    @Override
    public void onMessage(String message) {
        log.info("MQListener received message: {}", message);
    }
}

Test Class

... (test code from source) ...

4. Testing

Run the test to send multiple messages and observe consumption.