事务
本节介绍 Spring for Apache Pulsar 如何支持事务。
概述
Spring for Apache Pulsar 的事务支持构建于 Spring Framework 提供的事务支持之上。从较高层面看,事务性资源会注册到一个事务管理器,由该管理器负责处理已注册资源的事务状态(提交、回滚等)。
Spring for Apache Pulsar 提供以下内容:
PulsarTransactionManager——用于常规 Spring 事务支持(@Transactional、TransactionTemplate等)- 事务性的
PulsarTemplate - 事务性的
@PulsarListener - 与其他事务管理器的事务同步
事务支持默认禁用。使用 Spring Boot 时,要启用支持,只需设置 spring.pulsar.transaction.enabled 属性。更多配置选项见下面各组件章节。
使用 PulsarTemplate 进行事务性发布
事务性 PulsarTemplate 上的所有发送操作都会查找活动事务,并将每次发送操作登记到该事务中(如果找到的话)。
非事务性使用
默认情况下,事务性 PulsarTemplate 也可用于非事务性操作。当未找到现有事务时,它会以非事务方式继续发送操作。不过,如果 template 被配置为要求事务,那么在事务范围之外使用 template 的任何尝试都会导致异常。
事务可以由 TransactionTemplate、@Transactional 方法、调用 executeInTransaction 或事务性监听容器启动。
本地事务
我们使用“本地”事务一词来表示一种 Pulsar 原生事务,它不被 Spring 事务管理设施管理或与之关联(即 PulsarTransactionManager)。反之,“同步”事务是指被 PulsarTransactionManager 管理或与之关联的事务。
你可以使用 PulsarTemplate 在本地事务中执行一系列操作。以下示例展示了如何这样做:
var results = pulsarTemplate.executeInTransaction((template) -> {
var rv = new HashMap<String, MessageId>();
rv.put("msg1", template.send(topic, "msg1"));
rv.put("msg2", template.send(topic, "msg2"));
return rv;
});
回调中的参数是调用 executeInTransaction 时所在的 template 实例。对 template 的所有操作都登记到当前事务中。如果回调正常退出,则提交事务;如果抛出异常,则回滚事务。
如果正在进行同步事务,它会被忽略,而使用一个新的“嵌套”事务。
配置
以下事务设置可直接在 PulsarTemplate 上(通过 transactions 字段)获得:
enabled——template 是否支持事务(默认false)required——template 是否要求事务(默认false)timeout——事务超时时间(默认null)
不使用 Spring Boot 时,你可以在所提供的 template 上调整这些设置。不过,使用 Spring Boot 时,template 是自动配置的,没有机制来影响这些属性。在这种情况下,你可以注册一个 PulsarTemplateCustomizer bean 来调整设置。以下示例展示了如何在自动配置的 template 上设置超时:
@Bean
PulsarTemplateCustomizer<?> templateCustomizer() {
return (template) -> template.transactions().setTimeout(Duration.ofSeconds(45));
}
使用 @PulsarListener 进行事务性接收
当启用监听事务时,@PulsarListener 注解的监听方法会在一个同步事务的范围内被调用。
DefaultPulsarMessageListenerContainer 使用一个配置了 PulsarTransactionManager 的 Spring TransactionTemplate,在方法调用之前启动事务。
每条收到消息的确认都会登记到该范围内的事务中。
消费-处理-生产场景
一种常见的事务性模式是:消费者从 Pulsar topic 读取消息,转换消息,最后由生产者将结果消息写入另一个 Pulsar topic。当启用事务且你的监听方法使用事务性 PulsarTemplate 来生产转换后的消息时,框架支持这一用例。
给定以下监听方法:
@PulsarListener(topics = "my-input-topic") 1
void listen(String msg) { 2
var transformedMsg = msg.toUpperCase(Locale.ROOT); 3
this.transactionalTemplate.send("my-output-topic", transformedMsg); 4
} // <5> // <6>
启用监听事务时会发生以下交互:
监听容器启动新事务,并在事务范围内调用监听方法
监听方法接收消息
监听方法转换消息
监听方法用事务性 template 发送转换后的消息,该 template 将发送操作登记到活动事务中
监听容器自动确认消息,并将确认操作登记到活动事务中
监听容器(通过
TransactionTemplate)提交事务
如果你不使用 @PulsarListener,而是直接使用监听容器,同样能获得前述事务支持。记住,@PulsarListener 只是把一个 Java 方法注册为监听容器消息监听器的便捷方式。
记录监听器的事务
上述示例使用的是记录监听器。使用记录监听器时,每次监听方法调用都会创建一个新事务,即每条消息一个事务。
由于事务边界是每条消息一个,且每条消息确认都登记到各自事务中,批量确认模式不能与事务性记录监听器一起使用。
批量监听器的事务
使用批量监听器时,每次监听方法调用都会创建一个新事务,即每批消息一个事务。
事务性批量监听器目前不支持自定义错误处理器。
配置
监听容器工厂
以下事务设置可直接在 ConcurrentPulsarListenerContainerFactory 创建监听容器时所使用的 PulsarContainerProperties 上获得。这些设置会影响所有监听容器,包括 @PulsarListener 所使用的容器。
enabled——容器是否支持事务(默认false)required——容器是否要求事务(默认false)timeout——事务超时时间(默认null)transactionDefinition——一个蓝图事务定义,其属性将被复制到容器的事务模板(默认null)transactionManager——用于启动事务的事务管理器
不使用 Spring Boot 时,你可以在所提供的容器工厂上调整这些设置。不过,使用 Spring Boot 时,容器工厂是自动配置的。在这种情况下,你可以注册一个 org.springframework.boot.pulsar.autoconfigure.PulsarContainerFactoryCustomizer<ConcurrentPulsarListenerContainerFactory<?>> bean 来访问并定制容器属性。以下示例展示了如何在容器工厂上设置超时:
@Bean
PulsarContainerFactoryCustomizer<ConcurrentPulsarListenerContainerFactory<?>> containerCustomizer() {
return (containerFactory) -> containerFactory.getContainerProperties().transactions().setTimeout(Duration.ofSeconds(45));
}
@PulsarListener
默认情况下,每个监听器遵循其对应监听容器工厂的事务设置。不过,用户可以在每个 @PulsarListener 上设置 transactional 属性来覆盖容器工厂设置,如下所示:
- 如果容器工厂启用了事务,那么
transactional = false将为该单独监听器禁用事务。 - 如果容器工厂启用并要求事务,那么尝试设置
transactional = false将导致抛出异常,指出事务是必需的。 - 如果容器工厂禁用了事务,那么尝试设置
transactional = true将被忽略,并记录一条警告。
使用 PulsarTransactionManager
PulsarTransactionManager 是 Spring Framework PlatformTransactionManager 的一个实现。你可以将 PulsarTransactionManager 用于常规 Spring 事务支持(@Transactional、TransactionTemplate 等)。
如果事务处于活动状态,在该事务范围内执行的任何 PulsarTemplate 操作都会登记并参与到正在进行的事务中。管理器根据成功或失败提交或回滚事务。
你可能不需要直接使用 PulsarTransactionManager,因为大多数事务性用例已由 PulsarTemplate 和 @PulsarListener 覆盖。
Pulsar 事务与其他事务管理器
仅生产者事务
如果你想向 Pulsar 发送记录并在单个事务中执行一些数据库更新,可以使用常规 Spring 事务管理配合 DataSourceTransactionManager。
以下示例假设有一个以 "dataSourceTransactionManager" 名称注册的 DataSourceTransactionManager bean。
@Transactional("dataSourceTransactionManager")
public void myServiceMethod() {
var msg = calculateMessage();
this.pulsarTemplate.send("my-topic", msg);
this.jdbcTemplate.execute("insert into my_table (data) values ('%s')".formatted(msg));
}
@Transactional 注解的拦截器启动数据库事务,PulsarTemplate 会将一个事务与 DB 事务管理器同步;每次发送都会参与该事务。方法退出时,数据库事务先提交,随后 Pulsar 事务提交。
如果你希望先提交 Pulsar 事务,并且仅在 Pulsar 事务成功时才提交 DB 事务,可以使用嵌套的 @Transactional 方法,外层方法配置为使用 DataSourceTransactionManager,内层方法配置为使用 PulsarTransactionManager。
@Transactional("dataSourceTransactionManager")
public void myServiceMethod() {
var msg = calculateMessage();
this.jdbcTemplate.execute("insert into my_table (data) values ('%s')".formatted(msg));
this.sendToPulsar(msg);
}
@Transactional("pulsarTransactionManager")
public void sendToPulsar(String msg) {
this.pulsarTemplate.send("my-topic", msg);
}
消费者 + 生产者事务
如果你想从 Pulsar 消费记录、向 Pulsar 发送记录,并在一个事务中执行一些数据库更新,可以将常规 Spring 事务管理(使用 DataSourceTransactionManager)与容器启动的事务结合起来。
在以下示例中,监听容器启动 Pulsar 事务,@Transactional 注解启动 DB 事务。DB 事务先提交;如果 Pulsar 事务提交失败,记录会被重新投递,因此 DB 更新应当是幂等的。
@PulsarListener(topics = "my-input-topic")
@Transactional("dataSourceTransactionManager")
void listen(String msg) {
var transformedMsg = msg.toUpperCase(Locale.ROOT);
this.pulsarTemplate.send("my-output-topic", transformedMsg);
this.jdbcTemplate.execute("insert into my_table (data) values ('%s')".formatted(transformedMsg));
}