Apache Pulsar 消息传递核心概念:从消息、生产者、消费者到订阅模式与消息持久化机制详解

原创2026-09-24 11:51:311,381 阅读
文章标签:消息队列后端流处理

Apache Pulsar 消息传递核心概念:从消息、生产者、消费者到订阅模式与消息持久化机制详解

Pulsar 的整个消息传递体系建立在发布-订阅(pub-sub)模式之上:生产者(producers) 把消息发布到 主题(topics),消费者(consumers) 通过 订阅(subscriptions) 订阅这些主题,处理收到的消息并在完成后发送确认(acknowledgement)。本文以 Pulsar 2.2.1 版本概念文档为主线,结合当前仓库源码与配置文件,系统梳理消息的内部结构、生产/消费链路、四种订阅类型、分区路由、消息保留与去重等核心机制,帮助你建立完整的 Pulsar 消息传递知识框架。

与多数消息中间件不同,Pulsar 在创建订阅后会保留所有消息,即使消费者处于断开状态。这些被保留的消息只有在消费者确认已成功处理后才会被丢弃。这一"确认驱动删除"的模型是理解 Pulsar 消息生命周期、订阅游标(cursor)与消息保留策略的起点。

消息(Messages):Pulsar 的基本传输单元

消息是 Pulsar 中最基本的"单元"。每条消息由多个组件构成,下表列出这些组件及其说明:

组件 说明
Value / data payload 消息携带的数据。所有 Pulsar 消息都包含原始字节,消息数据也可以遵循数据 schema 规范。
Key 消息可选地带有 key,这对 主题压缩(topic compaction) 等场景非常有用。
Properties 用户自定义属性的可选 key/value 映射。
Producer name 产生该消息的生产者名称。若未指定,则使用默认名称。
Sequence ID 每条 Pulsar 消息在其所属主题上属于一个有序序列,Sequence ID 即消息在该序列中的次序。
Publish time 消息发布的时间戳,由生产者自动写入。
Event time 应用附加的可选时间戳,例如记录消息被处理的时间。若未设置,该值为 0。
TypedMessageBuilder 用于构造消息的构建器,可通过它设置消息 key、value 等属性。设置 key 时请使用字符串类型;若将 key 设置为其他类型(如 AVRO 对象),key 会以字节形式发送,消费者端将难以还原出 AVRO 对象。

从源码看,消息的序列 ID、发布路径与 TypedMessageBuilder 均在 pulsar-client-api 的客户端 API 中定义;消息的 key/value/properties 结构则由 pulsar-common 下的协议定义承载,具体传输格式可参考 Pulsar 二进制协议 文档。

消息大小限制:默认 5 MB,可分别在 broker 与 bookie 侧配置

Pulsar 消息的默认大小为 5 MB。该限制可以在两个层面进行配置:

  • 在 broker.conf 文件中(broker 侧的最大消息大小):

    # The max size of a message (in bytes).
    maxMessageSize=5242880
    
  • 在 bookkeeper.conf 文件中(bookie 侧 netty 帧大小):

    # The max size of the netty frame (in bytes). Any messages received larger than this value are rejected. The default value is 5 MB.
    nettyMaxFrameSizeBytes=5253120
    

以上两项配置在当前仓库中均能找到真实取值:conf/broker.conf 中 maxMessageSize=5242880,conf/bookkeeper.conf 中 nettyMaxFrameSizeBytes=5253120。注意 nettyMaxFrameSizeBytes 略大于 maxMessageSize,这是为了给消息在协议层之外的封装(帧头等)留出余量。若消息实际大小超过限制,broker/bookie 会拒绝接收。

生产者(Producers):发布消息到 broker

生产者是附着到主题并向 Pulsar broker 发布消息的进程,broker 负责处理这些消息。生产者的核心行为由发送模式、访问模式、压缩、批处理与分块等机制决定。

发送模式:同步与异步

生产者可以同步(sync)或异步(async)向 broker 发送消息:

模式 说明
Sync send 生产者每发送一条消息后都等待 broker 的确认。若未收到确认,生产者将本次发送视为失败。
Async send 生产者将消息放入阻塞队列后立即返回。客户端库在后台将消息发送给 broker。若队列已满(队列最大长度可配置),生产者会根据调用 API 时传入的参数被阻塞,或立即失败。

访问模式:Shared、Exclusive 与 WaitForExclusive

生产者对主题可以采取不同的访问模式,即 ProducerAccessMode:

访问模式 说明
Shared 多个生产者可以在同一主题上发布消息。这是默认设置。
Exclusive 同一主题只允许一个生产者发布。若已有生产者连接,其他尝试在此主题发布的生产者会立即收到错误。当"旧"生产者与 broker 发生网络分区时,旧生产者会被驱逐(evicted),并选出"新"生产者作为下一个独占生产者。
WaitForExclusive 若已有生产者连接,生产者创建会保持挂起(pending)状态(而不是超时),直到获得 Exclusive 访问权。成功成为独占生产者的实例被视为 leader——如果你想为应用实现 leader 选举机制,可以使用此模式。

在仓库中,这三种模式定义于 ProducerAccessMode.java:Shared(默认多生产者可发布)、Exclusive(要求独占访问,若已有生产者连接则立即失败)、WaitForExclusive(生产者创建挂起直至获得独占访问权)。

:::note

一旦应用使用 Exclusive 或 WaitForExclusive 模式成功创建生产者,该应用实例即被保证是该主题的唯一写入者。其他尝试向该主题生产的实例要么立即报错,要么必须等待获得 Exclusive 访问权。该特性由 PIP 68: Exclusive Producer 引入,可通过 Java Client API 的 ProducerBuilder.accessMode(...) 设置。

:::

压缩:LZ4、ZLib、ZSTD 与 Snappy

生产者可以在传输过程中压缩发布的消息。Pulsar 目前支持以下压缩类型:

批处理(Batching):以批次为单位存储与追踪

启用批处理后,生产者会将一批消息累积后放在单个请求中发送。批次大小由最大消息数和最大发布延迟共同决定,因此积压(backlog)大小表示的是批次总数而非消息总数。

在 Pulsar 中,批次被作为单一单元追踪和存储,而非作为独立消息。消费者会将批次解绑为单条消息。但注意:通过 deliverAt 或 deliverAfter 参数配置的定时消息(scheduled messages)始终以单条消息发送,即使启用了批处理。

一般情况下,当批次内所有消息都被消费者确认后,整个批次才被确认。这意味着意外失败、负向确认(negative acknowledgement)或确认超时都可能导致整个批次内所有消息被重新投递,即使其中部分消息已被确认。

批次索引确认(batch index acknowledgement)

为避免向消费者重投已确认的批次内消息,Pulsar 从 2.6.0 起引入了批次索引确认机制。启用后,消费者会过滤掉已确认的批次索引,并向 broker 发送批次索引确认请求;broker 维护各批次索引的确认状态,避免把已确认消息再次派发给消费者;当批次内所有索引都被确认后,该批次消息才被删除。

默认情况下批次索引确认是关闭的(acknowledgmentAtBatchIndexLevelEnabled=false)。可以通过在 broker 侧将该参数设为 true 来启用,对应配置位于 conf/broker.conf。需要注意的是,启用它会带来更多的内存开销。

分块(Chunking):大消息的分片传输

启用分块(chunkingEnabled=true)时需遵循以下约束:

  • 批处理与分块不能同时启用,启用分块前必须先禁用批处理;
  • 分块仅支持持久化主题(persisted topics);
  • 分块仅支持 Exclusive 和 Failover 订阅类型。

分块的工作机制:当消息大小超过允许的最大发布载荷(max publish-payload size)时,生产者将原始消息拆分为多个分块消息,携带分块元数据按顺序分别发布到 broker。broker 侧,分块消息与普通消息一样存储在 managed-ledger 中,唯一区别是消费者需要缓冲分块消息,待收集齐所有分块后拼装成真实消息。managed-ledger 中的分块消息可以与普通消息交错存放。若生产者未能发布完整消息的所有分块,消费者在超过过期时间(默认一分钟)后可以让不完整的分块过期。

消费者消费分块消息时会将其缓冲,直到收到某条消息的所有分块,随后把分块拼装成完整消息放入 receiver-queue,客户端再从 receiver-queue 中消费。一旦消费者消费完整个大消息并确认,消费者内部会自动为与该大消息关联的所有分块消息发送确认。可通过 maxPendingChunkedMessage 参数限制消费者侧挂起的分块消息数量:达到阈值后,消费者会静默确认(silently ack)未分块消息,或通过标记未确认(unacknowledged)请求 broker 稍后重投。

broker 侧为支持非共享订阅的分块无需任何改动,仅使用 chunkedMessageRate 记录主题上的分块消息速率。

单生产者 + 单有序消费者的分块场景

当一个主题只有一个生产者,且该生产者既发布分块大消息也发布普通消息时:生产者把消息 M1 拆成 M1-C1、M1-C2、M1-C3 三个分块,broker 将三个分块按顺序存入 managed-ledger 并派发给有序(Exclusive/Failover)消费者;消费者在内存中缓冲所有分块,收到全部后拼装为原始消息 M1 交给客户端。

多生产者 + 单有序消费者的分块场景

当多个生产者向同一主题发布分块消息时,broker 会把来自不同生产者的全部分块存入同一个 managed-ledger。Producer 1 将消息 M1 拆为 M1-C1/M1-C2/M1-C3,Producer 2 将消息 M2 拆为 M2-C1/M2-C2/M2-C3。每条消息自身的分块依然有序,但在 managed-ledger 中可能不连续。这会给消费者带来内存压力,因为消费者需要为每个大消息分别维护缓冲区以聚合其全部分块。

消费者(Consumers):通过订阅接收消息

消费者是附着到主题(通过订阅)并接收消息的进程。消费者向 broker 发送流控许可请求(flow permit request) 来获取消息。消费者侧有一个接收缓冲队列,队列大小可通过 receiverQueueSize 参数配置,默认值为 1000。每次调用 consumer.receive() 都会从缓冲区出队一条消息。

接收模式:同步与异步

模式 说明
Sync receive 同步接收会阻塞,直到有消息可用。
Async receive 异步接收立即返回一个 future 值(例如 Java 中的 CompletableFuture),该 future 在新消息可用时完成。

监听器(Listeners)

客户端库为消费者提供监听器实现。例如 Java 客户端 提供 MessageListener 接口,每当收到新消息时都会调用其中的 received 方法。

确认(Acknowledgement)

当消费者成功消费一条消息后,会向 broker 发送确认请求。该消息会被永久存储,并且只有在所有订阅都确认它之后才会被删除。如果你希望存储已被消费者确认的消息,需要配置消息保留策略。

对于批消息,若启用了批次索引确认,broker 会维护各批次索引的确认状态,避免向消费者派发已确认的消息;当批次内所有索引都被确认后批次消息才会被删除。

消息可以以下两种方式确认:

  • 单条确认(individual acknowledgement):消费者需要对每条消息分别确认,并向 broker 逐个发送确认请求。
  • 累积确认(cumulative acknowledgement):消费者只需确认最后收到的那条消息,该消息之前(含该消息)的整个流中所有消息都不会再被重新投递给该消费者。

:::note

累积确认不能用于 Shared 订阅类型,因为该类型下多个消费者共享同一个订阅,消息必须逐条确认。

:::

负向确认(Negative acknowledgement)

当消费者某次未能成功消费一条消息、并希望再次消费时,可以向 broker 发送负向确认,broker 随后重新投递该消息。

消息按订阅类型以单条或累积方式负向确认:

  • 在 Exclusive 和 Failover 订阅类型中,消费者只能对最后收到的那条消息进行负向确认;
  • 在 Shared 和 Key_Shared 订阅类型中,可以对消息进行逐条负向确认。

需要注意:在 Exclusive、Failover、Key_Shared 这类有序订阅类型上使用负向确认,可能导致失败消息乱序到达消费者。

:::note

若启用了批处理,同一批次内的其他消息会与被负向确认的消息一起被重新投递给消费者。

:::

确认超时(Acknowledgement timeout)

若消息未能成功消费,而你希望自动触发 broker 重新投递,可以采用未确认消息自动重投机制:客户端在完整的 acktimeout 时间范围内跟踪未确认消息,当达到确认超时后自动向 broker 发送 redeliver unacknowledged messages 请求。

:::note

若启用了批处理,同一批次内的其他消息会与未确认消息一起被重新投递。

:::

:::note

优先使用负向确认而非确认超时。负向确认可以更精确地控制单条消息的重投,并能避免消息处理时间超过确认超时时导致的无效重投。

:::

死信主题(Dead letter topic)

死信主题允许消费者在部分消息无法成功消费时继续消费新消息。机制上,消费失败的消息会被存入一个独立的主题——即死信主题,你可以自行决定如何处理其中的消息。

以下 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();

从源码看,DeadLetterPolicy 在 DeadLetterPolicy.java 中定义了 maxRedeliverCount、retryLetterTopic、deadLetterTopic 等字段,ConsumerBuilder 通过 .deadLetterPolicy(...) 与 .enableRetry(...)(见 ConsumerBuilder.java)将其接入消费者构建流程。

死信主题依赖消息重投机制:消息因确认超时或负向确认而重投。若要对消息使用负向确认,请确保它在确认超时之前被负向确认。

:::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();

主题(Topics):消息传递的命名通道

与其他 pub-sub 系统一样,Pulsar 的主题是消息从生产者流向消费者的命名通道。主题名称是 URL,具有明确的结构:

{persistent|non-persistent}://tenant/namespace/topic
主题名组件 说明
persistent / non-persistent 标识主题类型。Pulsar 支持持久化主题和非持久化主题两类。默认是持久化:若不指定类型则主题为持久化。持久化主题的所有消息会被持久写入磁盘(若 broker 非 standalone 部署,则写入多块磁盘),而非持久化主题的数据不写入存储磁盘。
tenant 实例内的主题租户。租户是 Pulsar 多租户(multi-tenancy)的基础,可跨集群分布。
namespace 主题的管理单元,作为相关主题的分组机制。大部分主题配置都在命名空间级别完成。每个租户有一个或多个命名空间。
topic 名称的最后一部分。主题名在 Pulsar 实例中没有特殊含义。

无需显式创建主题 Pulsar 中你无需显式创建主题。若客户端尝试向尚不存在的主题写入或读取消息,Pulsar 会自动在主题名提供的命名空间下创建该主题。 若创建主题时未指定租户或命名空间,主题会在默认租户和命名空间中创建。你也可以在指定租户和命名空间中创建主题,例如 persistent://my-tenant/my-namespace/my-topic 表示在 my-tenant 租户的 my-namespace 命名空间中创建 my-topic 主题。

命名空间(Namespaces)

命名空间是租户内的逻辑命名空间。租户可以通过管理 API 创建多个命名空间。例如,一个拥有多个应用的租户可以为每个应用创建独立的命名空间。命名空间允许应用创建和管理主题的层次结构:my-tenant/app1 即为 my-tenant 下应用 app1 的命名空间。你可以在该命名空间下创建任意数量的主题。

订阅(Subscriptions):决定消息如何投递

订阅是一条命名配置规则,决定消息如何投递给消费者。Pulsar 提供四种订阅类型:Exclusive](#exclusive)、Shared、Failover 和 Key_Shared。对应枚举定义见 [SubscriptionType.java,其中:

  • Exclusive:同一主题+同一订阅名只能有 1 个消费者;
  • Shared:多个消费者使用同一订阅名,消息按 round-robin 轮流派发,消费顺序不保证;
  • Failover:多个消费者使用同一订阅名,但同一时刻只有 1 个消费者接收消息;该消费者断开后,其他消费者开始接收;消费顺序有保证(分区主题按分区保证顺序);
  • Key_Shared:多个消费者使用同一订阅,所有 key 相同的消息只派发给一个消费者;可用 ordering_key 覆盖消息 key 以决定顺序。

Pub-Sub 还是队列(Queuing) 在 Pulsar 中你可以灵活地组合不同订阅:

  • 若要在消费者之间实现传统的"扇出 pub-sub 消息传递",为每个消费者指定唯一的订阅名(即 Exclusive 订阅类型)。
  • 若要在消费者之间实现"消息排队",让多个消费者共享同一个订阅名(shared、failover、key_shared)。
  • 若想同时实现两种效果,可以将 Exclusive 订阅类型与其他订阅类型组合使用。

订阅类型(Subscription types)

当订阅没有消费者时,其类型是未定义的。订阅类型在消费者连接时才被确定,且可以通过用不同配置重启所有消费者来更改类型。

Exclusive(独占)

Exclusive 类型只允许一个消费者附着到订阅。若有多个消费者使用相同订阅名订阅同一主题,会报错。这是默认的订阅类型。

Failover(故障切换)

Failover 类型允许多个消费者附着到同一订阅。非分区主题(或分区主题的每个分区)会选出一个**主消费者(master consumer)**接收消息;当主消费者断开时,所有(未确认和后续的)消息会投递给排队的下一个消费者。

  • 对于分区主题,broker 会按消费者优先级级别和消费者名称的字典序对消费者排序,然后尽量将主题平均分配给优先级最高的消费者。
  • 对于非分区主题,broker 按消费者订阅该主题的先后顺序选择。

Shared(共享)

Shared 或 round robin 模式下,多个消费者可以附着到同一订阅。消息按 round-robin 方式在消费者之间分配,任意一条消息只会投递给一个消费者。当某个消费者断开时,已发送给它但未确认的消息会被重新调度给其余消费者。

Shared 类型的限制 使用 Shared 类型时请注意:

  • 不保证消息顺序。
  • 不能与 Shared 类型一起使用累积确认。

Key_Shared(键共享)

Key_Shared 模式下,多个消费者可以附着到同一订阅。消息按 key 分布到消费者,key 相同(或 ordering key 相同)的消息只投递给一个消费者。无论消息被重投多少次,都会投递给同一个消费者。当消费者连接或断开时,某些 key 的消费者服务关系会发生变化。

Key_Shared 类型的限制 使用 Key_Shared 类型时请注意:

  • 需要为消息指定 key 或 orderingKey。
  • 不能与 Key_Shared 类型一起使用累积确认。
  • 生产者应禁用批处理或使用基于 key 的批处理器。

你可以在 broker.config 文件中禁用 Key_Shared 订阅,对应配置项为 conf/broker.conf 中的 subscriptionKeySharedEnable=true(自 2.8.0 起推荐使用 subscriptionTypesEnabled 替代该配置)。

订阅模式(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();

NonDurable 订阅模式:

Consumer<byte[]> consumer = pulsarClient.newConsumer()
        .topic("my-topic")
        .subscriptionName("my-sub")
        .subscriptionMode(SubscriptionMode.NonDurable)
        .subscribe();

在 ConsumerBuilder.java 中可以看到 subscriptionMode(SubscriptionMode) 的 API 定义,Durable 为默认值。关于创建、查看或删除持久订阅,参见管理订阅。

多主题订阅(Multi-topic subscriptions)

消费者订阅 Pulsar 主题时,默认只订阅一个特定主题,如 persistent://public/default/my-topic。从 Pulsar 1.23.0-incubating 起,消费者可以同时订阅多个主题。可以通过两种方式定义主题列表:

  • 基于正则表达式(regex),例如 persistent://public/default/finance-.*
  • 显式定义一个主题列表

通过正则订阅多个主题时,所有主题必须在**同一个命名空间**内。

订阅多个主题时,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 = // Instantiate Pulsar client object

// Subscribe to all topics in a namespace
Pattern allTopicsInNamespace = Pattern.compile("persistent://public/default/.*");
Consumer<byte[]> allTopicsConsumer = pulsarClient.newConsumer()
                .topicsPattern(allTopicsInNamespace)
                .subscriptionName("subscription-1")
                .subscribe();

// Subscribe to a subsets of topics in a namespace, based on regex
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 有 5 个分区(P0 到 P4),分布在 3 个 broker 上。由于分区数多于 broker 数,两个 broker 各处理两个分区,第三个 broker 只处理一个分区(同样由 Pulsar 自动分配)。

该主题的消息广播给两个消费者。路由模式决定每条消息应发布到哪个分区,订阅类型决定哪些消息去往哪些消费者。

在大多数情况下,路由与订阅类型的选择可以独立进行:吞吐量问题应指导分区/路由决策,而订阅决策应依据应用语义。就订阅类型的工作方式而言,分区主题与普通主题没有区别——分区只决定消息从生产者发布到消费者处理确认之间发生了什么。

分区主题需要通过管理 API显式创建,创建时可指定分区数。

路由模式(Routing modes)

向分区主题发布消息时,必须指定路由模式。路由模式决定每条消息应发布到哪个分区(即哪个内部主题)。MessageRoutingMode 枚举定义于 MessageRoutingMode.java,共三种模式:

模式 说明
RoundRobinPartition 若未提供 key,生产者以 round-robin 方式在所有分区上发布消息以获得最大吞吐量。注意 round-robin 不是逐条消息进行,而是以批处理延迟为边界进行,以确保批处理有效。若消息指定了 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 是一个枚举,表示在特定消息选择分区时可用的标准哈希函数集合,定义于 HashingScheme.java:

  • JavaStringHash:使用常规 String.hashCode();
  • Murmur3_32Hash:使用 Murmur3 哈希函数。

生产者默认的哈希函数是 JavaStringHash。请注意:当生产者来自不同语言的多个客户端时,JavaStringHash 并不适用(不同语言对字符串哈希的实现可能不一致),此场景下推荐使用 Murmur3_32Hash。

非持久化主题(Non-persistent topics)

默认情况下,Pulsar 会将所有未确认消息持久化存储在多个 BookKeeper bookie(存储节点)上。持久化主题上的消息数据因此可以经受住 broker 重启和订阅方故障切换。

Pulsar 同时也支持非持久化主题:这类主题上的消息从不写入磁盘,只存在于内存中。使用非持久化投递时,杀掉一个 Pulsar broker 或断开订阅者,意味着该(非持久化)主题上的所有在途消息都会丢失,客户端可能看到消息丢失。

非持久化主题的名称形式如下(注意名称中的 non-persistent):

non-persistent://tenant/namespace/topic

更多非持久化主题使用说明,参见非持久化消息 cookbook。

在非持久化主题中,broker 会立即将消息投递给所有已连接的订阅者,而不在 BookKeeper 中持久化。若订阅者断开,broker 将无法投递这些在途消息,订阅者也永远无法再次收到它们。省去持久化存储步骤使非持久化主题上的消息传递在某些场景下比持久化主题略快,但代价是丢失了 Pulsar 的部分核心优势。

非持久化主题的消息数据只存在于内存。若消息 broker 故障或消息数据无法从内存中取回,消息数据可能丢失。只有在确定你的用例需要且能承受消息丢失时,才使用非持久化主题。

默认情况下,Pulsar broker 上启用非持久化主题,对应 conf/broker.conf 中的 enableNonPersistentTopics=true。你可以通过 broker 的配置禁用它们,并使用 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)。

所有消息保留和过期都在命名空间级别管理。操作指南见消息保留与过期 cookbook。

消息保留:在顶部场景中,应用于命名空间下所有主题的保留策略(retention policy)规定部分消息即使已被确认也会被持久存储在 Pulsar 中。未被保留策略覆盖的已确认消息会被删除。若没有保留策略,所有已确认消息都会被删除。

消息过期:在底部场景中,部分消息虽然尚未被确认,但因其已超过应用于命名空间的 TTL(例如命名空间 TTL 为 5 分钟,而这些消息 10 分钟未确认)而被删除。

消息去重(Message deduplication)

消息重复(duplication)发生在消息被 Pulsar 持久化超过一次时。消息去重是 Pulsar 的一个可选特性,它通过每条消息只处理一次来防止不必要的重复,即使消息被收到多次。

去重禁用场景(上图):生产者向主题发布消息 1,消息到达 broker 并被持久化到 BookKeeper;随后生产者(因某种重试逻辑)再次发送消息 1,broker 再次接收并存储到 BookKeeper,这就发生了重复。

去重启用场景(下图):生产者发布消息 1,broker 接收并持久化(与上例相同)。当生产者再次尝试发布该消息时,broker 知道它已见过消息 1,因此不会再次持久化。

消息去重在命名空间级别或主题级别处理,具体操作见消息去重 cookbook。

生产者幂等性(Producer idempotency)

消息去重的另一种可行方法是确保每条消息只被生产一次,这种方法通常称为生产者幂等性。该方案的缺点是把消息去重的工作推迟给了应用。在 Pulsar 中,这是在 broker 级别处理的,因此你无需修改 Pulsar 客户端代码,只需进行管理层面的更改。详见管理消息去重。

去重与"有效一次"(effectively-once)语义

消息去重使 Pulsar 成为与流处理引擎(SPEs)及其他寻求提供"有效一次"处理语义的系统配合使用的理想消息系统。不提供自动消息去重的消息系统需要 SPE 或其他系统自行保证去重,这意味着严格的消息顺序以把去重责任转嫁给应用为代价。而在 Pulsar 中,严格的顺序保证无需任何应用级代价。

更多深入信息参见 Splunk 关于 exactly-once 的博客。

延迟消息投递(Delayed message delivery)

延迟消息投递允许你稍后而非立即消费消息。机制上,消息先存储在 BookKeeper 中,发布到 broker 后 DelayedDeliveryTracker 在内存中维护时间索引(time -> messageId),当特定的延迟时间过去后消息才被投递给消费者。

延迟消息投递仅适用于 Shared 订阅类型。在 Exclusive 和 Failover 订阅类型中,延迟消息会被立即派发。

工作流程:broker 保存消息时不作任何检查。当消费者消费消息时,若消息设置了延迟,则将其加入 DelayedDeliveryTracker。订阅从 DelayedDeliveryTracker 中检查并取出超时的消息。

Broker 配置

延迟消息投递默认启用,可在 broker 配置文件中修改:

# Whether to enable the delayed delivery for messages.
# If disabled, messages are immediately delivered and there is no tracking overhead.
delayedDeliveryEnabled=true

# Control the ticking time for the retry of delayed message delivery,
# affecting the accuracy of the delivery time compared to the scheduled time.
# Default is 1 second.
delayedDeliveryTickTimeMillis=1000

这两项配置同样可以在当前仓库的 conf/broker.conf 中找到真实取值:delayedDeliveryEnabled=true、delayedDeliveryTickTimeMillis=1000。此外,仓库中还提供了两个相关高级参数:

  • isDelayedDeliveryDeliverAtTimeStrict=false(conf/broker.conf):默认非严格模式下,消息可能比 deliverAt 时间提前最多一个 tickTime 被投递,以降低 broker 维护延迟索引的开销;设为 true 后消息不会早于 deliverAt 时间被投递;
  • delayedDeliveryFixedDelayDetectionLookahead=50000(conf/broker.conf):用于检测主题中所有消息是否具有固定延迟的前瞻窗口大小。

生产者示例

以下是 Java 中生产者使用延迟消息投递的示例:

// message to be delivered at the configured delay interval
producer.newMessage().deliverAfter(3L, TimeUnit.Minute).value("Hello Pulsar!").send();

总结

从消息的组成与大小限制,到生产者/消费者的各种发送、接收、确认与重投机制,再到四种订阅类型、订阅模式(游标持久性)、分区路由与哈希方案、非持久化主题、消息保留与过期、去重和延迟投递,Pulsar 的"消息传递"概念覆盖了一条消息从发布到被确认删除的完整生命周期。理解这些核心概念,是正确配置 Pulsar(broker 配置项见 conf/broker.conf,bookie 配置项见 conf/bookkeeper.conf)以及编写可靠客户端应用(API 定义集中在 pulsar-client-api)的基础。

登录后查看全文
pulsar