RocketMQ 顺序消息实现详解

原创于 2025-12-21 13:45:00 发布 · 685 阅读

15 ·

CC 4.0 BY-SA版权

文章标签：

#rocketmq #顺序消息

RocketMQ 专栏收录该内容

4 篇文章

订阅专栏

RocketMQ 顺序消息实现详解（原理 + 代码 + 踩坑）

目标：让你在真实项目里能稳定地用顺序消息，而不是“跑通 demo 就算完事”。
顺序消息的核心就一句话：让同一条业务链路的消息落到同一个队列，并保证该队列在同一时刻只被一个消费者串行处理。

1. 顺序消息到底保证了什么
2. RocketMQ 的顺序模型（Topic/Queue/Group）
3. 两种顺序：全局顺序 vs 分区顺序（你大概率只需要分区顺序）
4. Producer 端：如何“按业务键”选择同一个 Queue
5. Consumer 端：如何串行消费（MessageListenerOrderly）
- 5.1 Java SDK 示例：有序消费
- 5.2 失败重试与“暂停队列”机制
6. Spring Boot（rocketmq-spring）实现顺序消息
- 6.1 Producer：按 hashKey 路由
- 6.2 Consumer：顺序监听
7. 生产级最佳实践（非常重要）
8. 常见故障与排查清单
9. FAQ

1. 顺序消息到底保证了什么

RocketMQ 的“顺序”不是魔法，它保证的是：

同一个 MessageQueue 内：消息的投递顺序与写入顺序一致（在正常情况下）
同一个 Consumer Group 内：一个队列同一时刻只会分配给一个消费者实例进行消费（集群模式）

注意：RocketMQ 不会帮你保证“跨队列”的顺序，所以你必须自己决定哪些消息应该落到同一个队列里。

2. RocketMQ 的顺序模型（Topic/Queue/Group）

关键概念：

Topic：消息分类
MessageQueue：Topic 的分片（队列/分区）
Consumer Group：消费组，组内多个实例分担队列
Rebalance：组内实例变化时，队列会重新分配

顺序消息的“底层依赖”：

Producer：同一业务键（比如 orderId）→ 永远选择同一个队列
Consumer：对该队列串行消费（有序监听）
队列不被乱切：Rebalance / 重试 / 扩容都可能影响顺序稳定性（后面会讲怎么控）

3. 两种顺序：全局顺序 vs 分区顺序（你大概率只需要分区顺序）

3.1 全局顺序（不推荐，除非你非常确定）

定义：一个 Topic 只有 1 个队列（queueNum=1），所有消息都进这一个队列。
优点：简单，天然全局顺序。
缺点：吞吐/并发直接被“1 个队列”卡死，消费者无法并行扩展。

结论：除非业务量极小，或者真的必须严格全局顺序，否则别搞全局顺序。

3.2 分区顺序（推荐）

定义：Topic 有多个队列，通过 hash(orderId) 让同一个订单的消息进同一个队列。
效果：保证“同一订单内事件有序”，但不同订单之间可并行。

这基本就是电商/支付/履约里最常见的顺序消息形态。

4. Producer 端：如何“按业务键”选择同一个 Queue

4.1 原理：MessageQueueSelector

RocketMQ Java SDK 提供 MessageQueueSelector，允许你在发送时决定“这条消息进哪个队列”。

典型做法：用业务键（例如 orderId）做 hash，然后对队列数量取模：

int index = Math.abs(orderId.hashCode()) % mqs.size();
return mqs.get(index);

这样保证同一个 orderId 永远落到同一个队列（只要队列数不变）。

4.2 Java SDK 示例：订单维度顺序消息

Maven 依赖（示例）

<dependency>
  <groupId>org.apache.rocketmq</groupId>
  <artifactId>rocketmq-client</artifactId>
  <version>4.x/5.x</version>
</dependency>

Producer 代码（顺序发送）

import org.apache.rocketmq.client.producer.DefaultMQProducer;
import org.apache.rocketmq.client.producer.SendResult;
import org.apache.rocketmq.client.producer.SendStatus;
import org.apache.rocketmq.client.producer.selector.MessageQueueSelector;
import org.apache.rocketmq.common.message.Message;
import org.apache.rocketmq.common.message.MessageQueue;

import java.nio.charset.StandardCharsets;
import java.util.List;

public class OrderlyProducerDemo {

    public static void main(String[] args) throws Exception {
        DefaultMQProducer producer = new DefaultMQProducer("orderly_producer_group");
        producer.setNamesrvAddr("127.0.0.1:9876");
        producer.start();

        String topic = "topic_order_event";

        // 模拟同一订单的多个事件：CREATE -> PAY -> SHIP
        String orderId = "ORDER_10001";
        String[] events = {"CREATE", "PAY", "SHIP"};

        for (String event : events) {
            String body = orderId + ":" + event;
            Message msg = new Message(topic, "ORDER_TAG", orderId, body.getBytes(StandardCharsets.UTF_8));

            // 关键：用 orderId 选择同一队列
            SendResult result = producer.send(msg, new MessageQueueSelector() {
                @Override
                public MessageQueue select(List<MessageQueue> mqs, Message message, Object arg) {
                    String key = (String) arg; // orderId
                    int index = Math.abs(key.hashCode()) % mqs.size();
                    return mqs.get(index);
                }
            }, orderId);

            if (result.getSendStatus() != SendStatus.SEND_OK) {
                // 建议：打日志 + 告警 + 业务补偿（不要沉默失败）
                System.out.println("Send not OK: " + result);
            } else {
                System.out.println("Send OK: " + result);
            }
        }

        producer.shutdown();
    }
}

4.3 发送失败/重试策略（顺序消息的坑点）

顺序消息最大坑：失败重试可能让消息去到别的队列（取决于你的实现）。

建议：

你自己写的 MessageQueueSelector 必须是确定性的：同一个 key 永远算出同一个队列
发送失败时：
- 可以“重试同一个队列”（SDK 内部会做一些重试，但你更应该确保 selector 不变）
- 超过一定次数要落库/补偿（比如写本地表，异步任务重发），别一直无限重试

5. Consumer 端：如何串行消费（MessageListenerOrderly）

5.1 Java SDK 示例：有序消费

关键点：使用 MessageListenerOrderly，它是队列级别串行消费模型。

import org.apache.rocketmq.client.consumer.DefaultMQPushConsumer;
import org.apache.rocketmq.client.consumer.listener.ConsumeOrderlyContext;
import org.apache.rocketmq.client.consumer.listener.ConsumeOrderlyStatus;
import org.apache.rocketmq.client.consumer.listener.MessageListenerOrderly;
import org.apache.rocketmq.common.consumer.ConsumeFromWhere;
import org.apache.rocketmq.common.message.MessageExt;

import java.nio.charset.StandardCharsets;
import java.util.List;

public class OrderlyConsumerDemo {

    public static void main(String[] args) throws Exception {
        DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("orderly_consumer_group");
        consumer.setNamesrvAddr("127.0.0.1:9876");

        consumer.subscribe("topic_order_event", "*");
        consumer.setConsumeFromWhere(ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET);

        // 有序消费监听器
        consumer.registerMessageListener(new MessageListenerOrderly() {
            @Override
            public ConsumeOrderlyStatus consumeMessage(List<MessageExt> msgs, ConsumeOrderlyContext context) {
                context.setAutoCommit(true);

                for (MessageExt msg : msgs) {
                    String body = new String(msg.getBody(), StandardCharsets.UTF_8);
                    String orderId = msg.getKeys();
                    String queueId = String.valueOf(msg.getQueueId());

                    try {
                        // 你的业务逻辑：必须幂等（因为至少一次语义）
                        System.out.printf("queue=%s orderId=%s body=%s%n", queueId, orderId, body);

                        // TODO: do business
                    } catch (Exception e) {
                        // 暂停当前队列一会儿再重试（该队列后续消息会被卡住）
                        return ConsumeOrderlyStatus.SUSPEND_CURRENT_QUEUE_A_MOMENT;
                    }
                }

                return ConsumeOrderlyStatus.SUCCESS;
            }
        });

        consumer.start();
        System.out.println("Orderly consumer started.");
    }
}

5.2 失败重试与“暂停队列”机制

顺序消费的失败策略通常是：

暂停当前队列（默认有重试间隔）
再次消费失败消息
期间该队列后面的消息都会被阻塞

结论：

一条“毒消息”能把一个队列拖死。

应对：

超时控制、熔断降级
最大重试次数，超限进 DLQ
DLQ 必须有补偿方案

6. Spring Boot（rocketmq-spring）实现顺序消息

不同 starter API 名字可能略不同，但思路是固定的：

Producer：发送时带 hashKey/shardingKey，确保同 key 同队列
Consumer：使用 ORDERLY（顺序消费模式）

6.1 Producer：按 hashKey 路由（示意）

// 示意：常见的是 syncSendOrderly / sendOneWayOrderly 等
rocketMQTemplate.syncSendOrderly(
    "topic_order_event:ORDER_TAG",
    MessageBuilder.withPayload(payload).build(),
    orderId // hashKey
);

6.2 Consumer：顺序监听（示意）

@RocketMQMessageListener(
    topic = "topic_order_event",
    consumerGroup = "orderly_consumer_group",
    consumeMode = ConsumeMode.ORDERLY
)
public class OrderlyListener implements RocketMQListener<String> {
    @Override
    public void onMessage(String msg) {
        // 异常会触发重试，可能阻塞该队列
        handle(msg);
    }
}