跳到主要内容
版本:2.0.7

消息消费

Doubao 中英对照 Message Consumption

目录

1. Pulsar 监听器​

在 Pulsar 消费者方面,我们建议终端用户应用使用 PulsarListener 注解。要使用 PulsarListener,你需要使用 @EnablePulsar 注解。当你使用 Spring Boot 支持时,它会自动启用该注解,并配置 PulsarListener 所需的全部组件,例如消息监听基础设施(负责创建 Pulsar 消费者)。PulsarMessageListenerContainer 使用一个 PulsarConsumerFactory 来创建并管理底层用于消费消息的 Pulsar 消费者。
Spring Boot 提供了这个消费者工厂,你可以通过指定 spring.pulsar.consumer.* 应用属性来进一步配置它。
让我们回顾一下在快速之旅(quick-tour)一节中看到的 PulsarListener 代码片段:
@PulsarListener(subscriptionName = "hello-pulsar-subscription", topics = "hello-pulsar")
public void listen(String message) {
System.out.println("Message Received: " + message);
}
你可以进一步简化这个方法:
@PulsarListener
public void listen(String message) {
System.out.println("Message Received: " + message);
}
在这种最基本的形式下,如果 @PulsarListener 注解上没有提供 subscriptionName,将使用一个自动生成的订阅名称。同样,如果没有直接提供 topics,则会使用主题解析流程来确定目标主题。
在前面所示的 PulsarListener 方法中,我们以 String 类型接收数据,但没有指定任何 schema 类型。在内部,框架依赖 Pulsar 的 schema 机制将数据转换为所需类型。框架检测到你期望的是 String 类型,然后据此推断出 schema 类型,并将该 schema 提供给消费者。框架会对所有基本类型做这种推断。对于所有非基本类型,默认假定 schema 为 JSON。如果某个复杂类型使用了 JSON 之外的任何类型(例如 AVRO 或 KEY_VALUE),你必须在注解上使用 schemaType 属性提供 schema 类型。
下面的示例展示了另一个接收 Integer 的 PulsarListener 方法:
@PulsarListener(subscriptionName = "my-subscription-1", topics = "my-topic-1")
public void listen(Integer message) {
System.out.println(message);
}
下面的 PulsarListener 方法展示了我们如何从一个主题消费复杂类型:
@PulsarListener(subscriptionName = "my-subscription-2", topics = "my-topic-2", schemaType = SchemaType.JSON)
public void listen(Foo message) {
System.out.println(message);
}
让我们再看几种方式。
你可以直接消费 Pulsar 消息:
@PulsarListener(subscriptionName = "my-subscription", topics = "my-topic")
public void listen(org.apache.pulsar.client.api.Message<String> message) {
System.out.println(message.getValue());
}
下面的示例使用 Spring 消息信封来消费记录:
@PulsarListener(subscriptionName = "my-subscription", topics = "my-topic")
public void listen(org.springframework.messaging.Message<String> message) {
System.out.println(message.getPayload());
}
现在让我们看看如何批量消费记录。下面的示例使用 PulsarListener 以 POJO 形式批量消费记录:
@PulsarListener(subscriptionName = "hello-batch-subscription", topics = "hello-batch", schemaType = SchemaType.JSON, batch = true)
public void listen(List<Foo> messages) {
System.out.println("records received :" + messages.size());
messages.forEach((message) -> System.out.println("record : " + message));
}
注意,在这个示例中,我们以对象集合(List)的形式接收记录。此外,要在 PulsarListener 级别启用批量消费,你需要把注解上的 batch 属性设置为 true。
框架会根据 List 所持有的实际类型尝试推断应使用的 schema。如果 List 包含的是 JSON 之外的复杂类型,你仍然需要在 PulsarListener 上提供 schemaType。
下面的示例使用 Pulsar Java 客户端提供的 Message 信封:
@PulsarListener(subscriptionName = "hello-batch-subscription", topics = "hello-batch", schemaType = SchemaType.JSON, batch = true)
public void listen(List<Message<Foo>> messages) {
System.out.println("records received :" + messages.size());
messages.forEach((message) -> System.out.println("record : " + message.getValue()));
}
下面的示例使用 Spring 消息 Message 类型的信封来消费批量记录:
@PulsarListener(subscriptionName = "hello-batch-subscription", topics = "hello-batch", schemaType = SchemaType.JSON, batch = true)
public void listen(List<org.springframework.messaging.Message<Foo>> messages) {
System.out.println("records received :" + messages.size());
messages.forEach((message) -> System.out.println("record : " + message.getPayload()));
}
最后,你也可以使用 Pulsar 的 Messages 持有对象作为批量监听器的参数:
@PulsarListener(subscriptionName = "hello-batch-subscription", topics = "hello-batch", schemaType = SchemaType.JSON, batch = true)
public void listen(org.apache.pulsar.client.api.Messages<Foo>> messages) {
System.out.println("records received :" + messages.size());
messages.forEach((message) -> System.out.println("record : " + message.getValue()));
}
当你使用 PulsarListener 时,可以直接在注解本身上提供 Pulsar 消费者属性。如果你不想使用前面提到的 Boot 配置属性,或者有多个 PulsarListener 方法,这样做会很方便。
下面的示例直接在 PulsarListener 上使用 Pulsar 消费者属性:
@PulsarListener(properties = { "subscriptionName=subscription-1", "topicNames=foo-1", "receiverQueueSize=5000" })
void listen(String message) {
}
提示
所使用的属性是直接的 Pulsar 消费者属性,而不是 spring.pulsar.consumer 应用配置属性。

1.1. 使用 AUTO_CONSUME 的通用记录​

如果无法事先知道某个 Pulsar 主题的 schema 类型,你可以使用 AUTO_CONSUME schema 类型来消费通用记录。在这种情况下,主题会使用与该主题关联的 schema 信息将消息反序列化为 GenericRecord 对象。
要消费通用记录,请在你的 @PulsarListener 上设置 schemaType = SchemaType.AUTO_CONSUME,并使用 GenericRecord 类型的 Pulsar 消息作为消息参数,如下所示。
@PulsarListener(topics = "my-generic-topic", schemaType = SchemaType.AUTO_CONSUME)
void listen(org.apache.pulsar.client.api.Message<GenericRecord> message) {
GenericRecord record = message.getValue();
record.getFields().forEach((f) ->
System.out.printf("%s = %s%n", f.getName(), record.getField(f)));
}
提示
GenericRecord API 允许访问各个字段及其关联的值。

1.2. 定制 ConsumerBuilder​

你可以使用 PulsarListenerConsumerBuilderCustomizer 来定制通过 ConsumerBuilder 可用的任何字段——只需提供一个类型为 PulsarListenerConsumerBuilderCustomizer 的 @Bean,然后让 PulsarListener 能够使用它,如下所示。
@PulsarListener(topics = "hello-topic", consumerCustomizer = "myCustomizer")
public void listen(String message) {
System.out.println("Message Received: " + message);
}

@Bean
PulsarListenerConsumerBuilderCustomizer<String> myCustomizer() {
return (builder) -> builder.consumerName("myConsumer");
}
提示
如果你的应用只有一个 @PulsarListener,并且只注册了一个 PulsarListenerConsumerBuilderCustomizer bean,那么该定制器将被自动应用。

2. 指定 Schema 信息​

如前所述,对于 Java 基本类型,Spring for Apache Pulsar 框架可以推断出 PulsarListener 上应使用的合适 Schema。对于非基本类型,如果没有在注解上显式指定 Schema,Spring for Apache Pulsar 框架会尝试根据该类型构建一个 Schema.JSON。
important
当前支持的复杂 Schema 类型有:JSON、AVRO、PROTOBUF、AUTO_CONSUME,以及采用 INLINE 编码的 KEY_VALUE。

2.1. 自定义 Schema 映射​

作为在 PulsarListener 上为复杂类型指定 schema 的替代方案,可以为 schema 解析器配置类型映射。这样就无需在监听器上设置 schema,因为框架会根据传入消息的类型去查询解析器。

2.1.1. 配置属性​

可以使用 spring.pulsar.defaults.type-mappings 属性来配置 schema 映射。下面的示例使用 application.yml,分别为 User 和 Address 这两个复杂对象添加了 AVRO 和 JSON schema 映射:
spring:
pulsar:
defaults:
type-mappings:
- message-type: com.acme.User
schema-info:
schema-type: AVRO
- message-type: com.acme.Address
schema-info:
schema-type: JSON
备注
message-type 是消息类的全限定名。

2.1.2. Schema 解析器定制器​

添加映射的首选方式是使用上面提到的属性。不过,如果需要更精细的控制,你可以提供一个 schema 解析器定制器来添加映射。
下面的示例使用 schema 解析器定制器,分别为 User 和 Address 这两个复杂对象添加 AVRO 和 JSON schema 映射:
@Bean
public SchemaResolverCustomizer<DefaultSchemaResolver> schemaResolverCustomizer() {
return (schemaResolver) -> {
schemaResolver.addCustomSchemaMapping(User.class, Schema.AVRO(User.class));
schemaResolver.addCustomSchemaMapping(Address.class, Schema.JSON(Address.class));
}
}

2.1.3. 类型映射注解​

另一种为特定消息类型指定默认 schema 信息的方式,是用 @PulsarMessage 注解标记消息类。可以通过注解上的 schemaType 属性来指定 schema 信息。
下面的示例将系统配置为:在生产或消费 Foo 类型的消息时,默认使用 JSON 作为 schema:
@PulsarMessage(schemaType = SchemaType.JSON)
record Foo(String value) {
}
有了这个配置之后,就无需再在监听器上设置 schema,例如:
@PulsarListener(subscriptionName = "user-sub", topics = "user-topic")
public void listen(User user) {
System.out.println(user);
}

3. 访问 Pulsar Consumer 对象​

有时你需要直接访问 Pulsar Consumer 对象。下面的示例展示了如何获取它:
@PulsarListener(subscriptionName = "hello-pulsar-subscription", topics = "hello-pulsar")
public void listen(String message, org.apache.pulsar.client.api.Consumer<String> consumer) {
System.out.println("Message Received: " + message);
ConsumerStats stats = consumer.getStats();
...
}
警告
以这种方式访问 Consumer 对象时,不要通过调用任何 receive 方法来改变 Consumer 的游标位置。所有这类操作都必须由容器来完成。

4. Pulsar 消息监听容器​

既然我们已经通过 PulsarListener 看到了消费者侧的基本交互,现在让我们深入了解 PulsarListener 如何与底层 Pulsar 消费者协作的内部机制。请记住,对于终端用户应用,在大多数场景下,当使用 Spring for Apache Pulsar 从 Pulsar 主题消费时,我们建议直接使用 PulsarListener 注解,因为该模型覆盖了广泛的应用使用场景。不过,理解 PulsarListener 的内部工作方式仍然很重要。本节将详细介绍这些内容。
如前简要提到的,当你使用 Spring for Apache Pulsar 时,消息监听容器处于消息消费的核心位置。PulsarListener 在幕后使用消息监听容器基础设施来创建和管理 Pulsar 消费者。Spring for Apache Pulsar 通过 PulsarMessageListenerContainer 提供这个消息监听容器的契约。该消息监听容器的默认实现由 DefaultPulsarMessageListenerContainer 提供。顾名思义,PulsarMessageListenerContainer 持有消息监听器。容器创建 Pulsar 消费者,然后运行一个单独的线程来接收和处理数据。数据由所提供的消息监听器实现来处理。
消息监听容器使用消费者的 batchReceive 方法批量消费数据。数据一旦被接收,就会被交给选定的消息监听器实现处理。
当你使用 Spring for Apache Pulsar 时,可以使用以下几种消息监听器类型。
我们将在后面的几节中看到这些消息监听器的详细信息。
不过,在此之前,让我们先仔细看一下容器本身。

4.1. DefaultPulsarMessageListenerContainer​

这是一个基于单消费者的消息监听容器。下面的代码清单展示了它的构造函数:
public DefaultPulsarMessageListenerContainer(PulsarConsumerFactory<? super T> pulsarConsumerFactory,
PulsarContainerProperties pulsarContainerProperties)
}
它接收一个 PulsarConsumerFactory(用于创建消费者)和一个 PulsarContainerProperties 对象(包含容器属性的信息)。PulsarContainerProperties 具有以下构造函数:
public PulsarContainerProperties(String... topics)

public PulsarContainerProperties(Pattern topicPattern)
你可以通过 PulsarContainerProperties 提供主题信息,也可以作为消费者属性提供给消费者工厂。下面的示例使用了 DefaultPulsarMessageListenerContainer:
Map<String, Object> config = new HashMap<>();
config.put("topics", "my-topic");
PulsarConsumerFactory<String> pulsarConsumerFactorY = DefaultPulsarConsumerFactory<>(pulsarClient, config);

PulsarContainerProperties pulsarContainerProperties = new PulsarContainerProperties();

pulsarContainerProperties.setMessageListener((PulsarRecordMessageListener<?>) (consumer, msg) -> {
});

DefaultPulsarMessageListenerContainer<String> pulsarListenerContainer = new DefaultPulsarMessageListenerContainer(pulsarConsumerFacotyr,
pulsarContainerProperties);

return pulsarListenerContainer;
备注
如果直接使用监听容器时没有指定主题信息,将使用与 PulsarListener 相同的主题解析流程,唯一的例外是"消息类型默认值"这一步会被省略。
DefaultPulsarMessageListenerContainer 只创建一个消费者。如果你希望通过多个线程管理多个消费者,则需要使用 ConcurrentPulsarMessageListenerContainer。

4.2. ConcurrentPulsarMessageListenerContainer​

ConcurrentPulsarMessageListenerContainer 具有以下构造函数:
public ConcurrentPulsarMessageListenerContainer(PulsarConsumerFactory<? super T> pulsarConsumerFactory,
PulsarContainerProperties pulsarContainerProperties)
ConcurrentPulsarMessageListenerContainer 允许你通过 setter 指定一个 concurrency 属性。并发数大于 1 只允许在非排他订阅(failover、shared 和 key-shared)上使用。当你使用排他订阅模式时,并发数只能取默认值 1。
下面的示例通过 PulsarListener 注解为一个 failover 订阅启用 concurrency。
@PulsarListener(topics = "my-topic", subscriptionName = "subscription-1",
subscriptionType = SubscriptionType.Failover, concurrency = "3")
void listen(String message, Consumer<String> consumer) {
...
System.out.println("Current Thread: " + Thread.currentThread().getName());
System.out.println("Current Consumer: " + consumer.getConsumerName());
}
在前面的监听器中,假定主题 my-topic 有三个分区。如果它是一个非分区主题,把并发数设置为 3 不会有任何效果——除了主活动消费者之外,你还会得到两个空闲的消费者。如果主题有超过三个分区,消息会在容器创建的各个消费者之间负载均衡。如果你运行这个 PulsarListener,会看到来自不同分区的消息通过不同的消费者被消费,正如上面示例中打印出的线程名和消费者名所表明的那样。
备注
当你以这种方式在分区主题上使用 Failover 订阅时,Pulsar 会保证消息的顺序。
下面的代码清单展示了另一个 PulsarListener 示例,但使用的是 Shared 订阅并启用了 concurrency。
@PulsarListener(topics = "my-topic", subscriptionName = "subscription-1",
subscriptionType = SubscriptionType.Shared, concurrency = "5")
void listen(String message) {
...
}
在前面的示例中,PulsarListener 创建了五个不同的消费者(这一次,我们假定主题有五个分区)。
备注
在这种情况下,没有消息顺序可言,因为 Shared 订阅在 Pulsar 中不保证任何消息顺序。
如果你既需要消息顺序、又想使用共享订阅类型,就需要使用 Key_Shared 订阅类型。

4.3. 消费记录​

让我们看一下消息监听容器是如何同时支持单条记录消费和基于批量的消息消费的。

单条记录消费​

为便于讨论,让我们回顾一下最基本的 PulsarListener:
@PulsarListener(subscriptionName = "hello-pulsar-subscription", topics = "hello-pulsar")
public void listen(String message) {
System.out.println("Message Received: " + message);
}
使用这个 PulsarListener 方法时,我们实际上是要求 Spring for Apache Pulsar 每次以一条记录来调用监听器方法。前面提到,消息监听容器使用消费者上的 batchReceive 方法批量消费数据。在本例中,框架检测到 PulsarListener 接收的是单条记录。这意味着每次调用该方法时,它只需要一条记录。虽然记录是由消息监听容器批量消费的,但它会遍历收到的批次,并通过一个适配 PulsarRecordMessageListener 的适配器来调用监听器方法。正如你在前面一节中看到的,PulsarRecordMessageListener 扩展自 Pulsar Java 客户端提供的 MessageListener,并支持基本的 received 方法。

批量消费​

下面的示例展示了批量消费记录的 PulsarListener:
@PulsarListener(subscriptionName = "hello-batch-subscription", topics = "hello-batch", schemaType = SchemaType.JSON, batch = true)
public void listen4(List<Foo> messages) {
System.out.println("records received :" + messages.size());
messages.forEach((message) -> System.out.println("record : " + message));
}
当你使用这种类型的 PulsarListener 时,框架会检测到你处于批量模式。由于它已经通过消费者的 batchReceive 方法批量接收了数据,它会把整个批次通过一个适配 PulsarBatchMessageListener 的适配器交给监听器方法处理。

5. Pulsar 消息头​

Pulsar 并没有一等的"header"概念,而是提供了一个用于自定义用户属性的 map,以及一些用于访问通常存放在消息头中的消息元数据(例如 id 和 event-time)的方法。因此,"Pulsar 消息头"和"Pulsar 消息元数据"这两个术语是可以互换使用的。可用的消息元数据(消息头)列表可以在 PulsarHeaders.java 中找到。

5.1. Spring 消息头​

Spring Messaging 通过其 MessageHeaders 抽象提供了一等的"header"支持。
Pulsar 消息元数据可以作为 Spring 消息头来消费。可用的消息头列表可以在 PulsarHeaders.java 中找到。

5.2. 在单条记录消费者中访问​

下面的示例展示了在使用单条记录消费模式的应用中,如何访问各种 Pulsar 消息头:
@PulsarListener(topics = "simpleListenerWithHeaders")
void simpleListenerWithHeaders(String data, @Header(PulsarHeaders.MESSAGE_ID) MessageId messageId,
@Header(PulsarHeaders.RAW_DATA) byte[] rawData,
@Header("foo") String foo) {

}
在前面的示例中,我们访问了 messageId 和 rawData 消息元数据的值,以及一个名为 foo 的自定义消息属性。每个消息头字段都使用了 Spring 的 @Header 注解。
你也可以使用 Pulsar 的 Message 作为承载负载的信封。这样做时,用户可以直接调用 Pulsar 消息上相应的方法来获取元数据。不过,为方便起见,你也可以使用 Header 注解来获取它。注意,你也可以使用 Spring 消息 Message 信封来承载负载,然后通过 @Header 获取 Pulsar 消息头。

5.3. 在批量记录消费者中访问​

在本节中,我们看看在使用批量消费者的应用中如何访问各种 Pulsar 消息头:
@PulsarListener(topics = "simpleBatchListenerWithHeaders", batch = true)
void simpleBatchListenerWithHeaders(List<String> data,
@Header(PulsarHeaders.MESSAGE_ID) List<MessageId> messageIds,
@Header(PulsarHeaders.TOPIC_NAME) List<String> topicNames, @Header("foo") List<String> fooValues) {

}
在前面的示例中,我们以 List<String> 的形式消费数据。在提取各个消息头时,我们同样以 List<> 的形式获取。Spring for Apache Pulsar 会确保消息头列表与数据列表一一对应。
当你使用批量监听器、并以 List<org.apache.pulsar.client.api.Message<?>、org.apache.pulsar.client.api.Messages<?> 或 org.springframework.messaging.Messsge<?> 的形式接收负载时,也可以以同样的方式提取消息头。

5.4. 消息头映射​

框架提供了 PulsarHeaderMapper 策略,用于在 Pulsar 用户属性与 Spring MessageHeaders 之间双向映射消息头。
它的接口定义如下:
public interface PulsarHeaderMapper {

Map<String, String> toPulsarHeaders(MessageHeaders springHeaders);

MessageHeaders toSpringHeaders(Message<?> pulsarMessage);
}
框架提供了几个映射器实现。
  • JsonPulsarHeaderMapper 将消息头映射为 JSON,以支持丰富的消息头类型;当 Jackson JSON 库在 classpath 上时,它是默认映射器。
  • ToStringPulsarHeaderMapper 使用消息头值的 toString() 方法将消息头映射为字符串,它是兜底映射器。
上述两种实现分别为:JsonPulsarHeaderMapper 将消息头映射为 JSON,以支持丰富的消息头类型,当 Jackson JSON 库在 classpath 上时它是默认映射器;ToStringPulsarHeaderMapper 使用消息头值的 toString() 方法将消息头映射为字符串,它是兜底映射器。

5.4.1. JSON 消息头映射器​

JsonPulsarHeaderMapper 使用一个"特殊"消息头(key 为 spring_json_header_types),其中包含一个 <key>:<type> 的 JSON map。这个消息头在入站侧(Pulsar → Spring)使用,用于将每个消息头值正确转换回原始类型。
受信任包​
默认情况下,JSON 映射器只会反序列化包名与以下安全默认值完全匹配的消息头类型:java.lang、java.net、java.util 和 org.springframework.util。包名不在受信任列表中的类会以 NonTrustedHeaderType 包装器的形式返回给应用,而不会被反序列化。
信任是按包名精确匹配来判定的。子包不会被传递性地信任:信任 java.util 并不会自动信任 java.util.concurrent 或 java.util.logging。你需要的每个包都必须显式列出。
要在不替换整个转换器的情况下,为注解驱动的监听器(@PulsarListener / @PulsarReader)扩展受信任集合,可以在应用上下文中注册一个名为 pulsarHeaderTrustedPackages 的 String[] bean:
@Bean(name = "pulsarHeaderTrustedPackages")
String[] pulsarHeaderTrustedPackages() {
return new String[] { "com.example.events", "com.example.dto" };
}
框架会自动拾取这个 bean,并将其应用到每一个监听器和 reader 端点上,同时与你可能另外定义的任何自定义 pulsarHeaderObjectMapper bean 组合使用。
如果你是通过 builder 直接构造 JsonPulsarHeaderMapper,则改为在那里传入包名:
@Bean
JsonPulsarHeaderMapper headerMapper() {
return JsonPulsarHeaderMapper.builder()
.trustedPackages("com.example.events", "com.example.dto")
.build();
}
要信任所有包——例如在完全受控的内部消息环境中——在上述任一方式中都把 "*" 作为唯一的条目传入:
// via bean
@Bean(name = "pulsarHeaderTrustedPackages")
String[] pulsarHeaderTrustedPackages() {
return new String[] { "*" };
}

// via builder
JsonPulsarHeaderMapper.builder().trustedPackages("*").build();
注意
使用 "*" 会允许 classpath 上可访问的任何类在反序列化入站消息头时被加载并部分实例化。当从不信任或外部来源消费消息时,不要使用它。
ToString 类​
某些类型不适合做 JSON 序列化,对这些类型可能更倾向于使用简单的 toString() 序列化。JsonPulsarHeaderMapper 有一个名为 addToStringClasses() 的属性,允许你提供应在出站映射时按此方式处理的类名。在入站映射时,它们会被映射为 String。默认情况下,只有 org.springframework.util.MimeType 和 org.springframework.http.MediaType 按此方式映射。
自定义 ObjectMapper​
JSON 映射器使用一个配置合理的 Jackson 2 ObjectMapper 来处理消息头值的序列化。不过,要提供自定义的对象映射器,只需提供一个名为 pulsarHeaderObjectMapper 的 ObjectMapper bean 即可。例如:
@Configuration(proxyBeanMethods = false)
static class PulsarHeadersCustomObjectMapperTestConfig {

@Bean(name = "pulsarHeaderObjectMapper")
ObjectMapper customObjectMapper() {
var objectMapper = new ObjectMapper();
// do things with your special header object mapper here
return objectMapper;
}
}
important
上面示例中的对象映射器应当是 com.fasterxml.jackson.databind.ObjectMapper 的实例,而不是经过 shade 的 org.apache.pulsar.shade.com.fasterxml.jackson.databind.ObjectMapper。
important
关于 Jackson 2 与 Jackson 3 的相同限制在此同样适用。

5.5. 入站/出站模式​

在入站侧,默认情况下所有 Pulsar 消息头(消息元数据加上用户属性)都会被映射到 MessageHeaders。在出站侧,默认情况下除了 id、timestamp 以及表示 Pulsar 消息元数据的消息头(即以 pulsar_message_ 为前缀的消息头)之外,所有 MessageHeaders 都会被映射。你可以通过在所提供的映射器 bean 上配置 inboundPatterns 和 outboundPatterns,来指定入站和出站消息分别映射哪些消息头。你可以通过把确切的消息头名加入 outboundPatterns 来让 Pulsar 消息元数据消息头出现在出站消息中,因为元数据消息头不支持通配模式。通配模式相当简单,可以包含前导通配符(*)、后导通配符,或两者兼有(例如 *.cat.*)。你可以用前导 ! 对模式取反。第一个匹配到消息头名的模式(无论肯定还是否定)胜出。
important
当你提供自己的模式时,我们建议同时包含 !id 和 !timestamp,因为这两个消息头在入站侧是只读的。

6. 消息确认​

当你使用 Spring for Apache Pulsar 时,消息确认由框架处理,除非应用选择退出。本节将详细介绍框架是如何处理消息确认的。

6.1. 消息 ACK 模式​

Spring for Apache Pulsar 提供以下几种消息确认模式:
  • BATCH
  • RECORD
  • MANUAL
BATCH 确认模式是默认值,但你可以在消息监听容器上更改它。在后面的几节中,我们看看在使用 PulsarListener 的单条和批量两种版本时确认是如何工作的,以及它们如何映射到底层的消息监听容器(并最终映射到 Pulsar 消费者)。

6.2. 单条记录模式下的自动消息确认​

让我们回顾一下最基本的、基于单条消息的 PulsarListener:
@PulsarListener(subscriptionName = "hello-pulsar-subscription", topics = "hello-pulsar")
public void listen(String message) {
System.out.println("Message Received: " + message);
}
人们很自然会想知道,使用 PulsarListener 时确认是如何工作的,尤其是如果你已经熟悉直接使用 Pulsar 消费者的话。答案在于消息监听容器,因为它是 Spring for Apache Pulsar 中协调所有消费者相关活动的中枢。
假设你没有覆盖默认行为,那么在使用上面的 PulsarListener 时,幕后会发生以下事情:
  1. 首先,监听容器以批次的形式从 Pulsar 消费者接收消息。
  2. 收到的消息被逐条交给 PulsarListener。
  3. 当批次中的所有记录都被交给监听器方法并成功处理后,容器会确认原始批次中的所有消息。
这是正常流程。如果原始批次中有任何记录抛出异常,Spring for Apache Pulsar 会单独跟踪这些记录。当批次中的所有记录处理完毕后,Spring for Apache Pulsar 会确认所有成功的消息,并对所有失败的消息做否定确认(nack)。换句话说,当使用 PulsarRecordMessageListener 消费单条记录、并使用默认的 BATCH 确认模式时,框架会等待 batchReceive 调用收到的所有记录都成功处理,然后在 Pulsar 消费者上调用 acknowledge 方法。如果某条记录在调用处理方法时抛出异常,Spring for Apache Pulsar 会跟踪这些记录,并在整个批次处理完毕后分别对这些记录调用 negativeAcknowledge。
如果应用希望按记录粒度进行确认或否定确认,可以启用 RECORD 确认模式。在这种情况下,每处理完一条记录,无错则确认该消息,有错则否定确认。下面的示例在 Pulsar 监听器上启用了 RECORD 确认模式:
@PulsarListener(subscriptionName = "hello-pulsar-subscription", topics = "hello-pulsar", ackMode = AckMode.RECORD)
public void listen(String message) {
System.out.println("Message Received: " + message);
}

6.3. 单条记录模式下的手动消息确认​

你可能并不总是希望由框架发送确认,而是希望直接从应用自身来做。Spring for Apache Pulsar 提供了几种启用手动消息确认的方式。下面的示例展示了其中一种:
@PulsarListener(subscriptionName = "hello-pulsar-subscription", topics = "hello-pulsar", ackMode = AckMode.MANUAL)
public void listen(Message<String> message, Acknowledgment acknowledgment) {
System.out.println("Message Received: " + message.getValue());
acknowledgment.acknowledge();
}
这里有几点需要说明。首先,我们通过在 PulsarListener 上设置 ackMode 来启用手动确认模式。启用手动确认模式时,Spring for Apache Pulsar 允许应用注入一个 Acknowledgment 对象。框架是通过选择一个兼容的消息监听容器来实现这一点的:对于基于单条记录的消费,选择 PulsarAcknowledgingMessageListener,它让你可以访问一个 Acknowledgment 对象。
Acknowledgment 对象提供以下 API 方法:
void acknowledge();

void acknowledge(MessageId messageId);

void acknowledge(List<MessageId> messageIds);

void nack();

void nack(MessageId messageId);
在使用 MANUAL 确认模式时,你可以把这个 Acknowledgment 对象注入到 PulsarListener 中,然后调用相应的方法之一。
在前面的 PulsarListener 示例中,我们调用的是一个无参的 acknowledge 方法。这是因为框架知道当前正在处理哪一个 Message。调用 acknowledge() 时,你不必用 Message 信封接收负载,而是直接使用目标类型——在本例中是 String。你也可以通过提供消息 ID 来调用 acknowledge 的另一个变体:acknowledge.acknowledge(message.getMessageId());。当使用 acknowledge(messageId) 时,你必须使用 Message<?> 信封来接收负载。
与确认类似,Acknowledgment API 也提供了否定确认的选项。参见前面展示的 nack 方法。
你也可以直接在 Pulsar 消费者上调用 acknowledge:
@PulsarListener(subscriptionName = "hello-pulsar-subscription", topics = "hello-pulsar", ackMode = AckMode.MANUAL)
public void listen(Message<String> message, Consumer<String> consumer) {
System.out.println("Message Received: " + message.getValue());
try {
consumer.acknowledge(message);
}
catch (Exception e) {
....
}
}
直接在底层消费者上调用 acknowledge 时,你需要自己做错误处理。使用 Acknowledgment 则不需要这样做,因为框架可以替你完成。因此,在使用手动确认时,你应该采用 Acknowledgment 对象的方式。
important
使用手动确认时,重要的是要明白框架完全不会做任何确认。因此,在设计应用时仔细考虑正确的确认策略至关重要。

6.4. 批量消费下的自动消息确认​

当你批量消费记录(参见"消息 ACK 模式")并使用默认的 BATCH 确认模式时,整个批次成功处理完毕后,整个批次会被确认。如果有任何记录抛出异常,整个批次会被否定确认。注意,这可能与在生产者侧攒批的那个批次并不相同——它是消费者上调用 batchReceive 返回的那个批次。
考虑下面这个批量监听器:
@PulsarListener(subscriptionName = "hello-pulsar-subscription", topics = "hello-pulsar", batch = true)
public void batchListen(List<Foo> messages) {
for (Foo foo : messages) {
...
}
}
当传入集合(本例中为 messages)中的所有消息都处理完毕后,框架会确认它们全部。
在批量模式下消费时,RECORD 不是允许的确认模式。这可能会带来问题,因为应用可能不希望整个批次被重新投递。在这种情况下,你需要使用 MANUAL 确认模式。

6.5. 批量消费下的手动消息确认​

如上一节所述,当消息监听容器上设置了 MANUAL 确认模式时,框架不会做任何确认——无论是肯定还是否定。这类问题完全由应用自行负责。设置 MANUAL 确认模式时,Spring for Apache Pulsar 会选择一个兼容的消息监听容器:对于批量消费,选择 PulsarBatchAcknowledgingMessageListener,它让你可以访问一个 Acknowledgment 对象。下面是 Acknowledgment API 中可用的方法:
void acknowledge();

void acknowledge(MessageId messageId);

void acknowledge(List<MessageId> messageIds);

void nack();

void nack(MessageId messageId);
在使用 MANUAL 确认模式时,你可以把这个 Acknowledgment 对象注入到 PulsarListener 中。下面的代码清单展示了一个基于批量的监听器的基本示例:
@PulsarListener(subscriptionName = "hello-pulsar-subscription", topics = "hello-pulsar")
public void listen(List<Message<String>> messgaes, Acknowlegement acknowledgment) {
for (Message<String> message : messages) {
try {
...
acknowledgment.acknowledge(message.getMessageId());
}
catch (Exception e) {
acknowledgment.nack(message.getMessageId());
}
}
}
当你使用批量监听器时,消息监听容器无法知道当前正在处理哪一条记录。因此,要手动确认,你需要使用接收 MessageId 或 List<MessageId> 的重载 acknowledge 方法之一。对于批量监听器,你也可以使用 MessageId 来做否定确认。

7. 消息重投与错误处理​

既然我们已经了解了 PulsarListener 和消息监听容器基础设施及其各项功能,现在让我们来理解消息重投与错误处理。Apache Pulsar 提供了多种用于消息重投和错误处理的原生策略。我们来看一下这些策略,并了解如何通过 Spring for Apache Pulsar 使用它们。

7.1. 指定用于消息重投的确认超时​

默认情况下,除非消费者崩溃,Pulsar 消费者不会重投消息,但你可以通过在 Pulsar 消费者上设置确认超时来改变这一行为。如果确认超时属性的值大于 0,并且 Pulsar 消费者在该超时时间内未确认某条消息,该消息就会被重投。
使用 Spring for Apache Pulsar 时,你可以通过消费者定制器,或者在 @PulsarListener 的 properties 属性中使用 Pulsar 原生的 ackTimeoutMillis 属性来设置它:
@PulsarListener(subscriptionName = "subscription-1", topics = "topic-1"
properties = {"ackTimeoutMillis=60000"})
public void listen(String s) {
...
}
当你指定了确认超时后,如果消费者在 60 秒内没有发送确认,Pulsar 就会把该消息重投给消费者。
如果你想为确认超时指定不同延迟的高级退避选项,可以这样做:
@EnablePulsar
@Configuration
class AckTimeoutRedeliveryConfig {

@PulsarListener(subscriptionName = "withAckTimeoutRedeliveryBackoffSubscription",
topics = "withAckTimeoutRedeliveryBackoff-test-topic",
ackTimeoutRedeliveryBackoff = "ackTimeoutRedeliveryBackoff",
properties = { "ackTimeoutMillis=60000" })
void listen(String msg) {
// some long-running process that may cause an ack timeout
}

@Bean
RedeliveryBackoff ackTimeoutRedeliveryBackoff() {
return MultiplierRedeliveryBackoff.builder().minDelayMs(1000).maxDelayMs(10 * 1000).multiplier(2)
.build();
}

}
在前面的示例中,我们为 Pulsar 的 RedeliveryBackoff 指定了一个 bean,最小延迟为 1 秒,最大延迟为 10 秒,退避乘数为 2。在最初的确认超时发生后,消息的重投就通过这个退避 bean 来控制。我们通过把 ackTimeoutRedeliveryBackoff 属性设置为实际的 bean 名——本例中为 ackTimeoutRedeliveryBackoff——将这个退避 bean 提供给 PulsarListener 注解。

7.2. 指定否定确认重投​

做否定确认时,Pulsar 消费者允许你指定应用希望如何重投消息。默认是在一分钟后重投消息,但你可以通过消费者定制器,或者在 @PulsarListener 的 properties 属性中使用 Pulsar 原生的 negativeAckRedeliveryDelay 属性来更改:
@PulsarListener(subscriptionName = "subscription-1", topics = "topic-1"
properties = {"negativeAckRedeliveryDelay=10ms"})
public void listen(String s) {
...
}
你也可以通过提供一个 RedeliveryBackoff bean,并把该 bean 名作为 negativeAckRedeliveryBackoff 属性设置到 PulsarProducer 上,来指定不同的延迟和带乘数的退避机制,如下所示:
@EnablePulsar
@Configuration
class NegativeAckRedeliveryConfig {

@PulsarListener(subscriptionName = "withNegRedeliveryBackoffSubscription",
topics = "withNegRedeliveryBackoff-test-topic", negativeAckRedeliveryBackoff = "redeliveryBackoff",
subscriptionType = SubscriptionType.Shared)
void listen(String msg) {
throw new RuntimeException("fail " + msg);
}

@Bean
RedeliveryBackoff redeliveryBackoff() {
return MultiplierRedeliveryBackoff.builder().minDelayMs(1000).maxDelayMs(10 * 1000).multiplier(2)
.build();
}

}

7.3. 使用 Apache Pulsar 死信队列进行消息重投与错误处理​

Apache Pulsar 允许应用在使用 Shared 订阅类型的消费者上使用死信队列主题。对于 Exclusive 和 Failover 订阅类型,此特性不可用。基本思路是:如果一条消息被重试了一定次数(可能是由于确认超时或 nack 重投),一旦重试次数耗尽,该消息就会被发送到一个称为死信队列(DLQ)的特殊主题。让我们通过查看一些代码片段来了解这个特性的实际细节:
@EnablePulsar
@Configuration
class DeadLetterPolicyConfig {

@PulsarListener(id = "deadLetterPolicyListener", subscriptionName = "deadLetterPolicySubscription",
topics = "topic-with-dlp", deadLetterPolicy = "deadLetterPolicy",
subscriptionType = SubscriptionType.Shared, properties = { "ackTimeoutMillis=1000" })
void listen(String msg) {
throw new RuntimeException("fail " + msg);
}

@PulsarListener(id = "dlqListener", topics = "my-dlq-topic")
void listenDlq(String msg) {
System.out.println("From DLQ: " + msg);
}

@Bean
DeadLetterPolicy deadLetterPolicy() {
return DeadLetterPolicy.builder().maxRedeliverCount(10).deadLetterTopic("my-dlq-topic").build();
}

}
首先,我们为 DeadLetterPolicy 指定了一个特殊的 bean,命名为 deadLetterPolicy(你可以随意命名)。这个 bean 指定了若干内容,例如最大投递次数(本例中为 10)以及死信队列主题的名称——本例中为 my-dlq-topic。如果你不指定 DLQ 主题名,Pulsar 会默认使用 <topicname>-<subscriptionname>-DLQ。接下来,我们通过设置 deadLetterPolicy 属性把这个 bean 名提供给 PulsarListener。注意,PulsarListener 使用的是 Shared 订阅类型,因为 DLQ 特性只适用于共享订阅。这段代码主要用于演示,所以我们把 ackTimeoutMillis 设为 1000。其思路是:代码抛出异常,如果 Pulsar 在 1 秒内没有收到确认,就进行重试。如果这个循环持续十次(因为这是我们在 DeadLetterPolicy 中设置的最大重投次数),Pulsar 消费者就会把消息发布到 DLQ 主题。我们还有另一个 PulsarListener,它监听 DLQ 主题,以便在消息被发布到 DLQ 主题时接收数据。
使用分区主题时关于 DLQ 主题的特别说明
如果主主题是分区主题,那么在幕后,每个分区都会被 Pulsar 当作一个独立的主题处理。Pulsar 会在主主题名后追加 partition-<n>,其中 n 代表分区编号。问题在于,如果你没有指定 DLQ 主题(与我们上面的做法相反),Pulsar 会发布到一个默认主题名,其中包含 `partition-<n> 信息——例如 topic-with-dlp-partition-0-deadLetterPolicySubscription-DLQ。解决这个问题的简单方法是:始终提供一个 DLQ 主题名。

7.4. Spring for Apache Pulsar 中的原生错误处理​

如前所述,Apache Pulsar 的 DLQ 特性只适用于共享订阅。如果应用需要在非共享订阅上使用类似的特性,该怎么办呢?Pulsar 不支持在排他和 failover 订阅上使用 DLQ 的主要原因在于,这些订阅类型是有顺序保证的。允许重投、DLQ 等机制实际上会导致乱序接收消息。不过,如果应用对此并不介意、而且更重要的是需要在非共享订阅上使用 DLQ 特性呢?为此,Spring for Apache Pulsar 提供了 PulsarConsumerErrorHandler,它可以跨 Pulsar 的任何订阅类型使用:Exclusive、Failover、Shared 或 Key_Shared。
当你使用 Spring for Apache Pulsar 的 PulsarConsumerErrorHandler 时,务必不要在监听器上设置确认超时属性。
让我们通过查看几个代码片段来了解细节:
@EnablePulsar
@Configuration
class PulsarConsumerErrorHandlerConfig {

@Bean
PulsarConsumerErrorHandler<String> pulsarConsumerErrorHandler(
PulsarTemplate<String> pulsarTemplate) {
return new DefaultPulsarConsumerErrorHandler<>(
new PulsarDeadLetterPublishingRecoverer<>(pulsarTemplate, (c, m) -> "my-foo-dlt"), new FixedBackOff(100, 10));
}

@PulsarListener(id = "pulsarConsumerErrorHandler-id", subscriptionName = "pulsatConsumerErrorHandler-subscription",
topics = "pulsarConsumerErrorHandler-topic",
pulsarConsumerErrorHandler = "pulsarConsumerErrorHandler")
void listen(String msg) {
throw new RuntimeException("fail " + msg);
}

@PulsarListener(id = "pceh-dltListener", topics = "my-foo-dlt")
void listenDlt(String msg) {
System.out.println("From DLT: " + msg);
}

}
看一下 pulsarConsumerErrorHandler bean。它创建了一个类型为 PulsarConsumerErrorHandler 的 bean,并使用 Spring for Apache Pulsar 开箱即提供的默认实现:DefaultPulsarConsumerErrorHandler。DefaultPulsarConsumerErrorHandler 有一个构造函数,接收一个 PulsarMessageRecovererFactory 和一个 org.springframework.util.backoff.Backoff。PulsarMessageRecovererFactory 是一个函数式接口,其 API 如下:
@FunctionalInterface
public interface PulsarMessageRecovererFactory<T> {

/**
* Provides a message recoverer {@link PulsarMessageRecoverer}.
* @param consumer Pulsar consumer
* @return {@link PulsarMessageRecoverer}.
*/
PulsarMessageRecoverer<T> recovererForConsumer(Consumer<T> consumer);

}
recovererForConsumer 方法接收一个 Pulsar 消费者,并返回一个 PulsarMessageRecoverer,后者是另一个函数式接口。下面是 PulsarMessageRecoverer 的 API:
public interface PulsarMessageRecoverer<T> {

/**
* Recover a failed message, for e.g. send the message to a DLT.
* @param message Pulsar message
* @param exception exception from failed message
*/
void recoverMessage(Message<T> message, Exception exception);

}
Spring for Apache Pulsar 为 PulsarMessageRecovererFactory 提供了一个名为 PulsarDeadLetterPublishingRecoverer 的实现,它提供了一个默认实现,可以通过把消息发送到死信队列主题(DLT)来恢复消息。我们把这个实现提供给上面 DefaultPulsarConsumerErrorHandler 的构造函数。作为第二个参数,我们提供一个 FixedBackOff。你也可以提供 Spring 的 ExponentialBackoff 以获得高级退避特性。然后我们把这个 bean 名作为 PulsarConsumerErrorHandler 属性提供给 PulsarListener。该属性名为 pulsarConsumerErrorHandler。每当 PulsarListener 方法处理某条消息失败时,该消息就会被重试。重试次数由所提供的 Backoff 实现的值控制。在我们的示例中,我们做 10 次重试(共 11 次尝试——第一次加上随后的 10 次重试)。一旦所有重试耗尽,该消息就会被发送到 DLT 主题。
我们提供的 PulsarDeadLetterPublishingRecoverer 实现使用一个 PulsarTemplate 来把消息发布到 DLT。在大多数情况下,Spring Boot 自动配置的同一个 PulsarTemplate 就足够了,但对于分区主题有一个注意事项。当使用分区主题、并且对主主题使用自定义消息路由时,你必须使用另一个不同的 PulsarTemplate,它所使用的 PulsarProducerFactory 的 message-routing-mode 不会被自动配置为 custompartition 的值。你可以按照下面的蓝图来使用 PulsarConsumerErrorHandler:
@Bean
PulsarConsumerErrorHandler<Integer> pulsarConsumerErrorHandler(PulsarClient pulsarClient) {
PulsarProducerFactory<Integer> pulsarProducerFactory = new DefaultPulsarProducerFactory<>(pulsarClient, Map.of());
PulsarTemplate<Integer> pulsarTemplate = new PulsarTemplate<>(pulsarProducerFactory);

BiFunction<Consumer<?>, Message<?>, String> destinationResolver =
(c, m) -> "my-foo-dlt";

PulsarDeadLetterPublishingRecoverer<Integer> pulsarDeadLetterPublishingRecoverer =
new PulsarDeadLetterPublishingRecoverer<>(pulsarTemplate, destinationResolver);

return new DefaultPulsarConsumerErrorHandler<>(pulsarDeadLetterPublishingRecoverer,
new FixedBackOff(100, 5));
}
注意,我们把一个目标解析器作为第二个构造参数提供给了 PulsarDeadLetterPublishingRecoverer。如果不提供,PulsarDeadLetterPublishingRecoverer 会使用 <subscription-name>-<topic-name>-DLT> 作为 DLT 主题名。使用这个特性时,你应该通过设置目标解析器来使用合适的目标名,而不是使用默认值。
当使用单条记录消息监听器时(就像我们在 PulsarConsumerErrorHnadler 中所做的那样),如果你使用手动确认,务必在抛出异常时不要对消息做否定确认,而应把异常重新抛回给容器。否则,容器会认为该消息已被单独处理,错误处理就不会被触发。
最后,我们还有第二个 PulsarListener,它从 DLT 主题接收消息。
在本节到目前为止给出的示例中,我们只看到了如何把 PulsarConsumerErrorHandler 用于单条记录消息监听器。接下来,我们看看如何在批量监听器上使用它。

7.5. 使用 PulsarConsumerErrorHandler 的批量监听器​

首先,让我们看一个批量 PulsarListener 方法:
@PulsarListener(subscriptionName = "batch-demo-5-sub", topics = "batch-demo-4", batch = true, concurrency = "3",
subscriptionType = SubscriptionType.Failover,
pulsarConsumerErrorHandler = "pulsarConsumerErrorHandler", ackMode = AckMode.MANUAL)
void listen(List<Message<Integer>> data, Consumer<Integer> consumer, Acknowledgment acknowledgment) {
for (Message<Integer> datum : data) {
if (datum.getValue() == 5) {
throw new PulsarBatchListenerFailedException("failed", datum);
}
acknowledgement.acknowledge(datum.getMessageId());
}
}

@Bean
PulsarConsumerErrorHandler<String> pulsarConsumerErrorHandler(
PulsarTemplate<String> pulsarTemplate) {
return new DefaultPulsarConsumerErrorHandler<>(
new PulsarDeadLetterPublishingRecoverer<>(pulsarTemplate, (c, m) -> "my-foo-dlt"), new FixedBackOff(100, 10));
}

@PulsarListener(subscriptionName = "my-dlt-subscription", topics = "my-foo-dlt")
void dltReceiver(Message<Integer> message) {
System.out.println("DLT - RECEIVED: " + message.getValue());
}
我们再次通过 pulsarConsumerErrorHandler 属性提供了 PulsarConsumerErrorHandler bean 名。当你使用批量监听器(如上面示例所示)并想使用 Spring for Apache Pulsar 的 PulsarConsumerErrorHandler 时,你需要使用手动确认。这样,你就可以对每一条成功的消息进行确认。对于失败的消息,你必须抛出一个带有失败消息的 PulsarBatchListenerFailedException。如果你抛出任何其他异常,框架会对整个批次做 nack 并记录一条警告,而不是应用错误处理器提供的逐条消息重试和恢复逻辑。重试时,容器会把一批新的消息发送给监听器,从那条失败的消息开始。如果再次失败,就继续重试,直到重试耗尽,届时该消息会被发送到 DLT。此后,该消息由容器确认,监听器继续处理原始批次中的后续消息。

8. 在 PulsarListener 上定制消费者​

Spring for Apache Pulsar 提供了一种便捷方式,用于定制由 PulsarListener 所使用的容器创建的消费者。应用可以为 PulsarListenerConsumerBuilderCustomizer 提供一个 bean。下面是一个示例。
@Bean
public PulsarListenerConsumerBuilderCustomizer<String> myCustomizer() {
return cb -> {
cb.subscriptionName("modified-subscription-name");
};
}
然后,可以把这个定制器 bean 名作为属性提供到 PuslarListener 注解上,如下所示。
@PulsarListener(subscriptionName = "my-subscription",
topics = "my-topic", consumerCustomizer = "myCustomizer")
void listen(String message) {

}
框架会通过 PulsarListener 检测到所提供的 bean,并在创建 Pulsar 消费者之前把该定制器应用到 Consumer builder 上。
如果你有多个 PulsarListener 方法,并且每个方法有不同的定制规则,你应该创建多个定制器 bean,并在每个 PulsarListener 上附加合适的定制器。

9. 消息监听容器生命周期​

9.1. 暂停与恢复​

有时应用可能希望临时暂停消息消费,稍后再恢复。Spring for Apache Pulsar 提供了暂停和恢复底层消息监听容器的能力。当 Pulsar 消息监听容器被暂停时,容器为从 Pulsar 消费者接收数据所做的任何轮询都会暂停。同样,当容器恢复时,如果主题在暂停期间新增了记录,下一次轮询就会开始返回数据。
要暂停或恢复一个监听容器,首先通过 PulsarListenerEndpointRegistry bean 获取容器实例,然后在容器实例上调用暂停/恢复 API——如下面的代码片段所示:
@Autowired
private PulsarListenerEndpointRegistry registry;

void someMethod() {
PulsarMessageListenerContainer container = registry.getListenerContainer("my-listener-id");
container.pause();
}
提示
传给 getListenerContainer 的 id 参数是容器 id——在暂停/恢复一个 @PulsarListener 时,它就是 @PulsarListener 的 id 属性的值。

9.2. 处理启动失败​

消息监听容器在应用上下文刷新时启动。默认情况下,启动过程中遇到的任何失败都会被重新抛出,应用将启动失败。你可以通过相应容器属性上的 StartupFailurePolicy 来调整这一行为。
可用的选项有:
  • Stop(默认)——记录日志并重新抛出异常,实际上会停止应用。
  • Continue——记录日志,让容器处于非运行状态,但不停止应用。
  • Retry——记录日志,异步重试启动容器,但不停止应用。
默认的重试行为是:重试 3 次,每次尝试之间间隔 10 秒。不过,你可以在相应容器属性上指定自定义的重试模板。如果重试耗尽后容器仍未能重启,它将被留在非运行状态。

9.2.1. 配置 {#_configuration}##### 使用 Spring Boot 时​

使用 Spring Boot 时,你可以注册一个 PulsarContainerFactoryCustomizer<ConcurrentPulsarListenerContainerFactory<?>> bean 来设置容器启动属性。
不使用 Spring Boot 时​
不过,如果你是手动配置这些组件,则在构造消息监听容器工厂时,需要相应地更新容器启动属性。

10. Pulsar Reader 支持​

框架通过 PulsarReaderFactory 提供了使用 Pulsar Reader 的支持。
Spring Boot 提供了这个 reader 工厂,你可以通过指定任何 spring.pulsar.reader.* 应用属性来进一步配置它。

10.1. PulsarReader 注解​

虽然可以直接使用 PulsarReaderFactory,但 Spring for Apache Pulsar 提供了 PulsarReader 注解,让你无需自己搭建任何 reader 工厂即可快速从主题读取。这与 PulsarListener 背后的思想类似。下面是一个简单的示例。
@PulsarReader(id = "reader-demo-id", topics = "reader-demo-topic", startMessageId = "earliest")
void read(String message) {
//...
}
id 属性是可选的,但最佳实践是提供一个对你的应用有意义的值。未指定时将使用自动生成的 id。另一方面,topics 和 startMessageId 属性是必填的。topics 属性可以是单个主题,也可以是逗号分隔的主题列表。startMessageId 属性指示 reader 从主题中的某条特定消息开始读取。startMessageId 的有效值为 earliest 或 latest.。假设你希望 reader 从主题中任意一条消息开始读取,而不是从最早或最新的可用消息开始。在这种情况下,你需要使用 ReaderBuilderCustomizer 来定制 ReaderBuilder,让它知道应从哪个 MessageId 开始。

10.2. 定制 ReaderBuilder​

在 Spring for Apache Pulsar 中,你可以使用 PulsarReaderReaderBuilderCustomizer 来定制通过 ReaderBuilder 可用的任何字段。你可以提供一个类型为 PulsarReaderReaderBuilderCustomizer 的 @Bean,然后让 PulsarReader 能够使用它,如下所示。
@PulsarReader(id = "reader-customizer-demo-id", topics = "reader-customizer-demo-topic",
readerCustomizer = "myCustomizer")
void read(String message) {
//...
}

@Bean
public PulsarReaderReaderBuilderCustomizer<String> myCustomizer() {
return readerBuilder -> {
readerBuilder.startMessageId(messageId); // the first message read is after this message id.
// Any other customizations on the readerBuilder
};
}
提示
如果你的应用只有一个 @PulsarReader,并且只注册了一个 PulsarReaderReaderBuilderCustomizer bean,那么该定制器将被自动应用。

10.3. 处理启动失败​

消息监听容器在应用上下文刷新时启动。默认情况下,启动过程中遇到的任何失败都会被重新抛出,应用将启动失败。你可以通过相应容器属性上的 StartupFailurePolicy 来调整这一行为。
可用的选项有:
  • Stop(默认)——记录日志并重新抛出异常,实际上会停止应用。
  • Continue——记录日志,让容器处于非运行状态,但不停止应用。
  • Retry——记录日志,异步重试启动容器,但不停止应用。
默认的重试行为是:重试 3 次,每次尝试之间间隔 10 秒。不过,你可以在相应容器属性上指定自定义的重试模板。如果重试耗尽后容器仍未能重启,它将被留在非运行状态。

10.3.1. 配置 {#_configuration_2}##### 使用 Spring Boot 时​

使用 Spring Boot 时,你可以注册一个 PulsarContainerFactoryCustomizer<DefaultPulsarReaderContainerFactory<?>> bean 来设置容器启动属性。
不使用 Spring Boot 时​
不过,如果你是手动配置这些组件,则在构造消息监听容器工厂时,需要相应地更新容器启动属性。