Apache RocketMQ 主动拉取模式详解:DefaultMQPullConsumer 实战与源码分析
Apache RocketMQ 主动拉取模式详解:DefaultMQPullConsumer 实战与源码分析
导读
本文围绕 Apache RocketMQ 客户端中的 DefaultMQPullConsumer 展开,系统讲解主动拉取(Pull)模式的适用场景、类结构、核心字段、构造方法、完整使用流程、offset 管理与消息过滤机制。通过阅读本文,你将掌握如何用 DefaultMQPullConsumer 编写可批量、可自定义 offset 的拉取型消费者,并理解其底层实现(DefaultMQPullConsumerImpl、PullAPIWrapper、OffsetStore)与消息队列重平衡的协作原理,同时了解它被标记为废弃后官方推荐的替代方案。
一、Pull 消费模式:把主动权交给应用
RocketMQ 的消费模式分为 Push(推送)与 Pull(拉取)两大类。DefaultMQPullConsumer 属于主动拉取型消费者,消费过程由应用自己驱动:应用先根据 Topic 获取 MessageQueue 集合,遍历队列,再针对每个队列按指定 offset 批量拉取消息,同时可以自行控制 offset 的位置。
这种模式的特点非常鲜明:
- 优势:按需消费、背压友好。消费者完全按照自身处理能力拉取消息,不用担心被消息洪峰打垮;Broker 侧也不必为每个消费者记录复杂的状态,只需维护所有消息队列的 offset 即可。因此对于消费速度慢、消息总量有限且到达速率不均匀的场景,Pull 模式比忙等的 Push 模式更合适。
- 缺点:实时性不足。由于主动权在消费方,消费者无法第一时间感知新消息的到来,比较适合对实时性要求不高的批处理场景。
在源码层面,Pull 与 Push 的分界清晰可见:DefaultMQPullConsumerImpl 的 consumeType() 返回 ConsumeType.CONSUME_ACTIVELY(主动消费),而 DefaultMQPushConsumerImpl 则属于被动消费。参见 DefaultMQPullConsumerImpl.java。
重要提示:在 DefaultMQPullConsumer.java 中,该类已被标注
@Deprecated,注释明确说明"该类将在 2022 年移除,主动拉取场景推荐使用实现更完善的DefaultLitePullConsumer"。不过该类的接口契约、offset 语义与消息队列模型至今仍是理解 RocketMQ 拉取消费的最佳入门教材,且MQPullConsumer接口族仍然完整存在于 client 模块 中,因此本文仍以官方 API 文档为骨架完整讲解,并在最后一节给出迁移建议。
二、类继承关系与字段摘要
DefaultMQPullConsumer 的继承与实现关系为:
public class DefaultMQPullConsumer extends ClientConfig implements MQPullConsumer
其中 MQPullConsumer extends MQConsumer,而 MQConsumer extends MQAdmin。因此一个 Pull 消费者天然同时具备消息消费能力(拉取、offset 管理、消息回退)与消息管理能力(建 Topic、查消息、查 offset)。
核心字段及语义如下表(源码见 DefaultMQPullConsumer.java):
| 字段 | 默认值 | 描述 |
|---|---|---|
defaultMQPullConsumerImpl |
构造时创建 | 内部核心处理实现(DefaultMQPullConsumerImpl),所有 API 均委托给它 |
consumerGroup |
无(必须显式指定) | 消费组唯一标识,同组消费者共享队列分配 |
brokerSuspendMaxTimeMillis |
1000 * 20(20 秒) |
长轮询模式下 Broker 端最大挂起时间,不建议修改 |
consumerTimeoutMillisWhenSuspend |
1000 * 30(30 秒) |
挂起模式下连接最大超时时间,必须大于 brokerSuspendMaxTimeMillis,不建议修改 |
consumerPullTimeoutMillis |
1000 * 10(10 秒) |
socket 连接最大超时时间(普通拉取用),不建议修改 |
messageModel |
MessageModel.CLUSTERING |
消费模式,默认集群模式 |
messageQueueListener |
null | 消息队列监听器,用于感知 topic 队列变化 |
offsetStore |
null(start 时按模式创建) | offset 存储:集群模式为 RemoteBrokerOffsetStore,广播模式为 LocalFileOffsetStore |
registerTopics |
空 Set | 注册到该 consumer 的 topic 集合,参与 rebalance |
allocateMessageQueueStrategy |
AllocateMessageQueueAveragely |
队列负载分配策略(平均分配算法) |
unitMode |
false | 是否为单元化消费组 |
maxReconsumeTimes |
16 | 消息最大重试消费次数,用于 sendMessageBack 重投递 |
原文档中 messageQueueListener、offsetStore、registerTopics、allocateMessageQueueStrategy 的类型标注有误(写成了 int),实际分别为 MessageQueueListener、OffsetStore、Set<String>、AllocateMessageQueueStrategy,本文已按 源码 修正。
三、构造方法与生命周期
3.1 构造方法
| 构造方法 | 说明 |
|---|---|
DefaultMQPullConsumer() |
使用默认参数创建,内部使用 MixAll.DEFAULT_CONSUMER_GROUP 作为分组名 |
DefaultMQPullConsumer(String consumerGroup) |
使用指定分组名创建 |
DefaultMQPullConsumer(RPCHook rpcHook) |
使用默认分组 + 指定 RPC Hook 创建(可用于权限认证等场景) |
DefaultMQPullConsumer(String consumerGroup, RPCHook rpcHook) |
指定分组名与 RPC Hook |
DefaultMQPullConsumer(String namespace, String consumerGroup, RPCHook rpcHook) |
同时指定命名空间、分组名与 Hook |
无参构造会使用默认分组名,而 DefaultMQPullConsumerImpl.checkConfig() 中明确校验:consumerGroup 不能为 null,也不能等于 MixAll.DEFAULT_CONSUMER_GROUP,否则抛出 MQClientException。因此生产环境务必显式传入全局唯一的 consumerGroup。
3.2 启动流程(start)
DefaultMQPullConsumer.start() 内部委托给 defaultMQPullConsumerImpl.start(),其核心步骤(源码见 DefaultMQPullConsumerImpl.java):
- 配置校验:校验分组名合法性、
messageModel、allocateMessageQueueStrategy非空,以及consumerTimeoutMillisWhenSuspend > brokerSuspendMaxTimeMillis; - 复制订阅关系:将
registerTopics解析为SubscriptionData写入 rebalance 的订阅表(copySubscription()); - 获取 MQClientInstance:通过
MQClientManager.getInstance().getOrCreateMQClientInstance(...)创建或复用客户端实例(共享网络连接、心跳等资源); - 初始化 rebalance 与 PullAPIWrapper:设置消费组、消息模型与队列分配策略,构建
PullAPIWrapper(负责真正的拉取请求组装与结果处理); - 按消息模型选择 offsetStore:
CLUSTERING(集群)→RemoteBrokerOffsetStore,offset 持久化在 Broker,同组消费者共享进度;BROADCASTING(广播)→LocalFileOffsetStore,offset 保存在本地文件;
- 注册消费者并启动客户端:
mQClientFactory.registerConsumer(...)+mQClientFactory.start(),随后心跳线程、rebalance 服务随之启动。
3.3 关闭流程(shutdown)
shutdown() 会先调用 persistConsumerOffset() 将内存中的 offset 持久化,再从 MQClientInstance 注销该消费组,最后关闭客户端实例(DefaultMQPullConsumerImpl.java)。
四、完整代码示例:手动管理 offset 的拉取消费者
原文档给出了一个完整可运行的示例,它演示了 Pull 模式最核心的套路:获取队列集合 → 读取/保存 offset → 循环拉取 → 按 PullStatus 分派处理。完整代码继承如下:
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.apache.rocketmq.client.consumer.DefaultMQPullConsumer;
import org.apache.rocketmq.client.consumer.PullResult;
import org.apache.rocketmq.client.exception.MQClientException;
import org.apache.rocketmq.common.message.MessageExt;
import org.apache.rocketmq.common.message.MessageQueue;
public class MQPullConsumer {
private static final Map<MessageQueue, Long> OFFSE_TABLE = new HashMap<MessageQueue, Long>();
public static void main(String[] args) throws MQClientException {
DefaultMQPullConsumer consumer = new DefaultMQPullConsumer("groupName");
consumer.setNamesrvAddr("127.0.0.1:9876");
consumer.start();
// 从指定 topic 中拉取所有消息队列
Set<MessageQueue> mqs = consumer.fetchSubscribeMessageQueues("order-topic");
for (MessageQueue mq : mqs) {
try {
// 获取消息的 offset,指定从 store 中获取
long offset = consumer.fetchConsumeOffset(mq, true);
System.out.println("consumer from the queue:" + mq + ":" + offset);
while (true) {
PullResult pullResult = consumer.pullBlockIfNotFound(mq, null,
getMessageQueueOffset(mq), 32);
putMessageQueueOffset(mq, pullResult.getNextBeginOffset());
switch (pullResult.getPullStatus()) {
case FOUND:
List<MessageExt> messageExtList = pullResult.getMsgFoundList();
for (MessageExt m : messageExtList) {
System.out.println(new String(m.getBody()));
}
break;
case NO_MATCHED_MSG:
break;
case NO_NEW_MSG:
break;
case OFFSET_ILLEGAL:
break;
}
}
} catch (Exception e) {
e.printStackTrace();
}
}
consumer.shutdown();
}
// 保存上次消费的消息下标
private static void putMessageQueueOffset(MessageQueue mq, long nextBeginOffset) {
OFFSE_TABLE.put(mq, nextBeginOffset);
}
// 获取上次消费的消息的下标
private static Long getMessageQueueOffset(MessageQueue mq) {
Long offset = OFFSE_TABLE.get(mq);
if (offset != null) {
return offset;
}
return 0L;
}
}
对该示例的几点深入说明:
fetchSubscribeMessageQueues(topic)返回该 Topic 对应的全部MessageQueue集合(注意这是"订阅信息"而非"分配给当前实例的队列")。实现上它优先读取 rebalance 内存中的topicSubscribeInfoTable,缺失时才调用MQAdminImpl.fetchSubscribeMessageQueues向 NameServer/Broker 查询(DefaultMQPullConsumerImpl.java)。fetchConsumeOffset(mq, true)的第二个参数fromStore=true表示直接读取OffsetStore中已持久化的值(对应ReadOffsetType.READ_FROM_STORE)。pullBlockIfNotFound是"无消息则阻塞"的长轮询版本:当没有新消息时,Broker 会挂起请求最多brokerSuspendMaxTimeMillis(20 秒),客户端 socket 等待最多consumerTimeoutMillisWhenSuspend(30 秒),以此减少空轮询。- offset 更新必须紧跟
getNextBeginOffset():每次拉取返回的nextBeginOffset是下一次拉取的起点,示例中用OFFSE_TABLE在内存中维护每个队列的消费进度——这是 Pull 模式下应用自己承担的最重要职责。
4.1 官方仓库中的生产级示例
仓库 example 模块 提供了一个更贴近生产实践的多线程版本,其关键差异在于:
- 启动前先
consumer.setRegisterTopics(topics)注册 Topic,让 rebalance 在启动阶段就能拿到订阅信息; - 使用
fetchMessageQueuesInBalance(topic)获取经过负载均衡分配后归属当前实例的队列集合,而非全部队列; - 每个 Topic 启动一个线程持续消费,队列为空时
Thread.sleep(1000)退避; - offset 读取采用三层兜底策略(
consumeFromOffset方法):- 先读内存(
ReadOffsetType.READ_FROM_MEMORY); - 内存无值则读 Broker(
READ_FROM_STORE); - 仍无值则从
maxOffset(messageQueue)(队列当前最大 offset)开始消费,即"新消费组默认从最新位置开始";
- 先读内存(
- 消费成功后调用
consumer.updateConsumeOffset(messageQueue, pullResult.getNextBeginOffset())更新 offset,最终由客户端定期批量提交到 Broker。
此外仓库还提供了定时轮询封装示例 PullScheduleService.java,对应 MQPullConsumerScheduleService 工具类,适合用调度框架周期性触发拉取任务的场景。
五、方法摘要:三大接口的全部能力
DefaultMQPullConsumer 的方法来自 MQAdmin、MQConsumer、MQPullConsumer 三个接口。下表完整覆盖原文档内容并补充了最新的 MessageSelector 重载与阻塞变体:
5.1 MQAdmin 接口(消息管理能力)
| 返回值 | 方法 | 描述 |
|---|---|---|
void |
createTopic(String key, String newTopic, int queueNum) |
在 Broker 上创建指定 Topic(指定队列数) |
void |
createTopic(String key, String newTopic, int queueNum, int topicSysFlag) |
创建 Topic,并指定系统标志位 |
long |
earliestMsgStoreTime(MessageQueue mq) |
查询指定队列最早消息的存储时间 |
long |
maxOffset(MessageQueue mq) |
查询给定队列的最大 offset |
long |
minOffset(MessageQueue mq) |
查询给定队列的最小 offset |
QueryResult |
queryMessage(String topic, String key, int maxNum, long begin, long end) |
按关键字在时间区间内查询消息 |
long |
searchOffset(MessageQueue mq, long timestamp) |
查找指定时间点对应的物理 offset |
MessageExt |
viewMessage(String offsetMsgId) |
根据 offsetMsgId 查询单条消息 |
MessageExt |
viewMessage(String topic, String msgId) |
根据 msgId 查询消息,并显式指定 Topic |
5.2 MQConsumer 接口(通用消费能力)
| 返回值 | 方法 | 描述 |
|---|---|---|
Set<MessageQueue> |
fetchSubscribeMessageQueues(String topic) |
根据 Topic 获取全部订阅队列 |
void |
sendMessageBack(MessageExt msg, int delayLevel) |
消费失败时把消息回发到 Broker,按 delayLevel 延迟重投 |
void |
sendMessageBack(MessageExt msg, int delayLevel, String brokerName) |
指定 Broker 回发消息 |
void |
sendMessageBack(MessageExt msg, int delayLevel, String brokerName, String consumerGroup) |
回发消息并显式指定消费组(消息可能被同组其他消费者再次消费) |
5.3 MQPullConsumer 接口(拉取核心能力)
| 返回值 | 方法 | 描述 |
|---|---|---|
long |
fetchConsumeOffset(MessageQueue mq, boolean fromStore) |
查询给定队列的消费 offset,fromStore=true 表示读 Broker 持久化值 |
PullResult |
pull(MessageQueue mq, String subExpression, long offset, int maxNums) |
同步拉取,subExpression 形如 "tag1 || tag2",null 或 * 表示订阅全部 |
PullResult |
pull(MessageQueue mq, String subExpression, long offset, int maxNums, long timeout) |
指定超时时间的同步拉取 |
PullResult |
pull(MessageQueue mq, MessageSelector selector, long offset, int maxNums) |
通过 MessageSelector 过滤(支持 SQL92 表达式) |
PullResult |
pull(MessageQueue mq, MessageSelector selector, long offset, int maxNums, long timeout) |
带超时的 Selector 拉取 |
void |
pull(..., PullCallback pullCallback) 系列 |
异步拉取,结果通过回调 PullCallback 返回 |
PullResult |
pullBlockIfNotFound(MessageQueue mq, String subExpression, long offset, int maxNums) |
长轮询拉取:无消息时阻塞至 consumerPullTimeoutMillis 超时 |
void |
pullBlockIfNotFound(..., PullCallback pullCallback) |
长轮询异步版本 |
PullResult |
pullBlockIfNotFoundWithMessageSelector(MessageQueue mq, MessageSelector selector, long offset, int maxNums) |
长轮询 + 消息选择器 |
void |
pullBlockIfNotFoundWithMessageSelector(..., PullCallback pullCallback) |
长轮询 + 选择器异步版本 |
void |
updateConsumeOffset(MessageQueue mq, long offset) |
更新指定队列的消费 offset(写入内存,异步提交 Broker) |
Set<MessageQueue> |
fetchMessageQueuesInBalance(String topic) |
获取 rebalance 之后归属当前消费者的队列集合 |
void |
shutdown() |
关闭消费者并释放资源 |
void |
start() |
启动消费者 |
原文档中
fetchConsumeOffset的描述"查询给定消息队列的最大 offset"有误,该方法实际返回的是当前消费进度 offset;fetchMessageQueuesInBalance与fetchSubscribeMessageQueues的区别在于前者是负载均衡分配后的子集,后者是 Topic 全量队列。
六、PullResult 与 PullStatus:四种拉取结果语义
每次 pull 返回的 PullResult 包含五个要素:
| 字段 | 含义 |
|---|---|
pullStatus |
拉取结果状态,见下表 |
nextBeginOffset |
下一次拉取应使用的起始 offset(消费成功后必须回写) |
minOffset |
当前队列可消费的最小 offset |
maxOffset |
当前队列的最大 offset |
msgFoundList |
拉取到的消息列表,仅 FOUND 状态下非空 |
PullStatus 枚举共四种状态:
| 状态 | 含义 | 建议处理 |
|---|---|---|
FOUND |
成功拉取到消息 | 处理 getMsgFoundList(),然后用 nextBeginOffset 更新 offset |
NO_NEW_MSG |
暂无新消息 | 可短暂 sleep 后继续,或依赖长轮询模式减少空转 |
NO_MATCHED_MSG |
消息存在但未通过过滤条件 | 同样用 nextBeginOffset 推进 offset,避免重复拉取 |
OFFSET_ILLEGAL |
offset 非法(过大或过小,例如队列被重置) | 按 nextBeginOffset 修正本地 offset 后再拉 |
注意:即使 NO_MATCHED_MSG 与 NO_NEW_MSG,也必须推进 offset,否则会陷入原地空转。官方示例 PullConsumer.java 对四种状态分别调用了 updateConsumeOffset,正是这个原因。
七、消息过滤:subExpression 与 MessageSelector
Pull 模式支持两级过滤:
- 字符串表达式(
subExpression):仅支持 Tag 过滤,语法为"tag1 || tag2 || tag3",null或"*"表示订阅全部 Tag。底层通过FilterAPI.buildSubscriptionData(topic, subExpression)解析为SubscriptionData(DefaultMQPullConsumerImpl.java)。 - MessageSelector(服务端过滤):
pull(mq, selector, offset, maxNums)重载支持更强大的过滤,MessageSelector 提供两个工厂方法:MessageSelector.byTag(String tag):等价于 Tag 过滤(类型为ExpressionType.TAG);MessageSelector.bySql(String sql):使用 SQL92 表达式在 Broker 端过滤(类型为ExpressionType.SQL92),例如"a between 0 and 3"、"property1 IS NOT NULL",需要 Broker 开启enablePropertyFilter支持。
// SQL92 过滤示例
PullResult result = consumer.pull(mq,
MessageSelector.bySql("(TAGS is not null and TAGS in ('TagA', 'TagB')) and a between 0 and 3"),
0, 32);
两种表达式类型的常量定义见 ExpressionType.java(TAG = "TAG"、SQL92 = "SQL92")。Tag 类型拉取时 subVersion 传 0 以跳过版本比对,SQL92 则携带版本号以支持过滤条件的增量更新(DefaultMQPullConsumerImpl.java)。
八、三个关键时间参数与长轮询机制
Pull 模式的时间控制由三个字段决定,源码默认值已在第二节给出,这里说明它们的协同关系:
| 参数 | 默认值 | 作用阶段 |
|---|---|---|
consumerPullTimeoutMillis |
10 秒 | 普通 pull() 的 socket 超时 |
brokerSuspendMaxTimeMillis |
20 秒 | 长轮询(pullBlockIfNotFound)时 Broker 挂起请求的最长时间 |
consumerTimeoutMillisWhenSuspend |
30 秒 | 长轮询时客户端 socket 等待的最长时间,必须大于 brokerSuspendMaxTimeMillis |
长轮询的执行链路(pullSyncImpl / pullAsyncImpl,DefaultMQPullConsumerImpl.java):
- 构造系统标志位
PullSysFlag.buildSysFlag(false, block, true, false),其中第二个参数即"是否挂起等待"; - 将
brokerSuspendMaxTimeMillis作为 Broker 端挂起时长、consumerTimeoutMillisWhenSuspend作为客户端 socket 超时,通过PullAPIWrapper.pullKernelImpl发出拉取请求; - Broker 若无新消息则挂起请求(最多 20 秒),期间一旦有新消息写入立即返回;超时后返回
NO_NEW_MSG。
启动校验(checkConfig)会强制保证 consumerTimeoutMillisWhenSuspend >= brokerSuspendMaxTimeMillis,否则直接抛异常(DefaultMQPullConsumerImpl.java)。官方注释明确这三个参数"不建议修改"。
九、offset 管理:集群与广播两种存储模型
Pull 模式下 offset 的读写走的是 OffsetStore 抽象,其实现类由 messageModel 决定(DefaultMQPullConsumerImpl.java):
- 集群模式(CLUSTERING,默认) →
RemoteBrokerOffsetStore:offset 提交到 Broker(写入__consumer_offset主题或 Broker 内存/文件),同消费组的不同实例共享消费进度,实现"队列级负载均衡、进度全局一致"。 - 广播模式(BROADCASTING) →
LocalFileOffsetStore:offset 持久化在消费者本地文件(默认目录~/.rocketmq_offsets),每个实例各自维护完整进度。
使用上的关键 API:
fetchConsumeOffset(mq, true):读取持久化 offset;fetchConsumeOffset(mq, false):内存优先,缺失再读存储(对应ReadOffsetType.MEMORY_FIRST_THEN_STORE);updateConsumeOffset(mq, offset):更新内存中的 offset,由客户端后台线程周期性批量持久化;persist(mq)/persistConsumerOffset():立即强制持久化(shutdown()时自动调用)。
从源码调用链看,拉取完成后的 processPullResult 会更新 PullResult 的 nextBeginOffset 并修正 msgFoundList,而应用需要做的就是把 nextBeginOffset 交给 updateConsumeOffset,这正是上一节示例所演示的闭环。
十、同步与异步:pull 与 PullCallback
MQPullConsumer 同时提供同步与异步两套拉取 API:
- 同步:
pull(...)系列返回PullResult,当前线程阻塞直至结果返回或超时,适合批处理任务直接串行驱动; - 异步:
pull(..., PullCallback callback)系列不阻塞,结果通过 PullCallback 回调返回,onSuccess(PullResult)处理成功结果,onException(Throwable)处理异常,适合用独立线程池驱动高吞吐拉取。
异步链路中,DefaultMQPullConsumerImpl 内部用 CommunicationMode.ASYNC 调用 pullKernelImpl,并在回调里先执行 processPullResult(完成消息解码、offset 修正与消息过滤)再转交应用回调(DefaultMQPullConsumerImpl.java),因此应用拿到的 PullResult 已经是处理后的最终结果。
十一、与 DefaultLitePullConsumer 的对比与迁移建议
由于 DefaultMQPullConsumer 已被官方标记废弃,主动拉取场景应优先使用 DefaultLitePullConsumer。两者的关键差异(从源码字段可对比确认):
| 能力 | DefaultMQPullConsumer | DefaultLitePullConsumer |
|---|---|---|
| offset 自动管理 | 需应用手动保存/更新 | 支持 autoCommit 自动提交(默认开启,间隔 autoCommitIntervalMillis = 5 秒,最小 1 秒) |
| 拉取线程模型 | 应用自行驱动 | 内置 pullThreadNums(默认 20)拉取线程池 |
| API 形态 | 面向 MessageQueue 手动拉取 |
支持 subscribe(topic) 订阅式拉取与 assign(collection) 指定队列拉取两种模式 |
| 队列分配 | 需配合 fetchMessageQueuesInBalance 手动遍历 |
内部集成 rebalance 与队列分配 |
| 状态 | @Deprecated,计划移除 |
官方推荐 |
迁移建议:如果当前代码基于本文的 pull/pullBlockIfNotFound 手动管理 offset,可平滑迁移到 DefaultLitePullConsumer 的 assign + poll 模式;如果希望保留订阅/重平衡语义,则用 subscribe + poll 模式。仓库中对应的官方示例见 LitePullConsumerSubscribe.java 与 LitePullConsumerAssign.java。
十二、相关源码与文档索引
- 类定义与字段:DefaultMQPullConsumer.java
- 接口契约:MQPullConsumer.java、MQConsumer.java
- 内部实现:DefaultMQPullConsumerImpl.java(start/shutdown/offsetStore 选择/长轮询)
- 结果模型:PullResult.java、PullStatus.java
- 过滤模型:MessageSelector.java、ExpressionType.java
- 官方运行示例:PullConsumer.java、PullScheduleService.java、LitePullConsumerSubscribe.java
- 替代方案:DefaultLitePullConsumer.java