Apache RocketMQ DefaultMQProducer 完全指南:核心字段、构造方法、消息发送 API 与源码级实践详解

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

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;

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)

发送异常速查

同步与批量发送可能抛出的异常包括:

  • MQClientException:broker 不存在或未找到、namesrv 地址为空、未找到 topic 的路由信息等客户端异常;
  • RemotingException:网络异常;
  • MQBrokerException:broker 发生错误;
  • InterruptedException:发送线程中断;
  • RemotingTooMuchRequestException:发送超时(超时时间由 sendMsgTimeout 或各方法入参 timeout 指定)。

异步与 Oneway 发送的异常列表与同步类似,但不包含 MQBrokerException。

生产实践建议

综合上文字段与方法的语义,在实际生产使用中建议遵循以下要点:

  1. 生产者复用与生命周期:DefaultMQProducer 是线程安全的,一个 JVM 进程内建议复用少量生产者实例,遵循 start() → 多次 send → shutdown() 的生命周期;不要在每次发送消息时都新建生产者。
  2. 可靠性与吞吐的权衡:核心业务使用同步发送(send(msg)),必要时指定超时与 MessageQueueSelector 保证顺序;可容忍少量丢失的高吞吐场景使用 Oneway;需要快速返回且能接受异步回调的场景使用异步发送。三种模式的重试次数分别由 retryTimesWhenSendFailed 与 retryTimesWhenSendAsyncFailed 控制,注意重试可能带来消息重复,应用层需做好幂等。
  3. 参数校准:sendMsgTimeout 应与 broker 的 sendTimeout 保持一致;maxMessageSize(默认 4MB)与 broker 侧允许的最大消息大小需匹配;开启自动创建 topic(createTopicKey)仅限测试环境。
  4. 消息轨迹:通过 new DefaultMQProducer(group, true) 或 new DefaultMQProducer(group, true, "自定义轨迹Topic") 开启消息轨迹,即可在 RMQ_SYS_TRACE_TOPIC 中观测消息从生产、存储到消费的完整链路。

扩展阅读

登录后查看全文
rocketmq