Apache Pulsar 消息机制深度解析:从生产、消费到订阅模型
Apache Pulsar 消息机制深度解析:从生产、消费到订阅模型
Apache Pulsar 构建于经典的发布-订阅(pub-sub)模式之上:生产者(producer)向主题(topic)发布消息,消费者(consumer)订阅主题、处理消息,并在处理完成后向 broker 发送确认(acknowledgement)。本文以 concepts-messaging.md 为核心脉络,系统讲解 Pulsar 的消息模型、生产者/消费者行为、订阅类型、路由与分区、消息保留/过期、去重与延迟投递等核心概念,并结合仓库源码与配置文件给出可验证的实现细节。读完本文,你将掌握 Pulsar 消息链路中每个环节的设计动机、适用场景与关键配置,能够在实际项目中正确选择订阅类型、路由模式与消息保障机制。
消息(Messages):Pulsar 的基本单元
消息是 Pulsar 处理数据的基本"单元"。下表列出了消息的组成部分:
| 组成 | 说明 |
|---|---|
| Value / data payload | 消息携带的数据。所有 Pulsar 消息都包含原始字节,消息数据也可以遵循数据 schema 规范 |
| Key | 消息可选地带有键,可用于主题压缩等场景 |
| Properties | 用户自定义的可选键/值映射属性 |
| Producer name | 产生消息的生产者名称。若未指定,使用默认名称 |
| Sequence ID | 每条 Pulsar 消息在所属主题上属于一个有序序列,其序号即在该序列中的位置 |
| Publish time | 消息发布的时间戳,由生产者自动打上 |
| Event time | 应用附加的可选时间戳,例如记录消息被处理的时间。未设置时值为 0 |
| TypedMessageBuilder | 用于构造消息的构建器,可设置消息键、消息值等属性。设置 key 时应使用字符串;若设置为其他类型(如 AVRO 对象),key 会以字节形式发送,消费者端很难还原出 AVRO 对象 |
消息大小限制
Pulsar 消息的默认大小为 5 MB,可通过以下配置调整:
-
在 broker.conf 中:
# 消息的最大大小(字节)。 maxMessageSize=5242880 -
在 bookkeeper.conf 中:
# netty 帧的最大大小(字节)。任何超过此值的消息都会被拒绝。默认值为 5 MB。 nettyMaxFrameSizeBytes=5253120
从源码角度看,maxMessageSize 决定了 broker 能够接受的消息负载上限,而 nettyMaxFrameSizeBytes 是底层网络帧的缓冲区上限,二者共同约束了单条消息的传输与存储边界。更多消息格式细节可参考 Pulsar 二进制协议。
生产者(Producers)
生产者是附着到主题并向 Pulsar broker 发布消息的进程,broker 负责处理这些消息。
发送模式:同步与异步
| 模式 | 说明 |
|---|---|
| Sync send(同步发送) | 生产者每发送一条消息后等待 broker 的确认。若未收到确认,则将该次发送视为失败 |
| Async send(异步发送) | 生产者将消息放入阻塞队列并立即返回,客户端库在后台将消息发送到 broker。若队列已满(可通过配置调整最大长度),根据传入生产者的参数,调用 API 时生产者会被阻塞或立即失败 |
访问模式(Access Mode)
Pulsar 为生产者提供了三种主题访问模式,对应源码 ProducerAccessMode.java 中的枚举值:
| 访问模式 | 说明 |
|---|---|
Shared |
多个生产者可以同时向主题发布消息。默认设置 |
Exclusive |
同一时刻只允许一个生产者向主题发布消息。若已有生产者连接,其他尝试向该主题发布的生产者会立即报错。若"旧"生产者与 broker 发生网络分区,该生产者会被驱逐,"新"生产者被选为下一个独占生产者 |
WaitForExclusive |
若已有生产者连接,新生产者的创建会进入 pending 状态(而非超时),直到其获得 Exclusive 访问权。成功取得独占权的生产者被视为 leader,因此该模式可用于实现应用层面的 leader 选举 |
:::note
一旦应用以 Exclusive 或 WaitForExclusive 模式成功创建生产者,该应用实例即被保证是主题的唯一写入者,任何其他尝试向该主题生产的操作要么立即报错,要么必须等待取得 Exclusive 访问权。
:::
通过 Java Client API 可设置访问模式,对应 ProducerBuilder.java 中的 accessMode(ProducerAccessMode accessMode) 方法。
压缩(Compression)
生产者可在传输过程中压缩消息。Pulsar 目前支持以下压缩类型:
- LZ4
- ZLIB
- ZSTD
- SNAPPY
批量(Batching)
启用 batching 后,生产者将一批消息累积后通过单个请求发送。批大小由最大消息数和最大发布延迟共同决定,因此 backlog 大小代表的是批的数量而非消息总数。
在 Pulsar 中,批次被作为单个单元跟踪和存储,消费者会将一个批次解包为单条消息。需要注意:
- 通过
deliverAt或deliverAfter参数配置的定时消息即使启用了 batching,也总是作为单条消息发送; - 一般而言,一个批次在所有消息都被确认后才算确认。因此当不是所有批内消息都被确认时,异常失败、负确认或确认超时都可能导致该批次中所有消息被重新投递。
为避免批次中已确认消息被重复投递给消费者,Pulsar 自 2.6.0 起引入了 batch index acknowledgement(批索引确认)。启用后,消费者会过滤掉已确认的批索引,并向 broker 发送批索引确认请求;broker 维护每个批索引的确认状态,避免将已确认消息再次派发,当批内所有索引均被确认后该批次才被删除。
默认情况下批索引确认是关闭的(acknowledgmentAtBatchIndexLevelEnabled=false,见 broker.conf)。可将其设为 true 开启,但会带来更多的内存开销。
分块(Chunking)
启用分块前需了解以下约束:
- Batching 与 chunking 不能同时启用,启用 chunking 前必须先禁用 batching;
- Chunking 仅支持持久化主题;
- Chunking 仅支持 Exclusive 和 Failover 订阅类型。
当启用 chunking(chunkingEnabled=true)后,若消息大小超过允许的最大发布负载,生产者会将原始消息拆分为多个分块消息(chunked messages),携带分块元数据按顺序分别发布到 broker。broker 侧的分块消息与普通消息一样存储在 managed-ledger 中,唯一区别是消费者需要缓冲分块消息,并在收集齐所有分块后重组为原始消息。分块消息可以与普通消息交织存储;若生产者未能发布完某条消息的全部分块,消费者可在过期时间内将不完整分块失效,默认过期时间为 1 分钟。
消费者消费分块消息时会将其缓冲,直到收到某条大消息的全部分块后拼接并放入 receiver-queue。客户端从 receiver-queue 消费消息。一旦消费者消费并确认了整个大消息,会在内部对该大消息关联的所有分块消息发送确认。可通过消费者的 maxPendingChunkedMessage 参数设置缓冲阈值,达到阈值后消费者会丢弃未分块消息(静默确认,或标记为未确认由 broker 稍后重投)。
broker 侧支持非共享订阅的分块无需任何改动,仅使用 chunkedMessageRate 记录主题上的分块消息速率。
单生产者 + 单有序消费者场景:生产者将大消息 M1 拆为 M1-C1、M1-C2、M1-C3 三个分块发布,broker 依次存入 managed-ledger 并按序派发给有序(exclusive/failover)消费者;消费者在内存中缓冲全部分块后组合成原始消息 M1 交给客户端。
多生产者 + 单有序消费者场景:多个生产者发布的分块消息存入同一 managed-ledger,某条消息的各分块仍有序但可能不连续。这会给消费者带来内存压力,因为消费者需要为每条大消息单独维护缓冲区以聚合全部分块。
消费者(Consumers)
消费者是通过订阅附着到主题并接收消息的进程。消费者向 broker 发送 flow permit 请求 以获取消息;消费者侧存在一个接收队列缓存 broker 推送的消息,可通过 receiverQueueSize 参数配置队列大小,默认值为 1000。每次调用 consumer.receive() 都会从缓冲区出队一条消息。
接收模式
| 模式 | 说明 |
|---|---|
| Sync receive | 同步接收会阻塞,直到有消息可用 |
| Async receive | 异步接收立即返回一个 future(例如 Java 中的 CompletableFuture),在出现新消息时完成 |
监听器(Listeners)
客户端库为消费者提供监听器实现。例如 Java 客户端 提供 MessageListener 接口,每当收到新消息时调用其 received 方法。
确认(Acknowledgement)
消费者成功消费一条消息后向 broker 发送确认请求。该消息随后被永久存储,只有在所有订阅都确认之后才会被删除。若希望保留已被消费者确认的消息,需要配置消息保留策略。
消息确认有两种方式:
- 单条确认(individual acknowledgement):消费者逐条确认每条消息并向 broker 发送确认请求;
- 累积确认(cumulative acknowledgement):消费者只确认收到的最后一条消息,该消息之前(含该消息)的流中所有消息都不会再被重新投递给该消费者。
单条确认 API:
consumer.acknowledge(msg);
累积确认 API:
consumer.acknowledgeCumulative(msg);
:::note 累积确认不能用于 Shared 订阅类型,因为 Shared 涉及多个消费者共享同一订阅,Shared 类型中消息都是单条确认的。 :::
负确认(Negative Acknowledgement)
当消费者消费消息失败且希望再次消费该消息时,应向 broker 发送负确认,broker 会将该消息重新投递给消费者。负确认按订阅类型区分粒度:
- 在 Exclusive 和 Failover 订阅类型中,消费者只负确认其收到的最后一条消息;
- 在 Shared 和 Key_Shared 订阅类型中,消费者可以逐条负确认消息。
需要注意的是,对有序订阅类型(Exclusive、Failover、Key_Shared)进行负确认,可能导致失败消息被乱序投递给消费者。
// 调用此 API 后消息被负确认
consumer.negativeAcknowledge(msg);
:::note 如果启用了 batching,一个批次内的所有消息都会被重新投递给消费者。 :::
负确认重投退避(Negative Redelivery Backoff)
消费者处理消息失败时,除了简单负确认,还可以使用重投退避机制,通过设置重试次数让消息以不同延迟被重投,这样更灵活。例如对于 Shared 订阅,可以让失败消息稍后投递给其他消费者:
consumer.negativeAckRedeliveryBackoff(MultiplierRedeliveryBackoff.builder()
.minDelayMs(1000)
.maxDelayMs(60 * 1000)
.build())
确认超时(Acknowledgement Timeout)
若消息未成功消费且希望 broker 自动重投,可启用未确认消息的自动重投机制。启用后,客户端在 acktimeout 时间范围内跟踪未确认消息,并在确认超时到达时自动向 broker 发送 redeliver unacknowledged messages 请求。同样可以结合退避机制控制重投延迟:
consumer.ackTimeout(10, TimeUnit.SECOND)
.ackTimeoutRedeliveryBackoff(MultiplierRedeliveryBackoff.builder()
.minDelayMs(1000)
.maxDelayMs(60000)
.multiplier(2).build())
上述配置下,重投行为如下(基础 10 秒超时 + 倍增退避,封顶 60 秒):
| 重投次数 | 重投延迟 |
|---|---|
| 1 | 10 + 1 秒 |
| 2 | 10 + 2 秒 |
| 3 | 10 + 4 秒 |
| 4 | 10 + 8 秒 |
| 5 | 10 + 16 秒 |
| 6 | 10 + 32 秒 |
| 7 | 10 + 60 秒 |
| 8 | 10 + 60 秒 |
:::note
- 如果启用了 batching,一个批次内的所有消息都会被重新投递给消费者;
- 负确认优于确认超时:负确认能更精确地控制单条消息的重投,且当消息处理时间超过确认超时时可避免无效重投。 :::
死信主题(Dead Letter Topic)
死信主题(DLQ)机制让你在部分消息无法被成功消费时仍能继续消费新消息:消费失败的消息被存放到一个独立主题(死信主题),由你决定如何处理这些消息。
使用默认死信主题的 Java 示例:
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
.topic(topic)
.subscriptionName("my-subscription")
.subscriptionType(SubscriptionType.Shared)
.deadLetterPolicy(DeadLetterPolicy.builder()
.maxRedeliverCount(maxRedeliveryCount)
.build())
.subscribe();
默认死信主题命名格式:
<topicname>-<subscriptionname>-DLQ
指定死信主题名称的 Java 示例:
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
.topic(topic)
.subscriptionName("my-subscription")
.subscriptionType(SubscriptionType.Shared)
.deadLetterPolicy(DeadLetterPolicy.builder()
.maxRedeliverCount(maxRedeliveryCount)
.deadLetterTopic("your-topic-name")
.build())
.subscribe();
死信主题依赖消息重投机制——消息要么因确认超时重投,要么因负确认重投。若打算对消息使用负确认,请确保在确认超时之前完成负确认。
:::note 目前死信主题仅在 Shared 和 Key_Shared 订阅类型中启用。 :::
重试主题(Retry Letter Topic)
对于许多在线业务系统,消息会因业务逻辑处理异常而被重新消费。为了配置重新消费失败消息的延迟时间,可以让生产者同时向业务主题和重试主题发送消息,并在消费者端启用自动重试。启用自动重试后,未消费成功的消息被存储到重试主题,消费者在指定延迟时间后自动从重试主题消费失败消息。
默认自动重试是关闭的,将 enableRetry 设为 true 即可开启:
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
.topic(topic)
.subscriptionName("my-subscription")
.subscriptionType(SubscriptionType.Shared)
.enableRetry(true)
.receiverQueueSize(100)
.deadLetterPolicy(DeadLetterPolicy.builder()
.maxRedeliverCount(maxRedeliveryCount)
.retryLetterTopic("persistent://my-property/my-ns/my-subscription-custom-Retry")
.build())
.subscriptionInitialPosition(SubscriptionInitialPosition.Earliest)
.subscribe();
若希望将消息放入重试队列,可使用以下 API:
consumer.reconsumeLater(msg, 3, TimeUnit.SECONDS);
主题(Topics)与命名
与其他 pub-sub 系统一样,Pulsar 主题是生产者与消费者之间传输消息的命名通道。主题名是具有明确结构的 URL:
{persistent|non-persistent}://tenant/namespace/topic
| 主题名组成部分 | 说明 |
|---|---|
persistent / non-persistent |
标识主题类型。Pulsar 支持持久化与非持久化两种主题,默认是持久化。持久化主题的消息被持久化到磁盘(非 standalone 模式下持久化到多块磁盘),而非持久化主题的数据不落盘 |
tenant |
实例内的主题租户。租户是 Pulsar 多租户的核心,可跨集群分布 |
namespace |
主题的行政单元,用于对相关主题分组。大部分主题配置在 namespace 层面进行,每个租户可有多个 namespace |
topic |
名称的最后一部分,在 Pulsar 实例中没有特殊含义 |
无需显式创建主题 Pulsar 中无需显式创建主题。若客户端尝试向尚不存在的主题写入或读取消息,Pulsar 会根据主题名中提供的 namespace 自动创建该主题。 若客户端创建主题时未指定租户和 namespace,主题创建在默认租户与默认 namespace 下。你也可以在指定租户与 namespace 下创建主题,如
persistent://my-tenant/my-namespace/my-topic,即在my-tenant租户的my-namespacenamespace 中创建my-topic。
命名空间(Namespaces)
namespace 是租户内部的逻辑命名。租户可通过 admin API 创建多个 namespace。例如一个拥有多个应用的租户可以为每个应用创建独立 namespace,从而创建和管理主题层级。namespace 下可创建任意数量的主题。
订阅(Subscriptions)
订阅是一组命名的配置规则,决定消息如何投递给消费者。Pulsar 提供四种订阅类型:Exclusive、Shared、Failover 和 Key_Shared:
Pub-Sub 还是消息队列? Pulsar 中可灵活组合不同订阅:
- 若要在消费者间实现传统"扇出 pub-sub 消息",为每个消费者指定唯一订阅名,即 Exclusive 订阅类型;
- 若要在消费者间实现"消息队列",让多个消费者共享同一个订阅名(shared、failover、key_shared);
- 若想同时获得两种效果,可将 Exclusive 与其他订阅类型组合使用。
订阅类型
当订阅没有消费者时,其订阅类型未定义;类型在消费者连接时被定义,并且可以通过用不同配置重启所有消费者来更改。
Exclusive(独占)
Exclusive 类型只允许一个消费者附着到该订阅。若有多个消费者使用同一订阅名订阅同一主题,会产生错误。下图中只有 Consumer A-0 被允许消费消息。
Exclusive 是默认订阅类型。
Failover(故障转移)
Failover 类型允许多个消费者附着到同一订阅。对于非分区主题或分区主题的每个分区,会选出一个主消费者(master consumer)接收消息。当主消费者断开时,所有(未确认的及后续的)消息投递给下一个排队中的消费者。
- 对于分区主题,broker 按消费者优先级和消费者名称的字典序排序,然后将主题尽量均匀地分配给最高优先级层的消费者;
- 对于非分区主题,broker 按消费者订阅的顺序选择。
下图中 Consumer-B-0 是主消费者,若其断开,Consumer-B-1 将成为下一个接收消息的消费者。
Shared(共享)
Shared(又称 round robin)类型允许多个消费者附着到同一订阅。消息以轮询(round robin)方式在消费者间分发,任意消息只投递给一个消费者。当某个消费者断开时,已发给它但未确认的消息会被重新调度给剩余消费者。
下图中 Consumer-C-1 和 Consumer-C-2 都能订阅主题,Consumer-C-3 及其他消费者同样可以加入。
Shared 类型的限制
- 消息顺序不保证;
- Shared 类型不能使用累积确认。
Key_Shared(按键共享)
Key_Shared 类型允许多个消费者附着到同一订阅。消息按键分发:具有相同 key 或相同 ordering key 的消息总是投递给同一个消费者。无论消息重投多少次,都会投递给同一消费者。当消费者连接或断开时,某些 key 对应的消费者会发生变化。
使用 Key_Shared 订阅时,生产者必须禁用 batching 或使用基于键的 batching(key-based batching),原因有二:
- broker 按消息 key 派发消息,但默认 batching 可能无法将相同 key 的消息装入同一批次;
- 由于是消费者(而非 broker)从批次中派发消息,批次中第一条消息的 key 会被视为整个批次所有消息的 key,从而引发上下文错误。
基于键的 batching 确保生产者将相同 key 的消息装入同一批次;无 key 的消息装入一个批次且该批次无 key,broker 派发该批次时使用 NON_KEY 作为 key。此外,每个消费者只关联一个 key,并且只为该 key 接收一个消息批次。默认情况下可通过配置生产者允许发送的消息数来限制 batching。
启用基于键的 batching 的示例(client 为已创建的 Pulsar 客户端):
Producer<byte[]> producer = client.newProducer()
.topic("my-topic")
.batcherBuilder(BatcherBuilder.KEY_BASED)
.create();
ProducerConfiguration producerConfig;
producerConfig.setBatchingType(ProducerConfiguration::BatchingType::KeyBasedBatching);
Producer producer;
client.createProducer("my-topic", producerConfig, producer);
producer = client.create_producer(topic='my-topic', batching_type=pulsar.BatchingType.KeyBased)
Key_Shared 类型的限制
- 必须为消息指定 key 或 orderingKey;
- Key_Shared 类型不能使用累积确认。
订阅模式(Subscription Modes)
什么是订阅模式
订阅模式表示游标(cursor)类型:
- 创建订阅时会创建关联的游标,用于记录最后消费位置;
- 当订阅的消费者重启时,可以从最后消费的消息继续消费。
| 订阅模式 | 说明 | 备注 |
|---|---|---|
Durable |
游标是持久的,保留消息并持久化当前位置。若 broker 从故障中重启,可从持久存储(BookKeeper)恢复游标,从而从最后消费位置继续消费 | Durable 是默认订阅模式 |
NonDurable |
游标非持久。一旦 broker 停止,游标丢失且永远无法恢复,消息无法从最后消费位置继续消费 | Reader 的订阅模式本质是 NonDurable,且不会阻止主题数据被删除;Reader 的订阅模式无法更改 |
一个订阅可以有一个或多个消费者。消费者订阅主题时必须指定订阅名。持久订阅与非持久订阅可以使用相同名称,二者相互独立。若消费者指定的订阅不存在,该订阅会被自动创建。
何时使用
默认情况下,没有任何持久订阅的主题的消息会被标记为删除。若希望防止消息被标记删除,可为该主题创建持久订阅。此时只有被确认的消息才会被标记删除。详见消息保留与过期。
如何使用
消费者创建后,默认订阅模式为 Durable,可通过修改消费者配置改为 NonDurable:
// Durable
Consumer<byte[]> consumer = pulsarClient.newConsumer()
.topic("my-topic")
.subscriptionName("my-sub")
.subscriptionMode(SubscriptionMode.Durable)
.subscribe();
// Non-durable
Consumer<byte[]> consumer = pulsarClient.newConsumer()
.topic("my-topic")
.subscriptionName("my-sub")
.subscriptionMode(SubscriptionMode.NonDurable)
.subscribe();
关于持久订阅的创建、检查与删除,参见管理订阅。
多主题订阅(Multi-topic Subscriptions)
消费者订阅 Pulsar 主题时,默认只订阅一个具体主题(如 persistent://public/default/my-topic)。自 Pulsar 1.23.0-incubating 起,消费者可以同时订阅多个主题,有两种定义方式:
- 基于正则表达式,例如
persistent://public/default/finance-.*; - 显式定义一个主题列表。
通过正则订阅多个主题时,所有主题必须在同一个 namespace 中。
订阅多个主题时,Pulsar 客户端会自动调用 Pulsar API 发现匹配正则/列表的主题,然后逐一订阅。若某些主题尚不存在,消费者会在主题创建后自动订阅它们。
跨多主题不保证顺序 生产者向单个主题发送消息时,保证按相同顺序从该主题读取消息;但该保证不适用于多个主题。生产者向多个主题发送消息时,各主题的读取顺序不受保证。
Java 多主题订阅示例:
import java.util.regex.Pattern;
import org.apache.pulsar.client.api.Consumer;
import org.apache.pulsar.client.api.PulsarClient;
PulsarClient pulsarClient = // 实例化 Pulsar 客户端
// 订阅 namespace 中所有主题
Pattern allTopicsInNamespace = Pattern.compile("persistent://public/default/.*");
Consumer<byte[]> allTopicsConsumer = pulsarClient.newConsumer()
.topicsPattern(allTopicsInNamespace)
.subscriptionName("subscription-1")
.subscribe();
// 基于正则订阅 namespace 中的部分主题
Pattern someTopicsInNamespace = Pattern.compile("persistent://public/default/foo.*");
Consumer<byte[]> someTopicsConsumer = pulsarClient.newConsumer()
.topicsPattern(someTopicsInNamespace)
.subscriptionName("subscription-1")
.subscribe();
更多代码示例参见 Java 客户端多主题订阅。
分区主题(Partitioned Topics)
普通主题仅由单个 broker 服务,这限制了主题的最大吞吐量。分区主题是一种特殊主题,由多个 broker 处理,从而获得更高吞吐。
分区主题在实现上由 N 个内部主题构成(N 为分区数)。向分区主题发布消息时,每条消息被路由到多个 broker 之一,分区在 broker 间的分布由 Pulsar 自动处理。
上图中 Topic1 有五个分区(P0–P4)分布在三个 broker 上。由于分区数多于 broker 数,两个 broker 各处理两个分区,第三个 broker 处理一个(Pulsar 自动完成这种分布)。消息广播给两个消费者。路由模式决定每条消息发布到哪个分区,订阅类型决定哪些消息投递给哪些消费者。
多数情况下路由与订阅模式可以分别决策:吞吐需求应指导分区/路由决策,订阅决策应由应用语义决定。分区主题与普通主题在订阅类型的工作方式上没有区别——分区只决定消息从生产者发布到被消费者处理与确认之间发生什么。
分区主题需要通过 admin API 显式创建,创建时可指定分区数。
路由模式(Routing Modes)
向分区主题发布消息时必须指定路由模式,它决定每条消息发布到哪个分区(即哪个内部主题)。Pulsar 提供三种 MessageRoutingMode:
| 模式 | 说明 |
|---|---|
RoundRobinPartition |
若消息未指定 key,生产者以轮询方式将消息发布到所有分区以最大化吞吐。注意轮询并非按单条消息进行,而是与 batching 延迟边界一致以保证 batching 有效。若消息指定了 key,分区生产者会对 key 做哈希并将消息分配到特定分区。默认模式 |
SinglePartition |
若未指定 key,生产者随机挑选一个分区并将所有消息发布到该分区。若指定了 key,则对 key 哈希后分配到特定分区 |
CustomPartition |
使用自定义消息路由器实现决定每条消息的分区。可通过 Java 客户端实现 MessageRouter 接口创建自定义路由模式 |
顺序保证(Ordering Guarantee)
消息顺序与 MessageRoutingMode 和消息 Key 相关。通常用户希望获得 per-key-partition 的顺序保证。
若消息带有 key,使用 SinglePartition 或 RoundRobinPartition 模式时,消息会根据 ProducerBuilder 中指定的 HashingScheme 哈希到对应分区。
| 顺序保证 | 说明 | 路由模式与 Key |
|---|---|---|
| Per-key-partition | 相同 key 的所有消息有序,且放在同一分区 | 使用 SinglePartition 或 RoundRobinPartition 模式,且每条消息都带 Key |
| Per-producer | 同一生产者的所有消息有序 | 使用 SinglePartition 模式,且消息不带 Key |
哈希方案(Hashing Scheme)
HashingScheme 是表示标准哈希函数集合的枚举,用于选择特定消息的分区。Pulsar 提供两种标准哈希函数:JavaStringHash 和 Murmur3_32Hash。
生产者的默认哈希函数是 JavaStringHash。请注意,当生产者来自多种不同语言的客户端时,JavaStringHash 并不适用,此时推荐使用 Murmur3_32Hash(各语言客户端可一致实现)。
非持久化主题(Non-persistent Topics)
默认情况下,Pulsar 将所有未确认消息持久化存储在多个 BookKeeper bookie 上,持久化主题的数据因此能在 broker 重启和订阅者故障转移后存活。
同时 Pulsar 也支持非持久化主题:消息永不落盘,只存在于内存。使用非持久化投递时,若 Pulsar broker 崩溃或订阅者断开,该主题上所有传输中的消息都会丢失,客户端可能看到消息丢失。
非持久化主题命名如下(注意名称中的 non-persistent):
non-persistent://tenant/namespace/topic
非持久化主题中,broker 将消息不经过持久化立即投递给所有已连接订阅者。若订阅者断开,broker 无法再投递这些传输中的消息,订阅者也永远无法再次收到这些消息。省去持久化存储步骤使非持久化主题的消息传递在部分场景下略快于持久化主题,但代价是失去了 Pulsar 的部分核心优势。
非持久化主题的消息数据只存在于内存。若 broker 故障或消息数据无法从内存中获取,消息数据可能丢失。仅在确定你的使用场景需要且能承受时使用非持久化主题。
默认情况下,Pulsar broker 启用非持久化主题,可通过 broker 配置 enableNonPersistentTopics 禁用。可以使用 pulsar-admin topics 命令管理非持久化主题。
性能特征
非持久化消息通常比持久化消息更快,因为 broker 不持久化消息,且在消息投递给已连接 broker 后立即向生产者返回确认。因此生产者看到的发布延迟相对较低。
客户端 API
生产者与消费者连接非持久化主题的方式与持久化主题相同,关键区别是主题名必须以 non-persistent 开头。非持久化主题支持全部三种订阅类型——exclusive、shared 和 failover。
非持久化主题的 Java 消费者示例:
PulsarClient client = PulsarClient.builder()
.serviceUrl("pulsar://localhost:6650")
.build();
String npTopic = "non-persistent://public/default/my-topic";
String subscriptionName = "my-subscription-name";
Consumer<byte[]> consumer = client.newConsumer()
.topic(npTopic)
.subscriptionName(subscriptionName)
.subscribe();
同一非持久化主题的 Java 生产者示例:
Producer<byte[]> producer = client.newProducer()
.topic(npTopic)
.create();
消息保留与过期(Message Retention and Expiry)
默认情况下,Pulsar broker 会:
- 立即删除所有已被消费者确认的消息;
- 在消息 backlog 中持久存储所有未确认消息。
Pulsar 提供两个特性来覆盖这一默认行为:
- 消息保留(retention):允许存储已被消费者确认的消息;
- 消息过期(expiry):为尚未确认的消息设置生存时间(TTL)。
所有消息保留与过期都在 namespace](#命名空间namespaces) 层面管理。操作指南参见[消息保留与过期 cookbook。
上图上半部分展示消息保留:应用于 namespace 中所有主题的保留策略(绿色)使部分已确认消息被持久化存储在 Pulsar 中;未被保留策略覆盖的已确认消息(红色)被删除。若没有保留策略,所有已确认消息(青色)都会被删除。
图下半部分展示消息过期:部分消息即使尚未被确认(蓝色),也会因为超过了应用到 namespace 的 TTL(橙色)而被删除。例如对 namespace 应用 5 分钟 TTL,而消息已有 10 分钟未确认,则会被删除。
消息去重(Message Deduplication)
消息重复发生在 Pulsar 对一条消息持久化超过一次时。消息去重是 Pulsar 的可选特性,通过每条消息只处理一次来避免不必要的重复,即使该消息被接收了多次。
上图上半部分展示去重关闭的场景:生产者向主题发布消息 1,消息到达 broker 并持久化到 BookKeeper;随后生产者再次发送消息 1(例如由于某些重试逻辑),broker 再次接收并再次存储,于是发生了重复。
下半部分展示去重开启的场景:生产者发布消息 1,broker 接收并持久化;当生产者再次尝试发布该消息时,broker 识别出已见过消息 1,从而不再持久化。
消息去重在 namespace 级别或主题级别处理。更多操作说明参见消息去重 cookbook。
生产者幂等(Producer Idempotency)
另一种消息去重方案是确保每条消息只生产一次,即通常所说的生产者幂等。这种方案的缺点是把去重工作下放给了应用。在 Pulsar 中,去重在 broker 层面处理,因此无需修改 Pulsar 客户端代码,只需做管理层面的变更。详见管理消息去重。
去重与精确一次语义(Effectively-once)
消息去重使 Pulsar 成为与流处理引擎(SPE)以及其他追求 effectively-once 处理语义的系统配合使用的理想消息系统。不提供自动去重的消息系统要求 SPE 或其他系统自行保证去重,这意味严格的顺序保证以加重应用去重负担为代价。而使用 Pulsar,严格的顺序保证无需应用层面的任何代价。
延迟消息投递(Delayed Message Delivery)
延迟消息投递允许你延后消费消息而不是立即消费。该机制中,消息存储在 BookKeeper,发布到 broker 后由 DelayedDeliveryTracker 在内存中维护时间索引(time -> messageId),当特定延迟时间过后才投递给消费者。
延迟消息投递仅在 Shared 订阅类型中生效;在 Exclusive 和 Failover 订阅类型中,延迟消息会立即派发。
broker 保存消息时不作任何检查。消费者消费消息时,若消息设置了延迟,则被加入 DelayedDeliveryTracker;订阅从中检查并获取超时消息。
从源码看,DelayedDeliveryTracker.java 是延迟投递的抽象接口(提供 hasMessageAvailable()、getScheduledMessages(int maxMessages) 等方法),其默认实现为 InMemoryDelayedDeliveryTracker.java,由 DelayedDeliveryTrackerFactory 负责创建。这印证了文档中"DelayedDeliveryTracker 在内存中维护时间索引"的描述。
Broker 侧配置
延迟消息投递默认启用,可在 broker 配置文件中调整(对应 broker.conf):
# 是否启用消息延迟投递。
# 若禁用,消息会立即投递,且没有跟踪开销。
delayedDeliveryEnabled=true
# 控制延迟消息投递重试的 tick 时间,
# 影响投递时间与计划时间的精确度。
# 默认 1 秒。
delayedDeliveryTickTimeMillis=1000
Producer 侧示例
Java 生产者延迟投递示例:
// 消息将在配置的延迟间隔后投递
producer.newMessage().deliverAfter(3L, TimeUnit.Minute).value("Hello Pulsar!").send();
小结
Pulsar 的消息机制贯穿"生产者 → 主题 → 订阅 → 消费者"完整链路,各环节均可按需组合:
- 消息层面:支持 key、属性、事件时间、5 MB 默认大小限制,以及 batching、chunking 等提升吞吐或处理大消息的手段;
- 生产层面:同步/异步发送、Shared/Exclusive/WaitForExclusive 访问模式、压缩,以及延迟投递;
- 消费层面:单条/累积确认、负确认、确认超时、重投退避、死信与重试主题;
- 订阅层面:Exclusive/Failover/Shared/Key_Shared 四种类型与 Durable/NonDurable 两种模式,决定了消息分发语义与消费进度持久化;
- 主题层面:持久化/非持久化、分区与路由、多主题订阅,决定了吞吐、顺序与容错边界;
- 运维层面:消息保留、过期与去重,为"确认后仍可重读""TTL 清理""精确一次语义"提供了支撑。
上述核心概念均可在仓库源码与配置文件中找到实现依据(例如 broker.conf 中的 maxMessageSize、acknowledgmentAtBatchIndexLevelEnabled、delayedDeliveryEnabled 等参数,以及 ProducerAccessMode.java 和 DelayedDeliveryTracker.java 等实现),建议结合源码进一步深入验证各机制的内部行为。










