```mdk height=520 color=#4f46e5
# RocketMQ 使用与接入
## 是什么
### 阿里开源,后捐给 Apache,Java 编写
### NameServer 注册中心 + Broker 存储转发
### 强项:事务消息、延时/定时消息、消息回溯
### 典型场景:订单、支付、削峰、异步解耦
## 两代架构
### 4.x:Remoting 私有协议
- 客户端连 NameServer:9876
- 再直连 Broker:10911
- Java 客户端 rocketmq-client
### 5.x:Proxy + gRPC
- 客户端只连 Proxy:8081
- Proxy 代理 NameServer 与 Broker
- 官方多语言客户端统一走 gRPC
- 服务端仍兼容 4.x 老客户端
## 部署
### 4.x 二进制:mqnamesrv + mqbroker
### 5.x 容器:namesrv + broker + proxy
### 控制台:rocketmq-dashboard
## 四种接入方式
### Java 4.x remoting
### Java 5.x gRPC
### Spring Boot(rocketmq-spring-boot-starter)
### Go / Python / C++ / Node.js 客户端
## 消息类型
- 普通消息
- 顺序消息(队列级有序)
- 延时/定时消息
- 事务消息
- 批量消息
- Tag / SQL92 过滤
## 可靠性与运维
- 主从复制、flushDiskType
- 消费重试 %RETRY%group
- 死信队列 %DLQ%group
- 消费端幂等
- mqadmin 常用命令
## 常见坑
- brokerIP1 要配对外 IP
- No route info of this topic
- 发送超时多为 10911 不通
- 内存不足导致启动失败
```
===== 一、RocketMQ 是什么 =====
RocketMQ 最早由阿里内部研发(前身 MetaQ),2016 年捐给 Apache 基金会,现为 Apache 顶级项目。纯 Java 实现,特点是**高吞吐 + 低延迟 + 功能丰富**:事务消息、延时/定时消息、消息回溯、Tag/SQL92 过滤都是原生能力。
^ 组件 ^ 作用 ^
| NameServer | 无状态注册中心,Broker 向它注册、客户端向它拉路由;生产环境一般部署 2~3 台 |
| Broker | 真正存消息、转发消息的节点,启动时向所有 NameServer 注册 |
| Topic | 逻辑上的消息分类,内部再切成多个 Queue(默认 4 个) |
| Producer / Consumer Group | 生产者组 / 消费者组;组内负载均衡,组间各得一份 |
四个招牌能力(也是它相对 Kafka 的差异点):
* **事务消息**:半消息 + 本地事务回查,解决「发消息」和「写数据库」的一致性问题。
* **延时 / 定时消息**:4.x 支持 18 个固定延时级别,5.x 支持任意时间戳。
* **消息回溯**:按时间戳重置消费位点(''resetOffsetByTime''),可重新消费历史消息,业务侧比改 offset 友好。
* **丰富的过滤**:Tag 过滤、SQL92 属性过滤,在 Broker 端就把不需要的消息筛掉。
===== 二、4.x 与 5.x 的核心区别 =====
一句话:**5.x = 4.x 的存储内核 + 新增 Proxy 统一入口 + gRPC 协议**。服务端换了架构,老客户端不改代码也能用。
^ 对比项 ^ 4.x ^ 5.x ^
| 通信协议 | Remoting(自定义 TCP 协议) | gRPC(新客户端)+ Remoting(兼容老客户端) |
| 客户端连接目标 | 先连 NameServer:9876 拿路由,再直连 Broker:10911 | 只连 Proxy 的 8081,由 Proxy 转发 |
| 官方 Java 客户端 | ''org.apache.rocketmq:rocketmq-client'' | ''rocketmq-client-java''(gRPC);''rocketmq-client'' 5.x 仍可用 |
| 多语言客户端 | C++ / Go / Python,各基于 remoting 或 C++ 内核 | 官方统一 gRPC 客户端:Java / C++ / Go / Rust / Python |
| 延时消息 | 固定 18 级(1s 5s 10s 30s 1m … 2h) | 任意时间戳,精度秒级 |
| 消费模式 | Push(''DefaultMQPushConsumer'')/ Pull | PushConsumer / SimpleConsumer(显式 ack)/ POP 模式 |
| 扩缩容表现 | 消费者按队列重平衡,扩容时可能短暂重复消费 | POP 模式把重平衡放到 Broker 侧,扩缩容更平滑 |
| 运维入口 | mqadmin 命令行 + rocketmq-console | mqadmin + Proxy 管理接口 + rocketmq-dashboard |
| 兼容性 | — | 5.x 服务端同时开 remoting(10911)与 gRPC(8081),4.x 客户端可继续接 |
**怎么选**:
* 老项目、已有 4.x 客户端、Spring Boot 老版本 starter —— 继续走 remoting,服务端升到 5.x 也能跑。
* 新项目、多语言团队(Go / Rust / Python)、需要任意时刻定时消息 —— 直接上 5.x Proxy + gRPC 客户端。
* 4.x 客户端要连 5.x 集群时,Proxy 需要保留 remoting 兼容(配置项在 ''conf/rmq-proxy.json'' 里,例如 ''enableRemotingAccess'',键名以所用版本为准),否则老客户端连不上。
== 端口速记 ==
^ 端口 ^ 用途 ^
| 9876 | NameServer(4.x 客户端连这个) |
| 10911 | Broker 主服务端口(客户端收发消息) |
| 10909 | Broker VIP / fast-remoting 通道 |
| 8080 | 5.x Proxy 的 HTTP 接口 / 管理端口 |
| 8081 | 5.x Proxy 的 gRPC 端口(新客户端连这个) |
| 8082 | rocketmq-dashboard 示例端口 |
===== 三、部署 =====
== 3.1 老版本:4.x 二进制包(最经典) ==
wget https://archive.apache.org/dist/rocketmq/4.9.7/rocketmq-all-4.9.7-bin-release.zip
unzip rocketmq-all-4.9.7-bin-release.zip && cd rocketmq-all-4.9.7-bin-release
# 1) 改内存:默认要 4G/8G,小机器必须调小,否则起不来
vi bin/runserver.sh # -Xms512m -Xmx512m -Xmn256m
vi bin/runbroker.sh # -Xms1g -Xmx1g
# 2) Broker 配置 conf/broker.conf
brokerClusterName = DefaultCluster
brokerName = broker-a
brokerId = 0
namesrvAddr = 127.0.0.1:9876
brokerIP1 = 192.168.1.10 # 关键:客户端最终连这个 IP,容器/云主机必须显式指定
listenPort = 10911
deleteWhen = 04
fileReservedTime = 48
brokerRole = ASYNC_MASTER
flushDiskType = ASYNC_FLUSH
autoCreateTopicEnable = true # 生产环境建议 false,改为手工建 Topic
# 3) 启动
nohup sh bin/mqnamesrv & # NameServer
nohup sh bin/mqbroker -c conf/broker.conf & # Broker
# 4) 验证
sh bin/mqadmin clusterList -n 127.0.0.1:9876
控制台(可选):
docker run -d --name rocketmq-dashboard -p 8082:8080 \
-e "JAVA_OPTS=-Drocketmq.namesrv.addr=127.0.0.1:9876" \
apacherocketmq/rocketmq-dashboard:latest
== 3.2 新版本:5.x(namesrv + broker + proxy 三角色) ==
生产建议三个角色分开部署;开发环境可以让 Broker 内嵌 Proxy(Local 模式)。
# NameServer
docker run -d --name rmqnamesrv -p 9876:9876 \
-e "JAVA_OPT_EXT=-Xms512m -Xmx512m" \
apache/rocketmq:5.3.1 sh mqnamesrv
# Broker(指向 NameServer)
docker run -d --name rmqbroker --link rmqnamesrv:namesrv \
-p 10911:10911 -p 10909:10909 \
-e "NAMESRV_ADDR=namesrv:9876" \
-e "JAVA_OPT_EXT=-Xms1g -Xmx1g" \
apache/rocketmq:5.3.1 sh mqbroker -c /home/rocketmq/conf/broker.conf
# Proxy(客户端连它的 8081)
docker run -d --name rmqproxy --link rmqnamesrv:namesrv \
-p 8080:8080 -p 8081:8081 \
-e "NAMESRV_ADDR=namesrv:9876" \
apache/rocketmq:5.3.1 sh mqproxy
要点:
* 新客户端连的是 **Proxy 的 8081**,不是 NameServer 的 9876,这是新老接入最大的差别。
* ''brokerIP1'' 依然要填对外真实 IP,否则 Proxy 会把内网地址回给客户端,报连接超时。
* Proxy 的配置在 ''conf/rmq-proxy.json''(''namesrvAddr''、''grpcServerPort'' 等)。
* 用云上托管版时,控制台给出的「接入点」就是 Proxy 的 endpoints,直接交给第 5 节的 gRPC 客户端。
===== 四、接入方式一:Java 4.x(remoting,连 9876) =====
依赖:
org.apache.rocketmq
rocketmq-client
4.9.7
== 生产者 ==
DefaultMQProducer producer = new DefaultMQProducer("pg_order"); // 生产者组
producer.setNamesrvAddr("192.168.1.10:9876");
producer.setSendMsgTimeout(3000);
producer.setRetryTimesWhenSendFailed(2);
producer.start(); // 只启动一次,务必全应用复用
Message msg = new Message(
"topic_order", // topic
"PAID", // tag
"orderId=A1001", // keys,便于控制台按消息查询
"{\"orderId\":\"A1001\",\"amount\":99.5}".getBytes(StandardCharsets.UTF_8));
SendResult sr = producer.send(msg); // 同步发送
System.out.println(sr.getSendStatus() + " / " + sr.getMsgId());
// 异步:producer.send(msg, new SendCallback(){ onSuccess / onException });
// 单向:producer.sendOneway(msg); (不关心结果,吞吐最高)
// 批量:producer.send(Collection) (同 topic,总大小不超过 4MB)
// 指定队列:producer.send(msg, new MessageQueueSelector(){...}, arg) → 顺序消息用
producer.shutdown();
== 消费者(Push 模式,最常用) ==
DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("cg_order");
consumer.setNamesrvAddr("192.168.1.10:9876");
consumer.subscribe("topic_order", "PAID || REFUND"); // Tag 过滤;"*" 表示全部
consumer.setConsumeFromWhere(ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET);
consumer.setConsumeThreadMin(10);
consumer.setConsumeThreadMax(20);
consumer.setMaxReconsumeTimes(16); // 超过次数进死信队列
consumer.registerMessageListener((MessageListenerConcurrently) (msgs, ctx) -> {
for (MessageExt m : msgs) {
try {
handle(new String(m.getBody(), StandardCharsets.UTF_8));
} catch (Exception e) {
return ConsumeConcurrentlyStatus.RECONSUME_LATER; // 稍后重试
}
}
return ConsumeConcurrentlyStatus.CONSUME_SUCCESS; // 成功才提交位点
});
consumer.start();
== 顺序消息 ==
同一订单的消息必须落进同一个队列,消费端用 ''MessageListenerOrderly'':
// 生产端:按业务主键选队列
producer.send(msg, (mqs, m, arg) ->
mqs.get(Math.abs(arg.hashCode()) % mqs.size()), "A1001");
// 消费端:顺序监听器
consumer.registerMessageListener((MessageListenerOrderly) (msgs, ctx) -> {
// 暂时无法处理时返回这个状态,而不是无限阻塞
// return ConsumeOrderlyStatus.SUSPEND_CURRENT_QUEUE_A_MOMENT;
return ConsumeOrderlyStatus.SUCCESS;
});
== 延时消息(4.x 固定 18 级) ==
msg.setDelayTimeLevel(5); // 级别:1s 5s 10s 30s 1m 2m 3m 4m 5m 6m 7m 8m 9m 10m 20m 30m 1h 2h
// level=5 → 1m,level=17 → 2h
== 事务消息 ==
TransactionMQProducer producer = new TransactionMQProducer("pg_tx");
producer.setNamesrvAddr("192.168.1.10:9876");
producer.setExecutorService(Executors.newFixedThreadPool(8)); // 回查线程池
producer.setTransactionListener(new TransactionListener() {
@Override
public LocalTransactionState executeLocalTransaction(Message msg, Object arg) {
try {
orderService.create((String) arg); // 本地事务:写库
return LocalTransactionState.COMMIT_MESSAGE;
} catch (Exception e) {
return LocalTransactionState.ROLLBACK_MESSAGE;
}
}
@Override
public LocalTransactionState checkLocalTransaction(MessageExt msg) {
// Broker 回查本地事务状态,必须能查到真实结果
return orderService.exists(msg.getKeys())
? LocalTransactionState.COMMIT_MESSAGE
: LocalTransactionState.ROLLBACK_MESSAGE;
}
});
producer.start();
producer.sendMessageInTransaction(msg, "A1001"); // 先发半消息,再回调本地事务
===== 五、接入方式二:Java 5.x(gRPC,连 8081) =====
依赖(JDK 8+):
org.apache.rocketmq
rocketmq-client-java
5.0.7
== 客户端配置与生产者 ==
ClientServiceProvider provider = ClientServiceProvider.loadService();
ClientConfiguration cfg = ClientConfiguration.newBuilder()
.setEndpoints("192.168.1.10:8081") // Proxy 的 gRPC 端口,多个用分号隔开
// 开启 ACL 时:
// .setCredentialProvider(SessionCredentialsProvider.newBuilder()
// .setAccessKey("ak").setAccessSecret("sk").build())
.build();
Producer producer = provider.newProducerBuilder()
.setClientConfiguration(cfg)
.setTopics("topic_order") // 前置声明用到的 topic
.build();
Message msg = provider.newMessageBuilder()
.setTopic("topic_order")
.setTag("PAID")
.setKeys("A1001")
.setBody("{\"orderId\":\"A1001\"}".getBytes(StandardCharsets.UTF_8))
// 定时消息(5.x 新能力,任意时刻,精度秒级)
// .setDeliveryTimestamp(System.currentTimeMillis() + 60_000L)
.build();
SendReceipt receipt = producer.send(msg);
System.out.println(receipt.getMessageId());
// 异步:producer.sendAsync(msg) → CompletableFuture
producer.close(); // 实现 Closeable
== PushConsumer(推荐,框架自动 ack) ==
PushConsumer consumer = provider.newPushConsumerBuilder()
.setClientConfiguration(cfg)
.setConsumerGroup("cg_order")
.setSubscriptionExpressions(Collections.singletonMap("topic_order", "*"))
.setMessageListener(messageView -> {
try {
handle(messageView.getBody().toString(StandardCharsets.UTF_8));
return ConsumeResult.SUCCESS;
} catch (Exception e) {
return ConsumeResult.FAILURE; // 触发重试,超限进死信
}
})
.build();
== SimpleConsumer(拉模式,显式 ack,适合批量与自定义流控) ==
SimpleConsumer consumer = provider.newSimpleConsumerBuilder()
.setClientConfiguration(cfg)
.setConsumerGroup("cg_order_pull")
.setAwaitDuration(java.time.Duration.ofSeconds(15))
.setSubscriptionExpressions(Collections.singletonMap("topic_order", "*"))
.build();
List msgs = consumer.receive(32, java.time.Duration.ofSeconds(15));
for (MessageView m : msgs) {
process(m);
consumer.ack(m); // 处理成功才 ack;也可 changeInvisibleDuration 延长不可见时间
}
== 事务消息(5.x 写法更简洁) ==
Producer producer = provider.newProducerBuilder()
.setClientConfiguration(cfg)
.setTopics("topic_order")
.setTransactionChecker(messageView -> TransactionResolution.COMMIT) // 回查逻辑
.build();
Transaction transaction = producer.beginTransaction();
producer.send(transaction, msg);
transaction.commit(); // 本地事务成功则 commit,失败则 transaction.rollback()
== 4.x → 5.x API 映射速查 ==
^ 能力 ^ 4.x remoting ^ 5.x gRPC ^
| 入口配置 | ''setNamesrvAddr("ip:9876")'' | ''ClientConfiguration#setEndpoints("ip:8081")'' |
| 生产者 | ''DefaultMQProducer'' | ''ClientServiceProvider#newProducerBuilder'' |
| 推消费 | ''DefaultMQPushConsumer'' + Listener | ''newPushConsumerBuilder'' + MessageListener |
| 拉消费 | ''DefaultMQPullConsumer''(API 繁琐) | ''newSimpleConsumerBuilder'' + ''receive / ack'' |
| 发送结果 | ''SendResult'' | ''SendReceipt'' |
| 延时消息 | ''setDelayTimeLevel(int)'' | ''setDeliveryTimestamp(long)'' |
| 事务消息 | ''TransactionMQProducer'' + TransactionListener | ''beginTransaction / commit / rollback'' + TransactionChecker |
| 日志 | 自带 logback 配置 | 需自行引入 slf4j 实现,否则启动报错 |
| 资源释放 | ''shutdown()'' | ''close()'' |
===== 六、接入方式三:Spring Boot =====
org.apache.rocketmq
rocketmq-spring-boot-starter
2.3.1
rocketmq.name-server=192.168.1.10:9876
rocketmq.producer.group=pg_order
rocketmq.producer.send-message-timeout=3000
# 开启 ACL 时再填
# rocketmq.producer.access-key=
# rocketmq.producer.secret-key=
发送(''RocketMQTemplate'',topic 与 tag 用冒号分隔):
@Resource
private RocketMQTemplate rocketMQTemplate;
public void pay(String payload) {
// 同步
SendResult r = rocketMQTemplate.syncSend("topic_order:PAID", payload);
// 异步
rocketMQTemplate.asyncSend("topic_order:PAID", payload, new SendCallback() {
@Override public void onSuccess(SendResult sendResult) { }
@Override public void onException(Throwable e) { }
});
// 单向
rocketMQTemplate.sendOneWay("topic_order:LOG", "click");
// 顺序消息:第三个参数是 hashKey
rocketMQTemplate.syncSendOrderly("topic_order:PAID", payload, "A1001");
// 延时消息:最后一个参数是 4.x 的延时级别
rocketMQTemplate.syncSend("topic_order:PAID",
MessageBuilder.withPayload(payload).build(), 3000, 5);
}
消费:
@Service
@RocketMQMessageListener(
topic = "topic_order",
consumerGroup = "cg_order",
selectorExpression = "PAID",
consumeMode = ConsumeMode.ORDERLY) // 默认 CONCURRENTLY
public class OrderConsumer implements RocketMQListener {
@Override
public void onMessage(String body) {
// 正常返回即消费成功;抛异常会触发重试
}
}
===== 七、接入方式四:Go / Python / C++ / Node.js =====
^ 语言 ^ 4.x(remoting) ^ 5.x(gRPC) ^
| Go | ''github.com/apache/rocketmq-client-go/v2'' | ''github.com/apache/rocketmq-clients/golang/v5'' |
| Python | ''pip install rocketmq-client-python''(C++ 内核) | apache/rocketmq-clients 的 python 目录(gRPC,需自行装 grpcio 依赖) |
| C++ | ''rocketmq-client-cpp'' | ''rocketmq-client-cpp'' 的 5.x 分支(gRPC) |
| Rust | ''rocketmq-client-rust''(4.x 内核) | ''rocketmq-client-rust'' 的 5.x 分支(gRPC) |
| Node.js | ''rocketmq-client-nodejs''(C++ 绑定,连 9876,已少维护) | **无官方客户端**:用 ''@grpc/grpc-js'' 自行直连 Proxy,或走 Go/Python sidecar(见下) |
Go(4.x 风格):
p, _ := rocketmq.NewProducer(
producer.WithNameServer([]string{"192.168.1.10:9876"}),
producer.WithGroupName("pg_order"),
producer.WithRetry(2))
_ = p.Start()
res, err := p.SendSync(context.Background(), &primitive.Message{
Topic: "topic_order",
Body: []byte("hello"),
})
_ = res
_ = err
defer p.Shutdown()
Go(5.x gRPC 风格):
producer, _ := golang.NewProducer(&golang.Config{
Endpoint: "192.168.1.10:8081",
Credentials: credentials.NewCredentials("", ""),
}, golang.WithTopics("topic_order"))
_ = producer.Start()
resp, err := producer.Send(context.Background(), &golang.Message{
Topic: "topic_order",
Body: []byte("hello"),
})
_ = resp
_ = err
// defer producer.GracefulStop()
Python(4.x 风格):
from rocketmq.client import Producer, Message
producer = Producer('pg_order')
producer.set_name_server_address('192.168.1.10:9876')
producer.start()
msg = Message('topic_order')
msg.set_keys('A1001')
msg.set_tags('PAID')
msg.set_body('{"orderId":"A1001"}')
producer.send_sync(msg)
producer.shutdown()
== Node.js 接 5.x gRPC:官方没客户端,两条路 ==
先把现状说清楚:官方 ''rocketmq-clients'' 覆盖 Java / C++ / C# / Go / Rust / Python 等语言,**Node.js 一直是个空缺**;能搜到的 ''rocketmq-client-nodejs'' 是 4.x 时代的 C++ 绑定(连 NameServer 9876,走 remoting),早已停止更新,接不了 5.x Proxy。所以 Node 侧只有下面两条路。
=== 路径 A:用 @grpc/grpc-js 直连 Proxy 的 8081 ===
原理:Proxy 对外暴露的就是标准 gRPC 服务 ''apache.rocketmq.v2.MessagingService'',只要有官方 proto,Node 自己也能当客户端。
npm i @grpc/grpc-js @grpc/proto-loader
# 从 apache/rocketmq-clients 仓库把 proto 目录拷到本地,例如:
# proto/apache/rocketmq/v2/definition.proto
# proto/apache/rocketmq/v2/service.proto
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const def = protoLoader.loadSync('proto/apache/rocketmq/v2/service.proto', {
includeDirs: ['proto'],
keepCase: false, // 生成驼峰方法名 sendMessage / receiveMessage
longs: String,
enums: String,
defaults: true,
oneofs: true,
});
const { apache } = grpc.loadPackageDefinition(def);
// 关键:这里填 Proxy 的 8081,不是 NameServer 的 9876
const client = new apache.rocketmq.v2.MessagingService(
'192.168.1.10:8081',
grpc.credentials.createInsecure(), // 托管版 / 开 TLS 时换成 createSsl(...)
{ 'grpc.keepalive_time_ms': 30000, 'grpc.keepalive_timeout_ms': 10000 }
);
function send(body, tag, keys) {
return new Promise((resolve, reject) => {
client.sendMessage({
messages: [{
topic: 'topic_order', // 字段名请以你手上的 proto 为准
systemProperties: { tag, keys }, // tag / keys 属于系统属性
body: Buffer.from(body, 'utf8'),
}],
}, (err, resp) => (err ? reject(err) : resolve(resp.entries)));
});
}
send('{"orderId":"A1001"}', 'PAID', 'A1001')
.then(entries => console.log(JSON.stringify(entries)))
.catch(console.error);
动手前必须知道的几点:
* **Message 结构动过**:''topic'' / ''tag'' / ''keys'' 是顶层字段还是塞在 ''systemProperties'' 里,5.0 前后调整过,务必对着本地 proto 文件核对字段名,不要照抄旧博客。
* **心跳不能省**:官方 SDK 会周期性发 ''TelemetryCommand''(上报 settings、线程栈)和 ''Heartbeat''。只调 ''SendMessage'' 在部分版本上看着能用,但 Proxy 会把没有存活信号的连接当异常客户端清理,表现为随机超时、偶发失败,生产环境务必补齐。
* **消费端远比发送麻烦**:POP 消费要自己维持 ''ReceiveMessage'' 长轮询、调 ''AckMessage''、管理不可见时间(invisibleDuration)与重试/死信,还要处理连接重建。手写这一套性价比很低。
* **ACL**:开启鉴权后必须在 gRPC metadata 里带签名头(AK/SK 按官方 SDK 的签名算法算),否则 Proxy 直接拒绝请求。
* **升级代价**:官方 proto 不承诺向后兼容,Proxy 升级后自维护的 stub 可能要跟着改 —— 这正是路径 B 存在的理由。
=== 路径 B:Go / Python sidecar(生产推荐) ===
用官方 Go(''github.com/apache/rocketmq-clients/golang/v5'')或 Python 客户端跑一个极小的网关进程,对外只暴露 HTTP / gRPC,Node 侧调网关:
Node 业务进程 --HTTP/gRPC--> sidecar(官方 Go/Python 客户端) --gRPC 8081--> Proxy
* 好处:协议、心跳、重试、ACK、死信全交给官方 SDK,Node 只写业务;SDK 升级只动 sidecar,不用维护 proto stub。
* 代价:多一个常驻进程,部署、监控、超时与错误透传要一起设计。
* 什么时候值得:只要这条链路要进生产,就值得。团队里 Go / Java 更熟的话,投入产出比比在 Node 里手写协议高得多。
选型建议:多语言团队优先用 5.x 的 gRPC 客户端,接口在各语言间基本一致;**Node.js 没有官方客户端**,生产链路建议用 Go/Python sidecar 包住协议细节,而不是长期自己维护 gRPC stub;4.x 时代的 Python/Node 客户端维护活跃度较低,新项目不建议依赖。
===== 八、消息类型对照 =====
^ 类型 ^ 4.x 写法 ^ 5.x 写法 ^ 注意点 ^
| 普通消息 | ''send / sendAsync / sendOneway'' | 同样三种 | 核心链路用同步发送并配重试,别用单向 |
| 顺序消息 | 手动选队列 + Orderly 监听器 | PushConsumer 分区顺序消费 | 只在同一 Queue 内有序,选队列的 key 必须是业务主键 |
| 延时消息 | ''setDelayTimeLevel(1~18)'' | ''setDeliveryTimestamp'' | 5.x 可定时到任意时刻 |
| 事务消息 | 半消息 + 本地事务回查 | ''beginTransaction / commit / rollback'' | 回查有次数上限,回查逻辑必须能查到真实状态 |
| 批量消息 | ''send(List)'' | 客户端批量发送接口 | 同 topic、总大小不超过 4MB;批量不等于事务 |
| 过滤 | Tag 过滤(多 Tag 用两条竖线连接)、SQL92 | 同左 | 过滤表达式写在订阅方法里,注意转义 |
===== 九、运维与排错 =====
''bin/mqadmin'' 在 4.x / 5.x 上通用,常用命令:
# 集群与 Topic
sh bin/mqadmin clusterList -n 127.0.0.1:9876
sh bin/mqadmin topicList -n 127.0.0.1:9876 -c DefaultCluster
sh bin/mqadmin topicRoute -n 127.0.0.1:9876 -t topic_order
sh bin/mqadmin updateTopic -n 127.0.0.1:9876 -c DefaultCluster -t topic_order -r 8 -w 8
sh bin/mqadmin deleteTopic -n 127.0.0.1:9876 -c DefaultCluster -t topic_order
# 消费情况与位点
sh bin/mqadmin consumerProgress -n 127.0.0.1:9876 -g cg_order
sh bin/mqadmin consumerStatus -n 127.0.0.1:9876 -g cg_order
sh bin/mqadmin resetOffsetByTime -n 127.0.0.1:9876 -g cg_order -t topic_order -s now
# 手工发一条测试消息
sh bin/mqadmin sendMessage -n 127.0.0.1:9876 -t topic_order -p "hello"
5.x 还可以配合 Proxy 的管理接口和 rocketmq-dashboard 使用。
排查清单(按出现频率排序):
* ''sendDefaultImpl call timeout'':客户端到 Broker 的 **10911** 不通,多为安全组/防火墙未放行,或 ''brokerIP1'' 填了内网地址。
* ''No route info of this topic'':NameServer 上没有该 Topic 的路由。生产环境 ''autoCreateTopicEnable=false'' 时需先 ''updateTopic'' 手工创建。
* 4.x 客户端连 5.x 连不上:Proxy 未保留 remoting 兼容,或客户端仍指向已关闭的 9876。
* 5.x 新客户端连不上:''endpoints'' 必须填 Proxy 的 **8081**,填 9876 一定失败。
* Broker 启动即 OOM:默认 ''runbroker.sh'' 需要大内存,小机器必须调小 ''-Xmx''。
* 消费堆积:看 ''consumerProgress'' 的 diff;先确认消费者是否在线(''consumerStatus'' 里的 ''notOnline''),再考虑加实例(实例数超过队列数没有意义)。
* 消息重复:默认至少一次语义,别指望 MQ 去重,消费端必须幂等。
===== 十、可靠性要点 =====
* **刷盘**:''flushDiskType=ASYNC_FLUSH'' 性能好、断电可能丢少量消息;''SYNC_FLUSH'' 更安全但 TPS 下降。
* **主从**:''ASYNC_MASTER'' 主挂掉可能有少量未同步消息丢失;''SYNC_MASTER''(同步双写)不丢消息但 RT 上升。5.x 可用 DLedger / Controller 模式做主备自动切换。
* **消费重试**:并发消费失败会重试(默认 16 次),消息进入 ''%RETRY%消费组名'' 的 Topic,以递增间隔重投;超过次数后进入 ''%DLQ%消费组名'' 死信队列,死信必须有人工处理入口。
* **幂等**:用业务唯一 ID(订单号 + 事件类型)做 Redis 或数据库唯一键去重,这是应对「至少一次」的标准做法。
* **不丢消息的三道关**:生产端同步发送 + 失败重试;Broker 端同步刷盘 / 主从可靠;消费端处理成功才 ack。
* **顺序**:顺序消费要求消息进同一队列且消费端单线程(''MessageListenerOrderly'');生产端按业务键 hash 选队列,扩容队列会破坏既有顺序。
===== 参考 =====
* 官方文档:https://rocketmq.apache.org/docs/
* 官方示例代码:https://github.com/apache/rocketmq/tree/develop/example
* 5.x 多语言客户端:https://github.com/apache/rocketmq-clients
* gRPC 协议定义(proto,Node 自建客户端要取这里的文件):https://github.com/apache/rocketmq-clients/tree/master/proto
* Node.js 4.x 社区绑定(仅 remoting,连 9876,长期未更新):https://github.com/apache/rocketmq-client-nodejs
* Spring 集成:https://github.com/apache/rocketmq-spring