差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

后一修订版
前一修订版
rocketmq [2026/10/16 12:56] – 新建 rocketmq 页面并写入思维导图 张叶安rocketmq [2026/10/16 14:11] (当前版本) – 参考小节补充 proto 与 nodejs 客户端链接 张叶安
行 24: 行 24:
 ### Java 5.x gRPC ### Java 5.x gRPC
 ### Spring Boot(rocketmq-spring-boot-starter) ### Spring Boot(rocketmq-spring-boot-starter)
-### Go / Python / C++ 客户端+### Go / Python / C++ / Node.js 客户端
 ## 消息类型 ## 消息类型
 - 普通消息 - 普通消息
行 44: 行 44:
 - 内存不足导致启动失败 - 内存不足导致启动失败
 ``` ```
 +
 +===== 一、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 二进制包(最经典) ==
 +
 +<code bash>
 +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
 +</code>
 +
 +<code ini>
 +# 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
 +</code>
 +
 +<code bash>
 +# 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
 +</code>
 +
 +控制台(可选):
 +
 +<code bash>
 +docker run -d --name rocketmq-dashboard -p 8082:8080 \
 +  -e "JAVA_OPTS=-Drocketmq.namesrv.addr=127.0.0.1:9876" \
 +  apacherocketmq/rocketmq-dashboard:latest
 +</code>
 +
 +== 3.2 新版本:5.x(namesrv + broker + proxy 三角色) ==
 +
 +生产建议三个角色分开部署;开发环境可以让 Broker 内嵌 Proxy(Local 模式)。
 +
 +<code bash>
 +# 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
 +</code>
 +
 +要点:
 +
 +  * 新客户端连的是 **Proxy 的 8081**,不是 NameServer 的 9876,这是新老接入最大的差别。
 +  * ''brokerIP1'' 依然要填对外真实 IP,否则 Proxy 会把内网地址回给客户端,报连接超时。
 +  * Proxy 的配置在 ''conf/rmq-proxy.json''(''namesrvAddr''、''grpcServerPort'' 等)。
 +  * 用云上托管版时,控制台给出的「接入点」就是 Proxy 的 endpoints,直接交给第 5 节的 gRPC 客户端。
 +
 +===== 四、接入方式一:Java 4.x(remoting,连 9876) =====
 +
 +依赖:
 +
 +<code xml>
 +<dependency>
 +    <groupId>org.apache.rocketmq</groupId>
 +    <artifactId>rocketmq-client</artifactId>
 +    <version>4.9.7</version>   <!-- 5.x 服务端也可用同一坐标的 5.x 版本 -->
 +</dependency>
 +</code>
 +
 +== 生产者 ==
 +
 +<code java>
 +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<Message>) (同 topic,总大小不超过 4MB)
 +// 指定队列:producer.send(msg, new MessageQueueSelector(){...}, arg)  → 顺序消息用
 +
 +producer.shutdown();
 +</code>
 +
 +== 消费者(Push 模式,最常用) ==
 +
 +<code java>
 +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();
 +</code>
 +
 +== 顺序消息 ==
 +
 +同一订单的消息必须落进同一个队列,消费端用 ''MessageListenerOrderly'':
 +
 +<code java>
 +// 生产端:按业务主键选队列
 +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;
 +});
 +</code>
 +
 +== 延时消息(4.x 固定 18 级) ==
 +
 +<code java>
 +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
 +</code>
 +
 +== 事务消息 ==
 +
 +<code java>
 +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");   // 先发半消息,再回调本地事务
 +</code>
 +
 +===== 五、接入方式二:Java 5.x(gRPC,连 8081) =====
 +
 +依赖(JDK 8+):
 +
 +<code xml>
 +<dependency>
 +    <groupId>org.apache.rocketmq</groupId>
 +    <artifactId>rocketmq-client-java</artifactId>
 +    <version>5.0.7</version>   <!-- 请以 Maven Central 上最新的 5.0.x 为准 -->
 +</dependency>
 +</code>
 +
 +== 客户端配置与生产者 ==
 +
 +<code java>
 +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<SendReceipt>
 +producer.close();     // 实现 Closeable
 +</code>
 +
 +== PushConsumer(推荐,框架自动 ack) ==
 +
 +<code java>
 +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();
 +</code>
 +
 +== SimpleConsumer(拉模式,显式 ack,适合批量与自定义流控) ==
 +
 +<code java>
 +SimpleConsumer consumer = provider.newSimpleConsumerBuilder()
 +        .setClientConfiguration(cfg)
 +        .setConsumerGroup("cg_order_pull")
 +        .setAwaitDuration(java.time.Duration.ofSeconds(15))
 +        .setSubscriptionExpressions(Collections.singletonMap("topic_order", "*"))
 +        .build();
 +
 +List<MessageView> msgs = consumer.receive(32, java.time.Duration.ofSeconds(15));
 +for (MessageView m : msgs) {
 +    process(m);
 +    consumer.ack(m);     // 处理成功才 ack;也可 changeInvisibleDuration 延长不可见时间
 +}
 +</code>
 +
 +== 事务消息(5.x 写法更简洁) ==
 +
 +<code java>
 +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()
 +</code>
 +
 +== 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 =====
 +
 +<code xml>
 +<dependency>
 +    <groupId>org.apache.rocketmq</groupId>
 +    <artifactId>rocketmq-spring-boot-starter</artifactId>
 +    <version>2.3.1</version>
 +    <!-- 2.2.x 面向 4.x;2.3.x 基于 5.x 客户端 jar(仍是 remoting 协议连 9876),4.x/5.x 服务端都能连 -->
 +</dependency>
 +</code>
 +
 +<code ini>
 +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=
 +</code>
 +
 +发送(''RocketMQTemplate'',topic 与 tag 用冒号分隔):
 +
 +<code java>
 +@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);
 +}
 +</code>
 +
 +消费:
 +
 +<code java>
 +@Service
 +@RocketMQMessageListener(
 +        topic = "topic_order",
 +        consumerGroup = "cg_order",
 +        selectorExpression = "PAID",
 +        consumeMode = ConsumeMode.ORDERLY)     // 默认 CONCURRENTLY
 +public class OrderConsumer implements RocketMQListener<String> {
 +    @Override
 +    public void onMessage(String body) {
 +        // 正常返回即消费成功;抛异常会触发重试
 +    }
 +}
 +</code>
 +
 +===== 七、接入方式四: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 风格):
 +
 +<code go>
 +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()
 +</code>
 +
 +Go(5.x gRPC 风格):
 +
 +<code go>
 +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()
 +</code>
 +
 +Python(4.x 风格):
 +
 +<code python>
 +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()
 +</code>
 +
 +== 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 自己也能当客户端。
 +
 +<code bash>
 +npm i @grpc/grpc-js @grpc/proto-loader
 +
 +# 从 apache/rocketmq-clients 仓库把 proto 目录拷到本地,例如:
 +#   proto/apache/rocketmq/v2/definition.proto
 +#   proto/apache/rocketmq/v2/service.proto
 +</code>
 +
 +<code javascript>
 +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);
 +</code>
 +
 +动手前必须知道的几点:
 +
 +  * **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 侧调网关:
 +
 +<code>
 +Node 业务进程  --HTTP/gRPC-->  sidecar(官方 Go/Python 客户端)  --gRPC 8081-->  Proxy
 +</code>
 +
 +  * 好处:协议、心跳、重试、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 上通用,常用命令:
 +
 +<code bash>
 +# 集群与 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"
 +</code>
 +
 +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
 +
  

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • rocketmq.1792126601.txt.gz
  • 最后更改: 2026/10/16 12:56
  • 由 张叶安