消息生产
目录
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。
当前支持的复杂 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 定制器时必须谨慎。
规则: 两个以 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();
}
规则: 如果你的 Lambda 定制器不是只定义一次(后续调用使用同一实例),或者它引用了闭包之外定义的变量,那么你必须提供一个具有有效 equals/hashCode 实现的定制器实现。
如果不遵循这些规则,生产者缓存将始终未命中,应用程序性能会受到负面影响。
5. 在生产者上拦截消息
添加一个 ProducerInterceptor 让你可以在消息发布到 broker 之前拦截并修改生产者收到的消息。为此,你可以将拦截器列表传入 PulsarTemplate 构造函数。使用多个拦截器时,应用顺序就是它们在列表中出现的顺序。
如果你使用 Spring Boot 自动配置,可以将拦截器指定为 bean。它们会自动传入 PulsarTemplate。拦截器的排序通过 @Order 注解实现,如下所示:
@Bean
@Order(100)
ProducerInterceptor firstInterceptor() {
...
}
@Bean
@Order(200)
ProducerInterceptor secondInterceptor() {
...
}
如果你不使用 starter,则需要自己配置并注册前述组件。