Apache RocketMQ DefaultMQProducer 使用指南:消息生产者 API 全解析

原创2026-09-19 13:05:551,626 阅读
文章标签:消息队列流处理微服务后端存储认证鉴权

Apache RocketMQ DefaultMQProducer 使用指南:消息生产者 API 全解析

本篇技术指南以 Apache RocketMQ 客户端核心类 DefaultMQProducer 为研究对象,系统讲解其类层次结构、全部构造方法、核心可调参数(含默认值与源码依据)、同步/异步/单向/批量四种发送方式、队列选择器、发送结果解析以及消息追踪等能力。读者学完后,可以基于 client 模块 的 API 快速构建稳定、高吞吐的 RocketMQ 生产者应用,并掌握参数调优与重试、背压等底层机制的原理。

一、类概览:生产者入口

DefaultMQProducer 是应用程序向 RocketMQ 发布消息的入口类,声明如下(见 DefaultMQProducer.java):

public class DefaultMQProducer
    extends ClientConfig
    implements MQProducer
  • 继承 ClientConfig:天然继承 NameServer 地址、命名空间(namespace)、TLS、VIP Channel 等通用客户端配置能力,可直接使用 setNamesrvAddr、setNamespace 等方法。
  • 实现 MQProducer 接口(见 MQProducer.java):接口约定了 start/shutdown 生命周期、同步/异步/单向发送、指定队列发送、批量发送、request(请求-应答)、recallMessage(消息撤回)、事务消息等完整方法集。
  • 核心职责:负责消息发送,支持同步、异步、单向三种发送语义,且所有发送方法均支持批量发送;发送参数均可通过该类暴露的 getter/setter 调整。

线程安全性:官方文档与类注释均明确说明——该类在配置并完成 start() 之后是线程安全的(thread-safe),可以安全地在多个线程之间共享使用(见 DefaultMQProducer.java)。因此生产环境中通常将生产者实例声明为单例并由多个业务线程共用,而不是每个线程各建一个。

二、快速上手:同步发送示例

官方 API 参考文档给出的最简示例(对应仓库中的完整可运行版本见 Producer.java):

public class Producer {
    public static void main(String[] args) throws MQClientException {
        // 以生产者组名创建生产者
        DefaultMQProducer producer = new DefaultMQProducer("ProducerGroupName");

        // 启动生产者(必须先 start 才能发送)
        producer.start();

        for (int i = 0; i < 128; i++)
            try {
                // 构造消息:主题、标签、业务 Key、消息体
                Message msg = new Message("TopicTest",
                        "TagA",
                        "OrderID188",
                        "Hello world".getBytes(RemotingHelper.DEFAULT_CHARSET));

                // 同步发送
                SendResult sendResult = producer.send(msg);

                // 打印发送结果
                System.out.printf("%s%n", sendResult);
            } catch (Exception e) {
                e.printStackTrace();
            }

        producer.shutdown();
    }
}

几个必须掌握的生命周期要点:

  1. start() 是必须的:类注释强调“必须调用 start() 之后才能发送或查询消息”,其内部会完成 Producer 实例注册、Topic 路由拉取、通信通道初始化等一系列准备工作(见 DefaultMQProducer.java)。
  2. shutdown() 释放资源:会依次关闭 DefaultMQProducerImpl、ProduceAccumulator(自动批处理累积器)以及 TraceDispatcher(消息追踪分发器)(见 DefaultMQProducer.java)。
  3. NameServer 地址:本地调试时需调用 producer.setNamesrvAddr("127.0.0.1:9876")(从 ClientConfig 继承);集群环境下也可通过环境变量或配置文件统一指定。

三、构造方法详解

DefaultMQProducer 提供了丰富的构造重载,官方 API 文档整理如下(源码实现见 DefaultMQProducer.java):

构造方法 说明
DefaultMQProducer() 使用默认参数创建生产者(producerGroup 默认为 DEFAULT_PRODUCER,见 MixAll.java)
DefaultMQProducer(final String producerGroup) 以生产者组名创建生产者
DefaultMQProducer(final String producerGroup, boolean enableMsgTrace) 创建生产者并设置是否开启消息轨迹追踪
DefaultMQProducer(final String producerGroup, boolean enableMsgTrace, final String customizedTraceTopic) 创建生产者并设置是否开启消息追踪以及自定义 trace topic
DefaultMQProducer(RPCHook rpcHook) 创建带 RPC 钩子的生产者(用于 ACL 鉴权、消息拦截等)
DefaultMQProducer(final String producerGroup, RPCHook rpcHook) 创建带 RPC 钩子与生产者组名的生产者
DefaultMQProducer(final String producerGroup, RPCHook rpcHook, boolean enableMsgTrace, final String customizedTraceTopic) 以上能力的组合

各构造参数的作用:

  • producerGroup(生产者组):从概念上聚合了角色完全相同的所有生产者实例,这在事务消息场景下尤为重要;对非事务消息,只需保证每个进程内唯一即可。默认值为 DEFAULT_PRODUCER。
  • enableMsgTrace:消息轨迹开关。开启后 start() 内部会创建 AsyncTraceDispatcher,并注册 SendMessageTraceHookImpl、EndTransactionTraceHookImpl 等钩子采集发送轨迹(见 DefaultMQProducer.java)。
  • customizedTraceTopic:自定义 trace topic 名称,不配置时使用默认轨迹主题。
  • RPCHook:在每次 remoting 命令执行前后触发的钩子,官方 ACL 鉴权即基于此实现。

另外,带 namespace 参数的构造方法(如 DefaultMQProducer(namespace, producerGroup))已标记 @Deprecated,新代码应优先使用 ClientConfig.setNamespace。

四、核心变量与参数详解(含默认值与源码依据)

官方 API 文档列出如下核心字段,结合 DefaultMQProducer.java 源码可以补齐每个参数的默认值与真实含义:

类型 字段 默认值 说明
DefaultMQProducerImpl defaultMQProducerImpl — 生产者内部默认实现,包装了几乎所有实际发送逻辑
String producerGroup DEFAULT_PRODUCER 生产者组名
String createTopicKey TBW102(自动创建主题的关键字) 服务端不存在的主题在发送消息时会自动创建
int defaultTopicQueueNums 4 自动创建主题时的默认队列数
int sendMsgTimeout 3000(毫秒) 消息发送超时时间
int compressMsgBodyOverHowmuch 4096(4K 字节) 消息体压缩阈值,超过 4K 默认启用压缩
int retryTimesWhenSendFailed 2 同步模式下内部最多重试次数
int retryTimesWhenSendAsyncFailed 2 异步模式下内部最多重试次数
boolean retryAnotherBrokerWhenNotStoreOK false 内部发送失败时是否换一个 Broker 重试
int maxMessageSize 4194304(4M 字节) 消息体最大允许长度
TraceDispatcher traceDispatcher null 消息轨迹追踪器,通过 rpcHook 采集追踪数据

说明:createTopicKey 的默认值对应 TopicValidator.AUTO_CREATE_TOPIC_KEY_TOPIC(TBW102),即“自动建主题”的样板主题名;compressMsgBodyOverHowmuch 的源码注释明确写着“消息体大于 4k 默认压缩”(见 DefaultMQProducer.java)。

除上述字段外,源码还暴露了一批对生产调优很有价值的参数(同样通过 getter/setter 访问):

字段 默认值 说明
sendMsgMaxTimeoutPerRequest -1 单次请求的最大发送超时
compressLevel 5(可由系统属性 rocketmq.message.compress.level 覆盖) 压缩算法压缩级别
compressType ZLIB(可由系统属性 rocketmq.message.compress.type 覆盖) 压缩算法类型
enableBackpressureForAsyncMode false 异步发送流量过大时是否启用阻塞式背压
backPressureForAsyncSendNum 1024 背压模式下在途异步消息数量上限
backPressureForAsyncSendSize 104857600(100M) 背压模式下在途异步消息体大小上限
autoBatch / produceAccumulator false / null 是否开启自动批量发送(配合 ProduceAccumulator)
batchMaxDelayMs -1 自动批处理最大攒批时间
batchMaxBytes -1 单批最大消息体大小
totalBatchMaxBytes -1 累积器总容量上限

另外,DefaultMQProducer 还从实现层透传了故障延迟规避(MqFaultStrategy)相关配置:setSendLatencyFaultEnable、setLatencyMax、setNotAvailableDuration,用于在发送失败时将 Broker 短期“拉黑”,从源码结构看(见 DefaultMQProducer.java)这些参数最终作用于 DefaultMQProducerImpl 内部的发送延迟容错策略。

五、三种发送语义:同步、异步、单向

DefaultMQProducer 的发送方法全部在 MQProducer.java 接口中声明,各有优劣,使用前务必弄清差异。官方文档特别提示:多个发送方法细节不同,请确认用法后再使用。

5.1 同步发送(send)

SendResult sendResult = producer.send(msg);
  • 直到整个发送流程完全结束才返回,能拿到确切的 SendResult(消息 ID、队列、偏移量等);
  • 注意内部重试机制:失败时内部会最多重试 retryTimesWhenSendFailed 次才判定失败,因此可能出现“消息实际已投递成功但返回失败”的情况,可能造成消息重复,需要应用层自行去重(见 DefaultMQProducer.java);
  • 支持带超时重载 send(msg, timeout),覆盖默认 sendMsgTimeout。

5.2 异步发送(send + SendCallback)

producer.send(msg, new SendCallback() {
    @Override
    public void onSuccess(SendResult sendResult) {
        System.out.printf("OK %s %n", sendResult.getMsgId());
    }
    @Override
    public void onException(Throwable e) {
        System.out.printf("Exception %s %n", e);
    }
});
  • 方法立即返回,发送完成(成功或失败)后回调 SendCallback;
  • 内部同样有最多 retryTimesWhenSendAsyncFailed 次的重试,同样存在消息重复的潜在风险;
  • 完整可运行示例见 AsyncProducer.java,该示例还演示了两个实战要点:
    • producer.setEnableBackpressureForAsyncMode(true):大流量场景建议开启异步背压,避免在途请求无限堆积;
    • producer.setRetryTimesWhenSendAsyncFailed(0):按需关闭异步重试(如配合业务级重试)。

5.3 单向发送(sendOneway)

producer.sendOneway(msg);
  • 与 UDP 类似,不等 Broker 确认就返回,吞吐量最高,但存在消息丢失的可能,适合日志、埋点等允许丢失的场景;
  • 见 OnewayProducer.java,发送后需要 Thread.sleep 等待发送完成再 shutdown()。

5.4 三种方式对比

方式 返回时机 可靠性 吞吐 适用场景
同步 send 发送完全结束 高(可感知结果) 低 重要消息、需要确认结果的场景
异步 send + SendCallback 立即返回 中高(回调感知结果) 高 高吞吐且需要感知结果
单向 sendOneway 立即返回 低(可能丢失) 最高 日志、监控埋点等

六、批量发送

所有发送方法均支持批量形式(send(Collection<Message> ...))。仓库中的批发送示例见 SimpleBatchProducer.java:

List<Message> messages = new ArrayList<>();
messages.add(new Message("BatchTest", "Tag", "OrderID001", "Hello world 0".getBytes(StandardCharsets.UTF_8)));
messages.add(new Message("BatchTest", "Tag", "OrderID002", "Hello world 1".getBytes(StandardCharsets.UTF_8)));
messages.add(new Message("BatchTest", "Tag", "OrderID003", "Hello world 2".getBytes(StandardCharsets.UTF_8)));

SendResult sendResult = producer.send(messages);

批量发送的约束(源码与示例注释均明确):同一批消息必须 topic 相同、waitStoreMsgOK 相同、且不支持定时/延迟消息;单批总大小建议不超过 1MiB(示例注释原话:“If you just send messages of no more than 1MiB at a time, it is easy to use batch”)。

在底层,Collection<Message> 会先通过 MessageBatch.generateFromList 转换为 MessageBatch,逐条执行 Validators.checkMessage 校验并生成唯一消息 ID(见 DefaultMQProducer.java)。

补充:自动批量(AutoBatch)——新版本还支持通过 setAutoBatch(true) + initProduceAccumulator() 开启自动攒批,由 ProduceAccumulator 在客户端按 batchMaxDelayMs / batchMaxBytes 聚合成批后发送。注意自动批处理对延迟消息(getDelayTimeLevel() > 0 等)、重试主题(%RETRY% 前缀)消息不生效,会回退为直接发送(见 DefaultMQProducer.java)。

七、选择队列发送与顺序消息

除默认按 Topic 路由随机/轮询选择队列外,DefaultMQProducer 还支持通过 MessageQueueSelector 精确控制消息进入哪个队列:

SendResult sendResult = producer.send(msg, new MessageQueueSelector() {
    @Override
    public MessageQueue select(List<MessageQueue> mqs, Message msg, Object arg) {
        // 例如按订单 ID 哈希取模,保证同一订单进入同一队列
        Integer orderId = (Integer) arg;
        int index = Math.abs(orderId.hashCode()) % mqs.size();
        return mqs.get(index);
    }
}, orderId);

该类重载了 send(msg, selector, arg) 的同步、异步、单向与超时变体(见 DefaultMQProducer.java),是实现局部顺序消息(如按订单维度有序)的标准手段。也可以直接指定目标队列:send(msg, MessageQueue mq) 及其异步/超时重载。

八、发送结果解析:SendResult 与 SendStatus

同步发送返回的 SendResult(见 SendResult.java)主要包含以下字段:

字段 说明
sendStatus 发送状态,见下方 SendStatus 枚举
msgId 客户端生成的消息全局唯一 ID
offsetMsgId Broker 存储后返回的物理消息 ID
messageQueue 消息实际写入的队列(Broker 名 + 队列 ID)
queueOffset 消息在队列中的逻辑偏移量
transactionId 事务消息 ID(非事务消息为空)
regionId 消息所属区域
recallHandle 消息撤回句柄(配合 recallMessage 使用)

sendStatus 的取值定义在 SendStatus.java:

public enum SendStatus {
    SEND_OK,               // 发送成功
    FLUSH_DISK_TIMEOUT,    // 刷盘超时(Broker 可能已保存也可能未保存)
    FLUSH_SLAVE_TIMEOUT,   // 同步刷从节点超时
    SLAVE_NOT_AVAILABLE,   // 从节点不可用
}

关键认知:只有 SEND_OK 是严格意义上的存储成功;其余三种状态说明消息写入存在不确定性(可能已落盘、也可能未落盘),这正是同步发送内部重试可能引发“重复投递”的根本原因。这也是 retryAnotherBrokerWhenNotStoreOK 参数存在的意义——设置为 true 时,遇到非 SEND_OK 的存储异常会尝试换 Broker 重发。

九、消息追踪(Message Trace)

通过构造方法或 ClientConfig 开启 enableMsgTrace 后,生产者会在发送链路中自动埋点。从 start() 的实现 可以看到完整链路:

  1. 创建 AsyncTraceDispatcher(异步分发,不阻塞业务发送线程);
  2. 注册 SendMessageTraceHookImpl 与 EndTransactionTraceHookImpl 发送钩子;
  3. 通过 RPC Hook 注册 DefaultRecallMessageTraceHook;
  4. 启动 dispatcher 时传入 NameServer 地址与 AccessChannel,使轨迹数据异步上报到默认(或自定义)trace topic。

使用方式:

// 方式一:构造时开启
DefaultMQProducer producer = new DefaultMQProducer("ProducerGroupName", true, "custom_trace_topic");

// 方式二:setter 开启(需在 start 之前调用)
producer.setEnableMsgTrace(true);
producer.setTraceTopic("custom_trace_topic");
producer.start();

十、其他高级能力:请求-应答、消息撤回与事务消息

DefaultMQProducer 还实现了 MQProducer 接口中的三类高级方法:

  1. 请求-应答(Request-Reply):request(msg, timeout) / request(msg, requestCallback, timeout) 等重载(见 DefaultMQProducer.java)。同步版本会阻塞直到消费者消费请求消息并回复;异步版本通过 RequestCallback 接收回复,超时抛出 RequestTimeoutException。
  2. 消息撤回:recallMessage(topic, recallHandle) 配合发送结果中的 recallHandle 使用,用于在指定时间窗口内撤回已发送的消息。
  3. 事务消息:注意 DefaultMQProducer 自身的 sendMessageInTransaction 实现是直接抛异常的(源码注释为 “please use TransactionMQProducer class”,见 DefaultMQProducer.java)——事务消息必须使用专门的 TransactionMQProducer 类,配合 TransactionListener 实现本地事务与消息发送的最终一致性。

十一、底层实现与参数调优原理

DefaultMQProducer 本身是门面(Facade),几乎所有逻辑委托给 defaultMQProducerImpl(类型为 DefaultMQProducerImpl,位于 client 模块 impl 包)。理解以下几点有助于正确调参:

  1. 内部重试语义:同步 send 与异步 send 都会在内部按 retryResponseCodes(默认包含 TOPIC_NOT_EXIST、SYSTEM_BUSY、NO_PERMISSION、GO_AWAY 等 8 种可重试响应码,见 DefaultMQProducer.java)决定是否重试,并可通过 addRetryResponseCode(int) 扩展自定义可重试码。
  2. 延迟容错选队列:发送前会经 MqFaultStrategy 评估各 Broker 的可用性与历史延迟(对应 setSendLatencyFaultEnable、setLatencyMax、setNotAvailableDuration 三组参数),避免向故障 Broker 持续发送。
  3. 异步背压:开启 enableBackpressureForAsyncMode 后,在途异步消息的数量与总体积分别受 backPressureForAsyncSendNum(默认 1024)与 backPressureForAsyncSendSize(默认 100M)约束;这两个参数支持运行时动态调整(见 DefaultMQProducer.java),底层以信号量 + ReadWriteCASLock 保证调整安全。
  4. 消息压缩:消息体超过 compressMsgBodyOverHowmuch(默认 4K)时按 compressType(默认 ZLIB)、compressLevel(默认 5)自动压缩,见 common 模块的压缩实现。

十二、常见配置清单与最佳实践

一个综合配置的生产者示例:

DefaultMQProducer producer = new DefaultMQProducer("ProducerGroupName");
producer.setNamesrvAddr("127.0.0.1:9876");          // 本地调试必配
producer.setSendMsgTimeout(5000);                    // 发送超时 5s
producer.setRetryTimesWhenSendFailed(3);             // 同步重试 3 次
producer.setRetryTimesWhenSendAsyncFailed(3);        // 异步重试 3 次
producer.setRetryAnotherBrokerWhenNotStoreOK(true);  // 存储异常时换 Broker 重试
producer.setMaxMessageSize(1024 * 1024 * 8);         // 消息体上限 8M
producer.setCompressMsgBodyOverHowmuch(4096);        // 4K 以上自动压缩
producer.setEnableMsgTrace(true);                    // 开启消息轨迹
producer.setSendLatencyFaultEnable(true);            // 开启发送延迟容错
producer.start();
// ... 业务发送 ...
producer.shutdown();

实战建议:

  • 单例共享:生产者是线程安全的,进程内一个生产者组一个实例即可,避免频繁创建/销毁带来的路由缓存与连接开销;
  • 先 start 再发送、用完 shutdown:start() 完成路由初始化,shutdown() 释放连接与线程资源,进程退出前务必调用;
  • 正视重复投递:同步/异步发送的内部重试可能造成消息重复,业务侧需基于 msgId(或业务 Key)做幂等;
  • 区分三种发送语义:对结果敏感用同步、高吞吐用异步、可丢场景用单向;
  • 事务消息务必用 TransactionMQProducer,不要调用 DefaultMQProducer.sendMessageInTransaction。

延伸阅读

登录后查看全文
rocketmq