跳到主要内容
版本:2.0.7

消息生产

Doubao 中英对照 Message Production

目录

1. Pulsar 模板​

在 Pulsar 生产者端,Spring Boot 自动配置提供了一个 PulsarTemplate 用于发布记录。该 template 实现了名为 PulsarOperations 的接口,并提供通过其契约发布记录的方法。

这些发送 API 方法分为两类:send 和 sendAsync。send 方法通过使用 Pulsar 生产者上的同步发送能力来阻塞调用。一旦消息持久化到 broker,它们返回所发布消息的 MessageId。sendAsync 方法调用是非阻塞的异步调用。它们返回一个 CompletableFuture,你可以用它在消息发布后异步接收消息 ID。

备注

对于不包含 topic 参数的 API 变体,会使用 topic 解析过程 来确定目标 topic。

1.1. 简单 API​

template 提供了少量方法(以 'send' 为前缀)用于简单的发送请求。对于更复杂的发送请求,fluent API 让你可以配置更多选项。

1.2. Fluent API​

template 提供了一个 fluent builder 来处理更复杂的发送请求。

1.3. 消息定制​

你可以指定一个 TypedMessageBuilderCustomizer 来配置出站消息。例如,以下代码展示了如何发送带 key 的消息:

template.newMessage(msg)
.withMessageCustomizer((mb) -> mb.key("foo-msg-key"))
.send();

1.4. 生产者定制​

你可以指定一个 ProducerBuilderCustomizer 来配置底层 Pulsar 生产者 builder,该 builder 最终构造用于发送出站消息的生产者。

注意

请谨慎使用,因为这会完全访问生产者 builder,调用其某些方法(例如 create)可能产生意外副作用。

例如,以下代码展示了如何禁用批处理并启用分块:

template.newMessage(msg)
.withProducerCustomizer((pb) -> pb.enableChunking(true).enableBatching(false))
.send();

另一个示例展示了向分区 topic 发布记录时如何使用自定义路由。在 Producer builder 上指定你的自定义 MessageRouter 实现,如下所示:

template.newMessage(msg)
.withProducerCustomizer((pb) -> pb.messageRouter(messageRouter))
.send();
提示

注意,使用 MessageRouter 时,spring.pulsar.producer.message-routing-mode 唯一有效的设置是 custom。

另一个示例展示了如何添加一个 ProducerInterceptor,它会在消息发布到 broker 之前拦截并修改生产者收到的消息:

template.newMessage(msg)
.withProducerCustomizer((pb) -> pb.intercept(interceptor))
.send();

该定制器仅应用于发送操作所使用的生产者。如果你想将定制器应用于所有生产者,必须按全局生产者定制所述将其提供给生产者工厂。

警告

使用 Lambda 定制器时,必须遵循“Lambda 定制器注意事项”中所述的规则。

2. 指定 Schema 信息​

如果你使用 Java 基本类型,框架会自动为你检测 schema,发布数据时无需指定任何 schema 类型。对于非基本类型,如果在 PulsarTemplate 上调用发送操作时未显式指定 Schema,Spring for Apache Pulsar 框架会尝试根据类型构建一个 Schema.JSON。

important

当前支持的复杂 Schema 类型有 JSON、AVRO、PROTOBUF、AUTO_PRODUCE_BYTES 和带 INLINE 编码的 KEY_VALUE。

2.1. 自定义 Schema 映射​

作为在 PulsarTemplate 上为复杂类型调用发送操作时指定 schema 的替代方案,可以为 schema 解析器配置类型映射。这样就无需指定 schema,因为框架会根据出站消息类型查询解析器。

2.1.1. 配置属性​

可以使用 spring.pulsar.defaults.type-mappings 属性配置 schema 映射。以下示例使用 application.yml,分别用 AVRO 和 JSON schema 为 User 和 Address 复杂对象添加映射:

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 解析器定制器,分别用 AVRO 和 JSON schema 为 User 和 Address 复杂对象添加映射:

@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。

2.2. 使用 AUTO_SCHEMA 生产​

如果无法提前知道 Pulsar topic 的 schema 类型,你可以使用 AUTO_PRODUCE schema 来安全地将原始 JSON 或 Avro 载荷作为 byte[] 发布。

在这种情况下,生产者会校验出站字节是否与目标 topic 的 schema 兼容。

只需在 template 发送操作上指定 Schema.AUTO_PRODUCE_BYTES() schema,如下例所示:

void sendUserAsBytes(PulsarTemplate<byte[]> template, byte[] userAsBytes) {
template.send("user-topic", userAsBytes, Schema.AUTO_PRODUCE_BYTES());
}
备注

这仅支持 Avro 和 JSON schema 类型。

3. Pulsar 生产者工厂​

PulsarTemplate 依赖一个 PulsarProducerFactory 来实际创建底层生产者。Spring Boot 自动配置也提供了这个生产者工厂,你可以通过指定任何 spring.pulsar.producer.* 应用属性来进一步配置它。

备注

直接使用生产者工厂 API 时,如果未指定 topic 信息,会使用与 PulsarTemplate 相同的 topic 解析过程,唯一的例外是会省略“消息类型默认”步骤。

3.1. 全局生产者定制​

框架提供了 ProducerBuilderCustomizer 契约,让你可以配置用于构造每个生产者的底层 builder。要定制所有生产者,可以将定制器列表传入 PulsarProducerFactory 构造函数。使用多个定制器时,按它们在列表中出现的顺序应用。

提示

如果你使用 Spring Boot 自动配置,可以将定制器指定为 bean,它们会自动传入 PulsarProducerFactory,并按其 @Order 注解排序。

如果只想将定制器应用于单个生产者,可以使用 Fluent API 并在发送时指定定制器。

4. Pulsar 生产者缓存​

每个底层 Pulsar 生产者都会消耗资源。为提高性能并避免不断创建生产者,生产者工厂会缓存它所创建的生产者。它们以 LRU 方式缓存,并在配置的时间段内未被使用时被淘汰。缓存键由刚好足够的信息组成,以确保后续创建请求时向调用者返回同一个生产者。

此外,你可以通过指定任何 spring.pulsar.producer.cache.* 应用属性来配置缓存设置。

4.1. Lambda 定制器注意事项​

任何用户提供的生产者定制器也会包含在缓存键中。由于缓存键依赖于有效的 equals/hashCode 实现,使用 Lambda 定制器时必须谨慎。

important

规则: 两个以 Lambda 实现的定制器会在 equals/hashCode 上匹配,当且仅当它们使用同一个 Lambda 实例,且不引用其闭包之外定义的任何变量。

为阐明上述规则,我们看几个示例。在以下示例中,定制器定义为内联 Lambda,这意味着每次调用 sendUser 都使用同一个 Lambda 实例。此外,它不引用闭包之外的变量。因此,它会作为缓存键匹配。

void sendUser() {
var user = randomUser();
template.newMessage(user)
.withTopic("user-topic")
.withProducerCustomizer((b) -> b.producerName("user"))
.send();
}

在下一个情况中,定制器定义为内联 Lambda,这意味着每次调用 sendUser 都使用同一个 Lambda 实例。不过,它引用了闭包之外的变量。因此,它不会作为缓存键匹配。

void sendUser() {
var user = randomUser();
var name = randomName();
template.newMessage(user)
.withTopic("user-topic")
.withProducerCustomizer((b) -> b.producerName(name))
.send();
}

在最后这个示例中,定制器定义为内联 Lambda,这意味着每次调用 sendUser 都使用同一个 Lambda 实例。虽然它确实使用了变量 name,但该变量并非源自闭包之外,因此会作为缓存键匹配。这说明变量可以在 Lambda 闭包内部使用,甚至可以调用静态方法。

void sendUser() {
var user = randomUser();
template.newMessage(user)
.withTopic("user-topic")
.withProducerCustomizer((b) -> {
var name = SomeHelper.someStaticMethod();
b.producerName(name);
})
.send();
}
important

规则: 如果你的 Lambda 定制器不是只定义一次(后续调用使用同一实例),或者它引用了闭包之外定义的变量,那么你必须提供一个具有有效 equals/hashCode 实现的定制器实现。

注意

如果不遵循这些规则,生产者缓存将始终未命中,应用程序性能会受到负面影响。

5. 在生产者上拦截消息​

添加一个 ProducerInterceptor 让你可以在消息发布到 broker 之前拦截并修改生产者收到的消息。为此,你可以将拦截器列表传入 PulsarTemplate 构造函数。使用多个拦截器时,应用顺序就是它们在列表中出现的顺序。

如果你使用 Spring Boot 自动配置,可以将拦截器指定为 bean。它们会自动传入 PulsarTemplate。拦截器的排序通过 @Order 注解实现,如下所示:

@Bean
@Order(100)
ProducerInterceptor firstInterceptor() {
...
}

@Bean
@Order(200)
ProducerInterceptor secondInterceptor() {
...
}
备注

如果你不使用 starter,则需要自己配置并注册前述组件。