深度解析 `@TransactionEventListener` 注解

于 2025-06-30 08:16:32 发布
阅读量949 收藏 12
点赞数 10
CC 4.0 BY-SA版权
分类专栏： Spring 文章标签： spring 事务 学习
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/csdn_tom_168/article/details/148925872

深度解析 @TransactionEventListener 注解

@TransactionEventListener 是 Spring 框架中用于处理事务事件的核心注解，它提供了一种强大机制来响应事务生命周期中的关键节点。本文将全面解析该注解的工作原理、使用场景及源码实现，帮助开发者深入掌握事务事件处理机制。

一、核心概念与工作原理

1. 事务事件的生命周期

Spring 事务生命周期包含以下关键阶段：

  • BEFORE_COMMIT: 事务提交前触发
  • AFTER_COMMIT: 事务成功提交后触发
  • AFTER_ROLLBACK: 事务回滚后触发
  • AFTER_COMPLETION: 事务最终完成后触发（无论提交或回滚）
是
否
开始事务
BEFORE_COMMIT
提交成功?
AFTER_COMMIT
AFTER_ROLLBACK
AFTER_COMPLETION

2. @TransactionEventListener 与 @EventListener 的区别

特性@TransactionEventListener@EventListener
触发时机绑定事务阶段立即触发
事务保障与事务结果同步无事务关联
执行条件可依赖事务结果无条件
资源访问可访问事务资源独立上下文
错误处理影响事务结果独立异常流

二、注解定义与属性解析

1. 注解源码

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@EventListener
public @interface TransactionEventListener {
    // 事务阶段（默认AFTER_COMMIT）
    TransactionPhase phase() default TransactionPhase.AFTER_COMMIT;
    
    // 无事务时是否执行（默认false）
    boolean fallbackExecution() default false;
    
    // 事件类型（从@EventListener继承）
    @AliasFor(annotation = EventListener.class, attribute = "classes")
    Class<?>[] value() default {};
    
    @AliasFor(annotation = EventListener.class, attribute = "classes")
    Class<?>[] classes() default {};
    
    // 条件表达式（从@EventListener继承）
    @AliasFor(annotation = EventListener.class, attribute = "condition")
    String condition() default "";
}

2. 核心属性详解

1. phase 事务阶段

public enum TransactionPhase {
    BEFORE_COMMIT,   // 提交前阶段
    AFTER_COMMIT,     // 提交后阶段（默认）
    AFTER_ROLLBACK,   // 回滚后阶段
    AFTER_COMPLETION  // 完成阶段（无论结果）
}

2. fallbackExecution 无事务回退

  • true: 无事务时仍执行监听器
  • false: 仅在事务上下文中执行（默认）

3. condition SpEL 表达式

@TransactionEventListener(
    condition = "#event.order.amount > 1000"
)
public void handleLargeOrder(OrderEvent event) {
    // 处理大额订单
}

三、核心源码深度解析

1. 核心处理流程

事件发布者ApplicationContextEventListenerMethodProcessorEventListenerFactoryApplicationListenerMethodTransactionalAdapterTransactionSynchronizationManagerTargetpublishEvent(event)获取匹配监听器创建监听适配器返回TransactionalAdapter注册事务同步器事务阶段到来调用同步器方法执行监听方法事件发布者ApplicationContextEventListenerMethodProcessorEventListenerFactoryApplicationListenerMethodTransactionalAdapterTransactionSynchronizationManagerTarget

2. 关键类解析

TransactionalEventListenerFactory

public class TransactionalEventListenerFactory implements EventListenerFactory {
    
    @Override
    public boolean supportsMethod(Method method) {
        return AnnotatedElementUtils.hasAnnotation(method, TransactionEventListener.class);
    }
    
    @Override
    public ApplicationListener<?> createApplicationListener(
        String beanName, Class<?> type, Method method) {
        
        return new ApplicationListenerMethodTransactionalAdapter(beanName, type, method);
    }
}

ApplicationListenerMethodTransactionalAdapter

class ApplicationListenerMethodTransactionalAdapter extends ApplicationListenerMethodAdapter {
    
    @Override
    public void onApplicationEvent(ApplicationEvent event) {
        // 有事务上下文时
        if (TransactionSynchronizationManager.isSynchronizationActive()) {
            // 创建事务同步器
            TransactionSynchronization synchronization = createTransactionSynchronization(event);
            // 注册到当前事务
            TransactionSynchronizationManager.registerSynchronization(synchronization);
        } 
        // 无事务但启用fallback
        else if (isFallbackExecution()) {
            processEvent(event);
        }
    }
    
    private TransactionSynchronization createTransactionSynchronization(ApplicationEvent event) {
        return new TransactionalApplicationListenerSynchronization<>(this, event);
    }
}

TransactionalApplicationListenerSynchronization

private static class TransactionalApplicationListenerSynchronization<Event extends ApplicationEvent>
        implements TransactionSynchronization {
    
    private final ApplicationListenerMethodAdapter listener;
    private final Event event;
    
    // 事务阶段处理方法
    @Override
    public void beforeCommit(boolean readOnly) {
        if (getPhase() == TransactionPhase.BEFORE_COMMIT) {
            processEventWithTransactionStatus(STATUS_UNKNOWN);
        }
    }
    
    @Override
    public void afterCompletion(int status) {
        TransactionPhase phase = getPhase();
        // 根据阶段和状态触发
        if (phase == TransactionPhase.AFTER_COMMIT && status == STATUS_COMMITTED) {
            processEventWithTransactionStatus(status);
        } else if (phase == TransactionPhase.AFTER_ROLLBACK && status == STATUS_ROLLED_BACK) {
            processEventWithTransactionStatus(status);
        } else if (phase == TransactionPhase.AFTER_COMPLETION) {
            processEventWithTransactionStatus(status);
        }
    }
    
    private void processEventWithTransactionStatus(int transactionStatus) {
        // 传递事务状态给监听器
        getListener().processEvent(getEvent(), transactionStatus);
    }
}

四、高级应用场景

场景1：订单处理 - 各阶段事件处理

public class OrderService {
    @Transactional
    public void processOrder(Order order) {
        // 业务处理...
        applicationEventPublisher.publishEvent(new OrderProcessEvent(order));
    }
}

public class OrderListeners {
    
    @TransactionEventListener(phase = BEFORE_COMMIT)
    public void validateOrder(OrderProcessEvent event) {
        // 提交前最终验证
        if (!inventoryService.checkStock(event.getOrder())) {
            throw new InsufficientStockException();
        }
    }
    
    @TransactionEventListener(phase = AFTER_COMMIT)
    public void notifyUser(OrderProcessEvent event) {
        // 提交成功后通知用户
        notificationService.sendOrderConfirmed(event.getOrder());
    }
    
    @TransactionEventListener(phase = AFTER_ROLLBACK)
    public void handleFailure(OrderProcessEvent event) {
        // 回滚后执行补偿操作
        compensationService.compensateOrder(event.getOrder());
    }
}

场景2：审计日志 - 事务感知的记录

@TransactionEventListener(phase = AFTER_COMPLETION)
public void auditLog(OrderProcessEvent event, int status) {
    AuditLog log = new AuditLog()
        .setEventType(event.getClass().getSimpleName())
        .setEventTime(LocalDateTime.now())
        .setTransactionStatus(status == STATUS_COMMITTED ? "COMMITTED" : "ROLLED_BACK");
    
    // 保存审计日志（新事务）
    transactionTemplate.executeWithoutResult(tx -> {
        auditRepository.save(log);
    });
}

场景3：分布式事务协调

@TransactionEventListener(phase = BEFORE_COMMIT)
public void prepareSaga(OrderEvent event) {
    // 开启Saga事务
    String sagaId = sagaCoordinator.startSaga(event.getOrder());
    event.setSagaId(sagaId);
}

@TransactionEventListener(phase = AFTER_COMMIT)
public void commitSaga(OrderEvent event) {
    // 提交Saga事务
    sagaCoordinator.commitSaga(event.getSagaId());
}

@TransactionEventListener(phase = AFTER_ROLLBACK)
public void rollbackSaga(OrderEvent event) {
    // 回滚Saga事务
    sagaCoordinator.rollbackSaga(event.getSagaId());
}

五、事务阶段状态传递

监听器获取事务状态

@TransactionEventListener(phase = AFTER_COMPLETION)
public void handleCompletion(OrderEvent event, 
                            @TransactionalStatus int status) {
    if (status == TransactionSynchronization.STATUS_COMMITTED) {
        // 事务提交逻辑
    } else if (status == TransactionSynchronization.STATUS_ROLLED_BACK) {
        // 事务回滚逻辑
    } else {
        // 未知状态处理
    }
}

事务状态常量

状态常量值说明
STATUS_COMMITTED0事务已提交
STATUS_ROLLED_BACK1事务已回滚
STATUS_UNKNOWN2状态未知

六、与TransactionSynchronization对比

传统方式实现事务同步

@Component
public class OrderTransactionSynchronization implements TransactionSynchronization {
    
    private ThreadLocal<Order> currentOrder = new ThreadLocal<>();
    
    @Override
    public void beforeCommit(boolean readOnly) {
        Order order = currentOrder.get();
        // 验证逻辑...
    }
    
    public void registerOrder(Order order) {
        currentOrder.set(order);
        TransactionSynchronizationManager.registerSynchronization(this);
    }
}

@TransactionEventListener vs 手动实现

特性@TransactionEventListener手动实现
代码简洁性⭐⭐⭐⭐⭐⭐⭐
事务状态传递⭐⭐⭐⭐⭐⭐⭐
条件表达式⭐⭐⭐⭐⭐
事件对象封装⭐⭐⭐⭐⭐⭐
多监听器支持⭐⭐⭐⭐⭐
与Spring事件集成⭐⭐⭐⭐⭐⭐

七、最佳实践与注意事项

1. 性能优化建议

事件对象轻量化

public class OrderEvent extends ApplicationEvent {
    // 仅传递ID而非完整对象
    private Long orderId;
    
    public OrderEvent(Long orderId) {
        super(orderId);
        this.orderId = orderId;
    }
    
    public Long getOrderId() {
        return orderId;
    }
}

异步处理

@Bean
public TaskExecutor eventTaskExecutor() {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setCorePoolSize(5);
    executor.setMaxPoolSize(10);
    executor.setQueueCapacity(100);
    return executor;
}

@TransactionEventListener
@Async("eventTaskExecutor")
public void asyncHandle(OrderEvent event) {
    // 异步处理
}

2. 常见问题解决方案

问题：监听器未执行

  • 检查当前是否有活跃事务
  • 确认 fallbackExecution 设置（无事务时）
  • 验证事件是否正确发布

问题：事务资源无法访问

@TransactionEventListener(phase = AFTER_COMMIT)
public void handleAfterCommit(OrderEvent event) {
    // 错误：事务已提交，连接已关闭
    // orderRepository.findOne(event.getId()); 
    
    // 正确：新事务中访问
    transactionTemplate.execute(status -> {
        return orderRepository.findById(event.getId());
    });
}

问题：监听器顺序控制

@TransactionEventListener
@Order(Ordered.HIGHEST_PRECEDENCE)
public void firstListener(OrderEvent event) {
    // 最先执行
}

@TransactionEventListener
@Order(Ordered.LOWEST_PRECEDENCE)
public void lastListener(OrderEvent event) {
    // 最后执行
}

八、应用场景总结

1. 事务审计

  • 在事务各阶段记录关键事件
  • 保存事务最终状态

2. 业务补偿

  • 事务失败时执行回滚补偿
  • 分布式事务协调

3. 消息通知

  • 事务成功后发送通知
  • 保证消息发送与事务同步

4. 资源清理

  • 事务完成后释放资源
  • 清理线程局部变量

5. 后置校验

  • 提交前进行最终校验
  • 关键业务规则验证

九、总结

@TransactionEventListener 是 Spring 事务生态系统的关键组件，它通过以下核心机制提供强大的事务事件处理能力：

  1. 事务阶段绑定：精确控制事件在事务生命周期中的触发时机
  2. 状态传递：将事务执行状态注入事件处理方法
  3. 无缝集成：与 Spring 事件体系深度集成
  4. 条件处理：支持基于 SpEL 表达式的细粒度控制
  5. 灵活部署：提供无事务回退执行机制

在实际应用中，开发者应当：

  • 优先使用 AFTER_COMMIT 处理关键业务
  • 谨慎使用 BEFORE_COMMIT 避免影响事务
  • 异步处理耗时操作提升性能
  • 通过事务模板保障资源访问安全
  • 合理控制监听器执行顺序

通过深入理解其源码实现（特别是 ApplicationListenerMethodTransactionalAdapter 和 TransactionalApplicationListenerSynchronization），开发者能够构建出既符合事务一致性要求，又能灵活响应业务需求的企业级应用系统。

Spring @Transactional注解原理深度分析
ma451152002的专栏
06-17 85
Transactional注解是Spring事务管理的核心注解，定义在spring-tx@Inherited// 事务管理器限定符// 事务标签// 事务传播行为// 事务隔离级别// 事务超时时间// 只读事务标识// 回滚异常类型Class<?// 不回滚异常类型Class<?/*** 根据事务定义获取事务状态*//*** 提交事务*//*** 回滚事务*/@Component。
事件监听-@TransactionalEventListener与@EventListener的介绍、区别和使用
杨杨杨~~的博客
09-14 3490
事件监听-@TransactionalEventListener与@EventListener的介绍、区别和使用
使用@TransactionalEventListener监听事务实战
weixin_42633835的博客
01-28 2107
项目背景 最近在项目遇到一个问题 A方法体内有 INSERT、UPDATE或者DELETE操作,最后会发送一段MQ给外部，外部接收到MQ后会再发送一段请求过来，系统收到请求后会执行B方法，B方法会依赖A方法修改后的结果，这就有一个问题，如果A方法事务没有提交；且B方法的请求过来了会查询到事务未提交前的状态，这就会有问题 使用 @TransactionalEventListener注解 在Spring4.2+，有一种叫做TransactionEventListener的方式，能够控制在事务的时候Event事
TransactionalEventListener
xiaoguangtouqiang的博客
11-27 1129
正常情况，B和A为同一个事务，B中读取到的为A中未提交的事务数据；B中抛出异常，会导致A中的事务回滚；会在A方法执行完成之后，再执行B方法；因为是commit之后，所以B中抛出异常，A中不会回滚；A和B是两个事务，之间不会有任何关联；B中方法会立刻执行，所以拿到的数据看当时的数据库数据；提交之前，所以抛出异常会影响A中事务的提交，但是读取的数据，是A中的数据是一样的；不区分哪个阶段，但是是同一个事务中的数据；而且抛出异常也不会影响A中事务的回滚；读取到的也是A中事务的数据，是一个事务；
@TransactionalEventListener 事务事件监听
lu_tian_dong的博客
03-22 5231
背景 最近项目有这么一个问题：页面有一个“分单排定”的功能，针对选择的订单记录可以调用后台接口对这条订单进行“分单”操作，即对相关业务表的insert、update（在同一个事务中），然后控制流程的往下流转（未加入到事务）。但有反馈有同一条订单被“分单”多次的现象，于是让前端检查了防止多次触发提交以及提交遮罩层的功能。可是用户仍然可能点击提交之后刷新页面重复提交（提交接口处理时间长） 解决方法 为了防止用户点击提交后刷新页面重复提交，一方面优化后台接口效率；另一方面在加了事务的业务方法入口增加以下逻辑：
@TransactionalEventListener 事务事件监听进行业务解耦
迷茫，是因为才华配不上梦想...
10-27 3441
@TransactionalEventListener 事务事件监听进行业务解耦
【@Async与事务协同】：掌握解决方法与最佳实践
本文从异步编程与事务管理的基本概念出发，深入分析了Spring框架中@Async注解的原理及其与事务管理间的潜在冲突。文章详细探讨了事务传播机制、TransactionTemplate的使用以及异步与事务协同的场景实践，旨在
@TransactionalEventListener的使用和实现原理
热门推荐
Evan's Blog ٩(๑❛ᴗ❛๑)۶
04-25 2万+
一、问题描述 平时我们在完成某些数据的入库后，发布了一个事件，此时使用的是@EventListener，然后在这个事件中，又去对刚才入库的数据进行查询，从而完成后续的操作。例如（数据入库=>对入库数据进行查询审核），这时候会发现，查询不到刚才入库的数据，这是因为事务还没提交完成，在同一个事务当中，查询不到才存入的数据，那么就引出了下面的解决方式。 为了解决上述问题，Spring为我们提供了两...
分析事件监听器注解：@EventListener、@TransactionalEventListener
weixin_37607613的博客
08-20 9982
@EventListener @TransactionalEventListener是用来标识在方法上，使得该方法可以监听事件，在事件发布时调用方法（作用与实现接口的事件监听器一样，参考）。@的注解上标识@注解，相当于继承了@注解的功能，并添加了新的特性。...
Spring中的@TransactionalEventListener
yaolan97的博客
12-08 620
spring事件监听
@TransactionalEventListener Spring 事务绑定事件的深入学习与使用
终生学习践行者
12-25 9022
基于最新Spring 5.x，详细介绍了Spring的@TransactionalEventListener事务绑定事件机制的应用！
每天一个spring注解：@TransactionalEventListener
weixin_40952181的博客
08-19 618
是 Spring Framework 提供的一个注解，具体是在spring-tx包下用于监听特定的事务事件并在这些事件发生时执行相应的逻辑。它主要用于实现与事务相关的业务逻辑处理，比如发送通知、记录日志等。重点它是使用了@EventListener注解，就是使用了spring的事件通知机制。比如你需要在事务完成后去发送MQ消息，这个是很重要的使用场景。
Spring事务监听机制---使用@TransactionalEventListener处理数据库事务提交成功后再执行操作（附：Spring4.2新特性讲解）【享学Spring】
架构师：通透，才能写出好代码！
06-14 1万+
前言 从标题就可以看出，本篇文章内容既和Spring的事件/监听机制有关，同时还和Spring事务以及Spring事务同步机制有关。 为了给这篇文章铺好路，建议可以先了解下： Spring事件监听机制： 【小家Spring】从Spring中的(ApplicationEvent)事件驱动机制出发，聊聊【观察者模式】【监听者模式】【发布订阅模式】【消息队列MQ】【EventSourcing】… Spr...
@EventListener底层原理（超详细）| @TransactionalEventListener底层原理 | 事务同步
最新发布
假人一个的博客
01-31 907
@EventListener底层原理（超详细）| @TransactionalEventListener底层原理 | 事务同步
关于@TransactionalEventListener的理解
铭记：
04-03 1943
在Spring Boot应用中，事务是一个非常重要的概念。当应用需要执行一系列的操作，并且这些操作必须在一个事务内执行时，我们就需要使用事务管理。Spring Boot提供了一种非常便捷的方式来处理事务，即使用@Transactional注解。但是，在某些情况下，我们需要在事务完成之后执行一些额外的操作。这时，我们可以使用@TransactionalEventListener注解来监听事务完成事件。
@TransactionalEventListener商品同步MQ 实战
aaaak_的博客
05-24 656
TransactionalEventListener 实战场景 创建一个 EventEntity 用于event-listener 之间传输对象 @Data public class EventEntity extends ApplicationEvent { private static final long serialVersionUID = -6206752641309458207L; private String id; private String tag;
@TransactionalEventListener与@EventListener那点事
爱琴孩的博客
08-08 1023
最近测试提了个bug，有个交易订单服务，会产生一些交易数据，当时为了便于后续追溯交易订单的来源和状态，在交易中心服务中做了事件溯源功能，利用spring的事件监听功能做了异步事件溯源，将业务代码和事件存储逻辑解耦。同事在编码注册监听器的时候使用了@TransactionalEventListener注解。测试在测试功能的时候发现某一类型事件没有保存到事件溯源的mongoDB中，由于事件溯源功能已经上线快两年了。从现网mongoDB中查询数据，发现此类型事件数据从2023年7月份就没有数据了。
注解@TransactionalEventListener
y_index的博客
08-05 9691
例如 用户注册之后需要计算用户的邀请关系，递归操作。如果注册的时候包含多步验证，生成基本初始化数据，这时候我们通过mq发送消息来处理这个邀请关系，会出现一个问题，就是用户还没注册数据还没入库，邀请关系就开始执行，但是查不到数据，导致出错。 @TransactionalEventListener 可以实现事务的监听，可以在提交之后再进行操作。 监听的对象 package com.jing...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值