RocketMQ 顺序消息实现详解

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

目标：让你在真实项目里能稳定地用顺序消息，而不是"跑通 demo 就算完事"。

顺序消息的核心就一句话：让同一条业务链路的消息落到同一个队列，并保证该队列在同一时刻只被一个消费者串行处理。

[1. 顺序消息到底保证了什么](#1. 顺序消息到底保证了什么)
[2. RocketMQ 的顺序模型（Topic/Queue/Group）](#2. RocketMQ 的顺序模型（Topic/Queue/Group）)
[3. 两种顺序：全局顺序 vs 分区顺序（你大概率只需要分区顺序）](#3. 两种顺序：全局顺序 vs 分区顺序（你大概率只需要分区顺序）)
[4. Producer 端：如何"按业务键"选择同一个 Queue](#4. Producer 端：如何“按业务键”选择同一个 Queue)
- [4.1 原理：MessageQueueSelector](#4.1 原理：MessageQueueSelector)
- [4.2 Java SDK 示例：订单维度顺序消息](#4.2 Java SDK 示例：订单维度顺序消息)
- [4.3 发送失败/重试策略（顺序消息的坑点）](#4.3 发送失败/重试策略（顺序消息的坑点）)
[5. Consumer 端：如何串行消费（MessageListenerOrderly）](#5. Consumer 端：如何串行消费（MessageListenerOrderly）)
- [5.1 Java SDK 示例：有序消费](#5.1 Java SDK 示例：有序消费)
- [5.2 失败重试与"暂停队列"机制](#5.2 失败重试与“暂停队列”机制)
[6. Spring Boot（rocketmq-spring）实现顺序消息](#6. Spring Boot（rocketmq-spring）实现顺序消息)
- [6.1 Producer：按 hashKey 路由](#6.1 Producer：按 hashKey 路由)
- [6.2 Consumer：顺序监听](#6.2 Consumer：顺序监听)
[7. 生产级最佳实践（非常重要）](#7. 生产级最佳实践（非常重要）)
[8. 常见故障与排查清单](#8. 常见故障与排查清单)
[9. FAQ](#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，然后对队列数量取模：

java 复制代码

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

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

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

Maven 依赖（示例）

xml 复制代码

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

Producer 代码（顺序发送）

java 复制代码

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，它是队列级别串行消费模型。

java 复制代码

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 路由（示意）

java 复制代码

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

6.2 Consumer：顺序监听（示意）

java 复制代码

@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);
    }
}

7. 生产级最佳实践（非常重要）

7.1 顺序粒度别搞太大

订单顺序：用 orderId 做 key ✅
全站顺序：Topic 一个队列 ❌

7.2 Topic 队列数要前期规划，别随便改

分区顺序常用 hash(key) % queueNum。

如果在线改队列数（queueNum 变了），同一个 key 的映射会变，顺序会乱。

建议：

队列数前期规划好
必须扩容时：用新 Topic 承接新链路（版本化 topic）更稳

7.3 必须幂等

顺序不等于不重复。RocketMQ 默认至少一次，重复投递很正常。

常见幂等：

去重表（DB/Redis）：msgKey + eventType
业务状态机：只允许合法状态迁移，非法直接忽略

7.4 控制毒消息影响

限制重试次数，超限进 DLQ
按可重试/不可重试分类
DLQ 要有处理入口（后台页面/自动修复任务）

7.5 控制 Rebalance 频率

频繁扩缩容会导致频繁 Rebalance → 延迟抖动。

顺序消费不适合"疯狂弹性伸缩"。

8. 常见故障与排查清单

同一订单消息顺序乱了

Producer 是否真的用 orderId 选同一队列
Topic 队列数是否改过
是否发到多个 Topic（或者 tag 过滤导致你误判）

消费卡住不动

是否有异常反复重试
DLQ/Retry 是否堆积
外部依赖是否超时导致一直暂停队列

吞吐太低

是否用了全局顺序（1 队列）
顺序 key 是否过于集中（热 key）
优化：拆分 key 粒度或拆 Topic

9. FAQ

Q1：RocketMQ 能保证严格强顺序吗？

在"单队列 + 单消费者"最接近强顺序。现实里还会遇到重试、超时、补偿、Rebalance。

最靠谱：分区顺序 + 业务状态机兜底。

Q2：能在线加队列又不乱顺序吗？

默认 hash%N 会乱。要不乱就得做固定映射/版本化 topic。

建议：别在线改队列数，或者用新 Topic 平滑迁移。

一句话总结

顺序消息 = 稳定路由（同 key 同队列） + 串行消费（队列级） + 幂等兜底 + 控制毒消息 。

把这四件事做扎实，线上就稳。

RocketMQ 顺序消息实现详解