Apache RocketMQ DefaultMQProducer 完全指南:核心字段、构造方法、消息发送 API 与源码级实践详解
Apache RocketMQ DefaultMQProducer 完全指南:核心字段、构造方法、消息发送 API 与源码级实践详解
DefaultMQProducer 是 Apache RocketMQ Java 客户端中应用投递消息的统一入口类,它开箱即用,封装了同步、异步、Oneway 三种发送模式(均支持批量),并对外暴露了从创建 Topic 到事务消息、消息轨迹在内的一整套生产者 API。本文以 DefaultMQProducer 官方 API 参考文档 为骨架,结合 DefaultMQProducer.java 与 DefaultMQProducerImpl.java 的源码实现,逐字段、逐方法讲解每个配置参数与每个 send 变体的真实行为、默认值与适用场景,帮助读者在阅读完本文后能够根据业务需求正确选型、配置并使用生产者 API。
类简介:生产者的核心入口
DefaultMQProducer 的类声明如下:
public class DefaultMQProducer
extends ClientConfig
implements MQProducer
该类的核心职责与设计要点(对应源码注释见 DefaultMQProducer.java#L58-L70):
- 应用投递消息的入口:通过无参构造即可快速创建生产者,负责消息的发送,支持同步/异步/Oneway 三种发送方式,且这三种方式均支持批量发送。
- 参数可调:可以通过该类提供的 getter/setter 方法调整发送者的参数;同时该类提供了多个
send方法,每个方法语义略有不同,使用前务必仔细了解其意图。 - 线程安全:在配置并启动完成后,该类可以在多个线程间安全共享。源码 javadoc 明确标注了这一点,这也意味着一个生产者实例可以被整个应用的多个业务线程复用。
下面给出一个最基础的生产者示例(与官方示例代码一致):
public class Producer {
public static void main(String[] args) throws MQClientException {
// 创建指定分组名的生产者
DefaultMQProducer producer = new DefaultMQProducer("ProducerGroupName");
// 启动生产者
producer.start();
for (int i = 0; i < 128; i++)
try {
// 构建消息
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();
}
}
该示例的完整版可在仓库的 example/simple 目录下找到,其中还包含同步、异步、Oneway、批量发送、顺序消息等更丰富的发送示例。
字段摘要:生产者的关键配置属性
DefaultMQProducer 的核心字段及其含义如下表所示:
| 类型 | 字段名称 | 描述 |
|---|---|---|
| DefaultMQProducerImpl | defaultMQProducerImpl | 生产者的内部默认实现 |
| String | producerGroup | 生产者分组 |
| String | createTopicKey | 在发送消息时,自动创建服务器不存在的 topic |
| int | defaultTopicQueueNums | 创建 topic 时默认的队列数量 |
| int | sendMsgTimeout | 发送消息的超时时间 |
| int | compressMsgBodyOverHowmuch | 压缩消息体的阈值 |
| int | retryTimesWhenSendFailed | 同步模式下内部尝试发送消息的最大次数 |
| int | retryTimesWhenSendAsyncFailed | 异步模式下内部尝试发送消息的最大次数 |
| boolean | retryAnotherBrokerWhenNotStoreOK | 是否在内部发送失败时重试另一个 broker |
| int | maxMessageSize | 消息体的最大长度 |
| TraceDispatcher | traceDispatcher | 基于 RPCHook 实现的消息轨迹插件 |
字段详细信息
producerGroup(生产者分组)
private String producerGroup;
- 含义:生产者的分组名称。相同的分组名称表明生产者实例在概念上归属于同一分组。这对事务消息十分重要:如果原始生产者在事务之后崩溃,那么 broker 可以联系同一生产者分组的不同生产者实例来提交或回滚事务。对于非事务消息,只要保证每个进程内唯一即可。
- 默认值:
DEFAULT_PRODUCER,该常量定义于 MixAll.java#L76(MixAll.DEFAULT_PRODUCER_GROUP)。 - 命名约束:由数字、字母、下划线、横杠(-)、竖线(|)或百分号(%)组成;不能为空;长度不能超过 255。
defaultMQProducerImpl(内部默认实现)
protected final transient DefaultMQProducerImpl defaultMQProducerImpl;
生产者的内部默认实现,在构造生产者时自动初始化(见 DefaultMQProducer.java#L316),提供了本类绝大部分方法的内部实现,包括默认 topic 路由选择、消息压缩、发送超时控制与失败重试等逻辑。
createTopicKey(自动创建 topic 的 Key)
private String createTopicKey = TopicValidator.AUTO_CREATE_TOPIC_KEY_TOPIC;
- 含义:在发送消息时,自动创建服务器不存在的 topic 需要指定 Key,该 Key 可用于配置发送消息所在 topic 的默认路由。
- 默认值:
TBW102(即AUTO_CREATE_TOPIC_KEY_TOPIC)。 - 建议:仅用于测试或 demo,生产环境下不建议打开自动创建配置。
defaultTopicQueueNums(默认队列数)
private volatile int defaultTopicQueueNums = 4;
创建 topic 时默认的队列数量,默认值为 4。该字段被声明为 volatile,可在运行时安全调整。
sendMsgTimeout(发送超时)
private int sendMsgTimeout = 3000;
- 默认值:3000,单位毫秒。
- 建议:不建议修改该值,该值应该与 broker 配置中的
sendTimeout保持一致。发送超时时可临时修改该值,但根治方案是提升 broker 集群的 TPS 以解决超时问题。
compressMsgBodyOverHowmuch(压缩阈值)
private int compressMsgBodyOverHowmuch = 1024 * 4;
- 默认值:
1024 * 4(4KB),单位字节。大于 4K 的消息体将默认进行压缩。 - 底层实现:压缩动作发生在发送主流程中,见 DefaultMQProducerImpl.java#L1112-L1136 的
tryToCompressMessage方法:当消息体字节长度>= compressMsgBodyOverHowmuch时,调用defaultMQProducer.getCompressor().compress(body, compressLevel)对消息体进行压缩,成功后替换原消息体。注意批量消息(MessageBatch)当前不支持压缩。 - 压缩参数:可通过
DefaultMQProducerImpl.setZipCompressLevel方法设置压缩率(默认为 5,可选范围 0, 9]);可通过DefaultMQProducerImpl.tryToCompressMessage方法测试出 compressLevel 与 compressMsgBodyOverHowmuch 的最佳组合值。从源码看,压缩类型与级别还支持通过系统属性rocketmq.message.compress.level与rocketmq.message.compress.type覆盖(默认 ZLIB),见 [DefaultMQProducer.java#L213-L223。
retryTimesWhenSendFailed / retryTimesWhenSendAsyncFailed(重试次数)
private int retryTimesWhenSendFailed = 2;
private int retryTimesWhenSendAsyncFailed = 2;
- 含义:分别在同步模式、异步模式下,在返回发送失败之前内部尝试重新发送消息的最大次数。
- 默认值:均为 2,即默认情况下一条消息最多会被投递 3 次。
- 注意:在极端情况下,这可能会导致消息的重复,需要应用层自行做幂等处理。
retryAnotherBrokerWhenNotStoreOK(跨 broker 重试)
private boolean retryAnotherBrokerWhenNotStoreOK = false;
- 含义:同步模式下,消息保存失败时是否重试另一个 broker。
- 默认值:false。
- 注意:此配置关闭时,非投递时产生异常的情况下,会忽略
retryTimesWhenSendFailed配置。
maxMessageSize(最大消息体)
private int maxMessageSize = 1024 * 1024 * 4;
- 默认值:
1024 * 1024 * 4(4MB),单位字节。 - 含义:当消息体的字节数超过 maxMessageSize 时发送失败。该校验在 Validators.checkMessage 中执行——发送路径(如 DefaultMQProducerImpl.java#L688)在真正投递前都会先调用该校验方法,超出大小上限的消息会直接抛出
MQClientException。
traceDispatcher(消息轨迹)
private TraceDispatcher traceDispatcher = null;
- 含义:开启消息轨迹后,该类通过 hook 的方式把消息生产者、消息存储的 broker 和消费者消费消息的信息像链路一样记录下来。
- 初始化时机:在构造生产者时根据构造入参
enableMsgTrace决定是否创建该对象。在start()方法中,若开启轨迹,会创建AsyncTraceDispatcher并注册SendMessageTraceHookImpl、EndTransactionTraceHookImpl等 hook(见 DefaultMQProducer.java#L380-L405),轨迹数据默认写入RMQ_SYS_TRACE_TOPIC,可通过customizedTraceTopic自定义。
构造方法:七种创建方式
| 方法名称 | 方法描述 |
|---|---|
| DefaultMQProducer() | 由默认参数值创建一个生产者 |
| DefaultMQProducer(final String producerGroup) | 使用指定的分组名创建一个生产者 |
| DefaultMQProducer(final String producerGroup, boolean enableMsgTrace) | 使用指定的分组名创建一个生产者,并设置是否开启消息轨迹 |
| DefaultMQProducer(final String producerGroup, boolean enableMsgTrace, final String customizedTraceTopic) | 使用指定的分组名创建一个生产者,并设置是否开启消息轨迹及追踪 topic 的名称 |
| DefaultMQProducer(RPCHook rpcHook) | 使用指定的 hook 创建一个生产者 |
| DefaultMQProducer(final String producerGroup, RPCHook rpcHook) | 使用指定的分组名及自定义 hook 创建一个生产者 |
| DefaultMQProducer(final String producerGroup, RPCHook rpcHook, boolean enableMsgTrace, final String customizedTraceTopic) | 使用指定的分组名及自定义 hook 创建一个生产者,并设置是否开启消息轨迹及追踪 topic 的名称 |
从源码看,无参构造内部调用 this(MixAll.DEFAULT_PRODUCER_GROUP),最终所有构造器都会汇聚到最完整的构造器(DefaultMQProducer.java#L309-L317),在其中初始化 defaultMQProducerImpl = new DefaultMQProducerImpl(this, rpcHook)。仓库中还存在带 topics 列表(用于事务生产者初始化路由)以及带 namespace 的构造器(标注 @Deprecated),说明 namespace 能力已并入 ClientConfig。
各构造器入参说明汇总:
| 参数名 | 类型 | 是否必须 | 缺省值 | 描述 |
|---|---|---|---|---|
| producerGroup | String | 是 | DEFAULT_PRODUCER | 生产者的分组名称 |
| rpcHook | RPCHook | 否 | null | 每个远程命令执行后会回调 rpcHook |
| enableMsgTrace | boolean | 是 | false | 是否开启消息轨迹 |
| customizedTraceTopic | String | 否 | RMQ_SYS_TRACE_TOPIC | 消息轨迹 topic 的名称 |
使用方法:核心 API 详解
生命周期管理:start 与 shutdown
start()
public void start() throws MQClientException
启动生产者实例。在发送或查询消息之前必须调用此方法。它执行了许多内部初始化,比如:检查配置、与 namesrv 建立连接、启动一系列心跳等定时任务等。从源码看(DefaultMQProducer.java#L373-L406),start() 会先给 producerGroup 补全 namespace,然后调用 defaultMQProducerImpl.start() 完成客户端实例的启动;若开启了消息轨迹,还会在此创建 AsyncTraceDispatcher 并注册发送 hook、启动轨迹分发器。
shutdown()
public void shutdown()
关闭当前生产者实例并释放相关资源。会依次关闭内部实现(defaultMQProducerImpl.shutdown())、自动批量累加器(produceAccumulator)与轨迹分发器(traceDispatcher),见 DefaultMQProducer.java#L411-L420。
Topic 与消息队列管理
createTopic(两个重载)
public void createTopic(String key, String newTopic, int queueNum)
public void createTopic(String key, String newTopic, int queueNum, int topicSysFlag)
在 broker 上创建一个 topic。参数说明:
| 参数名 | 类型 | 是否必须 | 默认值 | 值范围 | 说明 |
|---|---|---|---|---|---|
| key | String | 是 | 访问密钥 | ||
| newTopic | String | 是 | 新建 topic 的名称。由数字、字母、下划线(_)、横杠(-)、竖线(|)或百分号(%)组成;长度小于 255;不能为 TBW102 或空 | ||
| queueNum | int | 是 | 0 | (0, maxIntValue] | topic 的队列数量 |
| topicSysFlag | int | 是 | 0 | 保留字段,暂未使用 |
fetchPublishMessageQueues
public List<MessageQueue> fetchPublishMessageQueues(String topic)
获取 topic 的消息队列(即生产者可投递的队列列表),底层委托给 defaultMQProducerImpl.fetchPublishMessageQueues(withNamespace(topic))。
消息查询类 API
| 方法签名 | 功能 | 关键返回值/异常 |
|---|---|---|
long earliestMsgStoreTime(MessageQueue mq) |
查询最早的消息存储时间 | 单位毫秒 |
long maxOffset(MessageQueue mq) |
查询给定消息队列的最大物理偏移量 | 最大物理偏移量 |
long minOffset(MessageQueue mq) |
查询给定消息队列的最小物理偏移量 | 最小物理偏移量 |
long searchOffset(MessageQueue mq, long timestamp) |
查找指定时间的消息队列的物理偏移量 | 指定时间的物理偏移量,timestamp 单位毫秒 |
QueryResult queryMessage(String topic, String key, int maxNum, long begin, long end) |
按关键字查询消息 | 返回查询到的消息集合;key 可空,begin/end 为毫秒时间戳 |
MessageExt viewMessage(String offsetMsgId) |
根据给定的 msgId 查询消息 | 返回 MessageExt,包含 topic 名称、消息体、消息 ID、消费次数、生产者 host 等信息 |
MessageExt viewMessage(String topic, String msgId) |
根据给定的 msgId 查询消息,并指定 topic | 同上 |
这些查询类方法在生产者状态非 Running、未找到 broker、broker 返回失败、网络异常或线程中断时均会抛出 MQClientException 等异常;viewMessage 在 msgId 非法时也会抛出 MQClientException。
消息发送核心 API:同步、异步、Oneway
DefaultMQProducer 提供了大量 send 方法,按发送模式可划分为三大类,每一类都有一组重载。选型要点如下:
同步发送(SendResult send(...))
同步发送仅在发送过程完全完成后返回,是默认推荐的可靠性发送方式。常见变体包括:
| 方法签名 | 特点 |
|---|---|
SendResult send(Message msg) |
同步单条发送;内部失败重试次数由 retryTimesWhenSendFailed 控制;未指定队列时默认轮询策略 |
SendResult send(Message msg, long timeout) |
指定超时时间;超时抛出 RemotingTooMuchRequestException |
SendResult send(Message msg, MessageQueue mq) |
向指定的消息队列同步发送单条消息 |
SendResult send(Message msg, MessageQueue mq, long timeout) |
指定队列 + 指定超时 |
SendResult send(Message msg, MessageQueueSelector selector, Object arg) |
通过队列选择器计算目标队列;此方式发送失败内部不会重试 |
SendResult send(Message msg, MessageQueueSelector selector, Object arg, long timeout) |
选择器 + 超时 |
SendResult send(Collection<Message> msgs) |
同步批量发送,集合内消息必须属于同一个 topic;默认轮询队列 |
SendResult send(Collection<Message> msgs, long timeout) |
批量 + 超时 |
SendResult send(Collection<Message> msgs, MessageQueue messageQueue) |
向指定队列批量发送 |
SendResult send(Collection<Message> msgs, MessageQueue messageQueue, long timeout) |
指定队列 + 超时 |
MessageQueueSelector 的典型用途:通过自实现该接口,将某一类消息发送至固定队列。例如,将同一个订单的状态变更消息始终投递到固定队列,从而配合消费端实现顺序消费。仓库示例 example/ordermessage 中提供了基于 MessageQueueSelector 的完整顺序消息发送示例。
异步发送(void send(..., SendCallback sendCallback, ...))
异步发送调用后立即返回,并在发送成功或异常时回调 sendCallback:
| 方法签名 | 特点 |
|---|---|
void send(Message msg, SendCallback sendCallback) |
异步发送单条消息;内部重试次数由 retryTimesWhenSendAsyncFailed 控制 |
void send(Message msg, SendCallback sendCallback, long timeout) |
异步 + 超时,超时后回调收到 RemotingTooMuchRequestException |
void send(Message msg, MessageQueue mq, SendCallback sendCallback) |
指定队列异步发送 |
void send(Message msg, MessageQueue mq, SendCallback sendCallback, long timeout) |
指定队列 + 超时 |
void send(Message msg, MessageQueueSelector selector, Object arg, SendCallback sendCallback) |
选择器 + 异步 |
void send(Message msg, MessageQueueSelector selector, Object arg, SendCallback sendCallback, long timeout) |
选择器 + 异步 + 超时 |
重要提醒:异步发送时 sendCallback 参数不能为 null,否则在回调时会抛出 NullPointerException。
Oneway 发送(void sendOneway(...))
public void sendOneway(Message msg)
public void sendOneway(Message msg, MessageQueue mq)
public void sendOneway(Message msg, MessageQueueSelector selector, Object arg)
以 oneway 形式发送消息时,broker 不会响应任何执行结果,行为与 UDP 类似——具有最大的吞吐量但消息可能会丢失。适用于消息量大、追求高吞吐量且允许消息丢失的场景。源码中 sendOneway 通过 CommunicationMode.ONEWAY 模式直接投递(见 DefaultMQProducerImpl.java#L1212-L1218)。
发送路径上的统一校验
从源码可以看到,所有发送入口在投递前都会先执行 Validators.checkMessage(msg, this.defaultMQProducer)(见 DefaultMQProducerImpl.java#L688、L745、L1232 等),校验消息 topic 合法性、消息体大小(maxMessageSize)等,随后进入压缩、选队列、发送的主流程。因此,maxMessageSize、compressMsgBodyOverHowmuch 等字段的取值会直接作用于每一次发送。
事务消息(sendMessageInTransaction)
public TransactionSendResult sendMessageInTransaction(Message msg, LocalTransactionExecuter tranExecuter, final Object arg)
public TransactionSendResult sendMessageInTransaction(Message msg, final Object arg)
- 该类不做默认实现,始终抛出
RuntimeException异常。 - 第一个重载中的
LocalTransactionExecuter已过期,将在 5.0.0 版本中移除,请勿使用该方法。 - 事务消息应使用
TransactionMQProducer类实现。仓库中 client/src/main/java/org/apache/rocketmq/client/producer/TransactionMQProducer.java 提供了完整实现,example/transaction 下有事务消息的完整示例(包含本地事务执行器与事务回查监听器的实现)。
发送异常速查
同步与批量发送可能抛出的异常包括:
MQClientException:broker 不存在或未找到、namesrv 地址为空、未找到 topic 的路由信息等客户端异常;RemotingException:网络异常;MQBrokerException:broker 发生错误;InterruptedException:发送线程中断;RemotingTooMuchRequestException:发送超时(超时时间由sendMsgTimeout或各方法入参timeout指定)。
异步与 Oneway 发送的异常列表与同步类似,但不包含 MQBrokerException。
生产实践建议
综合上文字段与方法的语义,在实际生产使用中建议遵循以下要点:
- 生产者复用与生命周期:
DefaultMQProducer是线程安全的,一个 JVM 进程内建议复用少量生产者实例,遵循start()→ 多次send→shutdown()的生命周期;不要在每次发送消息时都新建生产者。 - 可靠性与吞吐的权衡:核心业务使用同步发送(
send(msg)),必要时指定超时与MessageQueueSelector保证顺序;可容忍少量丢失的高吞吐场景使用 Oneway;需要快速返回且能接受异步回调的场景使用异步发送。三种模式的重试次数分别由retryTimesWhenSendFailed与retryTimesWhenSendAsyncFailed控制,注意重试可能带来消息重复,应用层需做好幂等。 - 参数校准:
sendMsgTimeout应与 broker 的sendTimeout保持一致;maxMessageSize(默认 4MB)与 broker 侧允许的最大消息大小需匹配;开启自动创建 topic(createTopicKey)仅限测试环境。 - 消息轨迹:通过
new DefaultMQProducer(group, true)或new DefaultMQProducer(group, true, "自定义轨迹Topic")开启消息轨迹,即可在RMQ_SYS_TRACE_TOPIC中观测消息从生产、存储到消费的完整链路。
扩展阅读
- DefaultMQProducer 源码:字段默认值、构造器聚合逻辑与 start/shutdown 实现
- DefaultMQProducerImpl 源码:发送主流程、消息压缩(
tryToCompressMessage)、路由选择与重试逻辑 - Validators.checkMessage:发送前的消息合法性校验
- 生产者示例合集:example/simple(同步/异步/Oneway/批量)、example/ordermessage(顺序消息)、example/transaction(事务消息)
- 消费端对应 API:API_Reference_DefaultPullConsumer.md