RocketMQTemplate 详解 (RocketMQ 4.x vs 5.x)

RocketMQTemplate 详解 (RocketMQ 4.x vs 5.x)

一、核心差异概览

特性	RocketMQ 4.x	RocketMQ 5.x
架构模型	基于主从架构	轻量级 Broker + Compute 分离架构
事务消息	半消息 + 本地事务表	增强型事务模型（支持最终一致性事务）
API 设计	基础消息操作	更丰富的 API + 流式处理支持
消息类型	基础消息类型	新增批处理消息、流式消息
消费模式	Push/Pull	新增 Pop 消费模式
序列化	简单序列化	支持 Protocol Buffers 等高效序列化
容错机制	基础重试机制	增强的故障转移和自动恢复
云原生	有限支持	深度整合 Kubernetes 等云平台

二、核心 API 对比

1. 消息发送 (通用方法)

// 同步发送 (4.x & 5.x 通用)
SendResult result = rocketMQTemplate.syncSend("topic:tag", message);

// 异步发送 (4.x & 5.x 通用)
rocketMQTemplate.asyncSend("topic:tag", message, new SendCallback() {
    @Override
    public void onSuccess(SendResult sendResult) { /*...*/ }
    
    @Override
    public void onException(Throwable e) { /*...*/ }
});

// 单向发送 (4.x & 5.x 通用)
rocketMQTemplate.sendOneWay("topic:tag", message);

2. 事务消息差异

RocketMQ 4.x 实现：

// 4.x 事务消息
TransactionSendResult result = rocketMQTemplate.sendMessageInTransaction(
    "tx-group", 
    "topic:tag",
    message,
    arg
);

// 事务监听器
@RocketMQTransactionListener(txProducerGroup = "tx-group")
class TxListenerImpl implements RocketMQLocalTransactionListener {
    @Override
    public RocketMQLocalTransactionState executeLocalTransaction(Message msg, Object arg) {
        // 业务逻辑
        return RocketMQLocalTransactionState.COMMIT;
    }
    
    @Override
    public RocketMQLocalTransactionState checkLocalTransaction(Message msg) {
        // 回查逻辑
        return RocketMQLocalTransactionState.UNKNOWN;
    }
}

RocketMQ 5.x 增强实现：

// 5.x 事务消息 (增强API)
TransactionSendResult result = rocketMQTemplate.sendMessageInTransaction(
    "tx-group", 
    "topic:tag",
    message,
    new TransactionArg() {
        @Override
        public Object execute(Message message) {
            // 执行业务逻辑
            return businessService.process(message);
        }
        
        @Override
        public RocketMQLocalTransactionState check(Object executeResult) {
            // 根据业务执行结果决定事务状态
            return executeResult.success ? 
                RocketMQLocalTransactionState.COMMIT : 
                RocketMQLocalTransactionState.ROLLBACK;
        }
    }
);

3. 顺序消息差异

RocketMQ 4.x：

// 4.x 顺序消息
SendResult result = rocketMQTemplate.syncSendOrderly(
    "topic:tag", 
    message, 
    "orderId-123" // 分区键
);

RocketMQ 5.x 增强：

// 5.x 顺序消息 (支持自定义选择器)
SendResult result = rocketMQTemplate.syncSendOrderly(
    "topic:tag",
    message,
    "orderId-123",
    new MessageQueueSelector() {
        @Override
        public MessageQueue select(List<MessageQueue> mqs, Message msg, Object arg) {
            // 自定义队列选择逻辑
            int index = Math.abs(arg.hashCode()) % mqs.size();
            return mqs.get(index);
        }
    }
);

4. 延迟消息差异

RocketMQ 4.x：

// 4.x 延迟消息 (固定18个级别)
/**
* 1:1s  2:5s  3:10s  4:30s  5:1m  6:2m  7:3m  8:4m  
* 9:5m  10:6m  11:7m  12:8m  13:9m  14:10m  
* 15:20m  16:30m  17:1h  18:2h
*/
Message<?> msg = MessageBuilder.withPayload(payload)
    .setHeader(MessageConst.PROPERTY_DELAY_TIME_LEVEL, "3") // 1=1s, 2=5s,..., 18=2h
    .build();

RocketMQ 5.x：

// 5.x 支持精确延迟
Message<?> msg = MessageBuilder.withPayload(payload)
    .setHeader(RocketMQHeaders.DELAY_TIME, 5000) // 毫秒级精度
    .build();

5. 批量消息差异

RocketMQ 4.x：

// 4.x 批量发送
List<Message<?>> messages = ...;
SendResult result = rocketMQTemplate.syncSend("topic:tag", messages);

RocketMQ 5.x 增强：

// 5.x 批量发送 (支持压缩)
SendResult result = rocketMQTemplate.syncSend(
    "topic:tag", 
    messages,
    new SendOptions().setCompress(true) // 启用压缩
);

三、5.x 新增特性 API

1. 流式消息处理

// 流式生产者
rocketMQTemplate.sendAsStream("stream-topic", streamProducer -> {
    for (int i = 0; i < 100; i++) {
        streamProducer.send(MessageBuilder.withPayload("item-" + i).build());
    }
});

// 流式消费者
rocketMQTemplate.consumeAsStream("stream-topic", stream -> {
    stream.filter(msg -> msg.getPayload().contains("important"))
          .forEach(msg -> processImportant(msg));
});

2. 消息追踪集成

// 5.x 消息追踪
rocketMQTemplate.setTraceDispatcher(new TraceDispatcher() {
    @Override
    public void sendTrace(TraceContext ctx) {
        // 发送追踪数据到监控系统
        monitoringService.sendTrace(ctx);
    }
});

3. 消息路由控制

// 5.x 消息路由
rocketMQTemplate.sendWithRoute("topic", message, new RoutePolicy() {
    @Override
    public String selectRoute(Message message) {
        // 根据消息内容动态选择路由
        return message.getPayload().priority > 10 ? "high-priority-route" : "normal-route";
    }
});

四、配置对比

RocketMQ 4.x 配置

spring:
  cloud:
    stream:
      rocketmq:
        binder:
          name-server: 127.0.0.1:9876
        bindings:
          output:
            producer:
              group: my-group

RocketMQ 5.x 增强配置

spring:
  cloud:
    stream:
      rocketmq:
        binder:
          name-server: 127.0.0.1:9876
          # 5.x 新增配置
          access-key: ${ROCKETMQ_ACCESS_KEY}
          secret-key: ${ROCKETMQ_SECRET_KEY}
          namespace: ${ENV_NAMESPACE}
          enable-msg-trace: true
          customized-trace-topic: my-trace-topic
        bindings:
          output:
            producer:
              group: my-group
              # 5.x 新增生产者配置
              send-latency-fault-enable: true
              retry-times-when-send-failed: 5

五、最佳实践建议

迁移升级策略：

1. API 兼容性：5.x 兼容 4.x 的大部分 API，优先替换已废弃的方法
2. 事务消息：逐步迁移到 5.x 的事务模型，利用其更强的最终一致性保证
3. 消费模式：评估 Pop 消费模式是否适合业务场景（减少 Broker 压力）
4. 序列化优化：在 5.x 中使用 Protocol Buffers 替代 JSON 提升性能

5.x 特有功能应用：

// 1. 消息优先级处理
rocketMQTemplate.syncSend("topic", message, new SendOptions().setPriority(MessagePriority.HIGH));

// 2. 消息生命周期管理
rocketMQTemplate.setMessageTTL("topic", message, Duration.ofHours(2));

// 3. 多租户支持
rocketMQTemplate.sendInNamespace("tenant-namespace", "topic", message);

// 4. 消息轨迹集成
Message<?> tracedMsg = MessageBuilder.fromMessage(message)
    .setHeader(RocketMQHeaders.TRACE_ID, generateTraceId())
    .build();

六、性能优化技巧

1. 批量压缩（5.x 专有）：

   SendOptions options = new SendOptions()
       .setCompress(true)
       .setCompressThreshold(1024); // 1KB以上启用压缩
   rocketMQTemplate.syncSend("topic", messages, options);
   

2. 零拷贝发送（5.x 优化）：

   rocketMQTemplate.sendWithZeroCopy("topic", new ByteBufferPayload(byteBuffer));
   

3. 客户端缓存（4.x/5.x）：

   rocketMQTemplate.setCacheEnabled(true);
   rocketMQTemplate.setCacheExpire(Duration.ofMinutes(10));
   

七、错误处理对比

错误类型	RocketMQ 4.x 处理	RocketMQ 5.x 增强
发送超时	抛出 SendTimeoutException	自动重试 + 异步回调通知
Broker 不可用	抛出 MQClientException	智能路由切换 + 自动恢复
事务回查失败	默认回滚	可配置降级策略
消息过大	直接拒绝	支持分片传输

// 5.x 错误处理增强
rocketMQTemplate.setSendFailureHandler(new SendFailureHandler() {
    @Override
    public void onFailure(Message message, Throwable cause) {
        if (cause instanceof MessageTooLargeException) {
            // 分片处理大消息
            splitAndResendLargeMessage(message);
        } else {
            // 其他错误处理
            errorService.report(cause);
        }
    }
});

总结

1. 兼容性：RocketMQ 5.x 保持了对 4.x API 的高度兼容，升级成本低
2. 增强功能：
   • 更强大的事务消息模型
   • 精确延迟消息（毫秒级）
   • 流式消息处理
   • 消息生命周期管理
3. 性能优化：
   • 批量压缩
   • 零拷贝传输
   • 智能路由
4. 云原生支持：
   • 多租户隔离
   • Kubernetes 深度集成
   • 弹性伸缩能力
5. 运维增强：
   • 细粒度消息追踪
   • 自动故障转移
   • 可视化监控

迁移建议：新项目直接使用 RocketMQ 5.x，现有系统逐步迁移事务消息和延迟消息等关键功能到 5.x 特性，充分利用其增强的可靠性和性能优势。