外观
23 - Spring 事件与事务监听:发布、提交阶段与异步边界
适用版本:Spring Framework 6.x、Spring Boot 3.x。本文讨论单进程应用事件,不把它等同于消息队列。事务上下文的说明以绑定当前线程的命令式事务为前提;响应式事务需要另行核对目标版本的上下文传递方式。
前置阅读:05 - Bean 生命周期与扩展点顺序、11 - Spring 声明式事务执行链和18 - Spring 扩展点选型。
摘要
业务代码调用 publishEvent(),表示把事件交给 Spring 的事件机制处理,并不表示数据库已经提交,也不表示事件已经可靠送达。普通监听器默认同步执行;事务监听器可以等到指定事务阶段再执行;异步监听器则把处理工作交给执行器。这些选择分别影响执行时机、线程和失败传播。
本文先解释进程内事件的发布模型,再讨论事务阶段和异步边界,最后说明哪些需求需要持久化与跨进程消息机制。
1. 场景:订单已提交,事件为什么仍然丢了
假设创建订单后,需要通知其他模块。下面是业务方法示意,... 表示省略的业务参数,不能直接编译运行。repository 是数据访问对象,publisher 是事件发布入口,OrderCreated 是承载订单信息的事件类型;方法需要通过 Spring 事务代理调用,并配置与数据访问对应的事务管理器。
java
@Transactional
public void createOrder() {
repository.save(...);
publisher.publishEvent(new OrderCreated(...));
}这里有三个不同的时刻:保存订单、发布事件、提交事务。执行到 publishEvent() 时,方法还没有结束,事务也可能尚未提交。
如果普通监听器同步执行,它会在发布调用中处理事件,因此可能在提交前就发出通知。此后若事务回滚,通知与订单状态便不一致;监听器抛出的未处理异常也可能沿调用链返回业务方法,并按事务回滚规则影响提交。
如果使用提交后阶段 AFTER_COMMIT,可以避免在主事务成功前处理通知,却仍存在另一种失败:数据库已完成 COMMIT(提交),进程在监听器完成前崩溃。订单已经保存,尚未完成的通知却没有自动恢复的依据。
因此,进程内解耦与可靠投递是两个需求。Spring 应用事件不自动提供持久化、跨实例投递、至少一次投递或故障恢复。“至少一次”指在约定的故障与恢复条件下,保证消息至少被投递一次,允许重复投递;投递成功不等于业务处理成功。
2. 普通事件发布链
应用事件由发布者发出,由监听器接收。发布者只需要提供事件对象,不必直接调用每个接收模块;广播器负责找到匹配的监听器并分发事件。@EventListener 是声明监听方法的一种方式。
text
publisher.publishEvent(event)
→ ApplicationEventMulticaster
→ 查找匹配 Listener
→ 当前线程同步执行,或交给配置的 ExecutorApplicationEventMulticaster 是事件广播器,Listener 是监听器,Executor 是负责调度任务的执行器。上述路径是分发模型示意;实际执行方式还取决于广播器配置和监听器是否支持异步执行。
默认广播器在未配置异步执行器时同步调用普通监听器。同步意味着监听工作仍发生在发布调用中:
- 发布者等待监听器完成,慢监听器会直接增加请求或启动耗时;
- 监听器在同一线程执行,可以使用该线程上可见的事务等上下文;
- 未处理异常可能返回发布调用,是否触发回滚还取决于异常类型、回滚规则和异常处理配置。
事件机制降低了发布者对接收模块的直接依赖,但同步监听仍然存在耗时和异常上的耦合。为广播器配置执行器或使用 @Async 后,需要重新判断这些行为,不能继续套用同步模型。
3. 事务事件阶段
@TransactionalEventListener 用于让监听方法在指定事务阶段处理事件。它与普通监听器的区别主要在执行时机:发布事件时关联当前事务,业务处理等到对应阶段再触发。事件对象本身不必因为监听方式不同而换成另一类对象。
| 阶段 | 含义 | 主要风险 |
|---|---|---|
| BEFORE_COMMIT | 提交动作前 | 此时还未保证提交成功,监听器失败仍可能导致回滚 |
| AFTER_COMMIT | 主事务已提交 | 后续失败不能撤销主事务 |
| AFTER_ROLLBACK | 主事务已回滚 | 可用于记录或触发补偿,不保证外部投递成功 |
| AFTER_COMPLETION | 提交或回滚完成 | 两种结果都会触发,不能仅凭回调执行就判断提交成功 |
AFTER_COMMIT 是默认阶段。使用 AFTER_COMPLETION 时,如果处理逻辑依赖最终结果,必须通过合适的事务状态记录或回调机制区分提交与回滚,不能假定监听方法仅因使用该阶段就自动获得最终状态。
默认情况下,没有活动事务时事务监听器不会执行。fallbackExecution = true 允许它在无事务时也执行,但此时没有可等待的提交或回滚阶段。启用这一选项会改变事件契约:接收事件不再意味着它必然关联一次事务完成。
3.1 AFTER_COMMIT 中继续写数据库
AFTER_COMMIT 回调发生时,原事务已经提交,但连接等资源可能仍绑定在线程上,尚未清理。资源仍可访问,不等于原事务还会再次提交;回调中继续写入,不能假设这些写入自动得到一次可提交事务。
需要写数据库时,应显式建立新的事务边界,并确认调用路径确实使新事务生效。新的写入即使失败,也不能回滚已提交的订单,因此还要设计失败记录、重试或补偿方式。
若必须可靠保存待发送的业务事件,通常可以采用 Transactional Outbox(事务发件箱):在原事务中同时写入业务数据和待投递事件记录,再由后续流程读取并投递。这样,提交后的进程崩溃不会仅因内存中的事件消失而失去待处理记录;投递与恢复仍需要单独实现。
4. 异步监听改变了什么
下面是监听方法片段,需要放在 Spring 管理的 Bean(由容器创建和管理的对象)中,导入 Spring 的 Async、EventListener 注解,并定义 OrderCreated。还需要启用异步方法支持、配置名为 domainEventExecutor 的执行器,并确保异步代理生效。空方法体仅展示注解组合。
java
@Async("domainEventExecutor")
@EventListener
public void onOrderCreated(OrderCreated event) { }事务阶段回答“什么时候触发”,异步执行回答“由哪个线程处理”。这个例子使用普通 @EventListener,不会因为加上 @Async 就自动等待主事务提交;异步任务仍可能在提交前开始。
任务成功交给异步执行器后,发布线程通常不等待监听方法完成。切换线程还带来以下变化:
- 原命令式事务绑定在发布线程上,不会自动传播到工作线程;
ThreadLocal(线程局部变量)、MDC(日志诊断上下文)和安全上下文需要明确的传播策略,否则监听器可能缺少请求标识或身份信息;- 任务可能因容量不足被拒绝,也可能在进程关闭时丢失或在执行中失败;
void异步方法的执行异常不能像同步异常一样直接返回给发布者,需要专门的异常处理机制。
提交任务时的拒绝与任务开始后的执行异常是两个阶段,应分别处理。线程池必须配置容量、队列、拒绝和关闭策略;拒绝策略还可能改变是否由调用线程执行任务,不能仅凭 @Async 就推断所有情况下发布者都不会等待。
相关边界见并发 09 - ThreadPoolExecutor 参数与容量设计和并发 21 - 并发上下文传播与 ScopedValue。
5. 应用事件与消息队列的边界
MQ 是消息队列,用于在生产者与消费者之间传递消息;CDC 是变更数据捕获,用于读取数据库的变更并交给后续处理流程。Outbox 解决的是业务写入与待投递记录共同提交的问题,MQ 或 CDC 可以参与后续投递,几者不能简单互相替代。
| 需求 | 应用事件 | Outbox / MQ |
|---|---|---|
| 同进程模块解耦 | 适合 | 通常过重 |
| 跨实例消费 | 不保证 | 适合,但需配置投递与消费机制 |
| 进程崩溃后恢复 | 不保证 | 可通过持久化与恢复流程实现 |
| 重放与消费位点 | 无通用能力 | 取决于消息系统或 CDC 的能力与配置 |
| 事务提交与事件不丢 | 单靠 AFTER_COMMIT 不保证 | Transactional Outbox 可使业务数据与待投递记录共同提交 |
消费位点表示处理进度,重放则是从已保存的记录重新处理。持久化提供恢复依据,但最终是否可靠,还取决于投递重试、进度记录和消费端处理方式,不能只因引入 MQ 就认为所有失败窗口都已消除。
OrderCreated 可以表达“订单已创建”这一业务事实,但对象名称不能证明它已经可靠发布到外部系统。可靠事件投递的具体设计见分布式 29 - Outbox 与 CDC。
6. 监听器顺序与幂等
同步监听器可以排序,但顺序只约束当前广播器中的调用,不构成跨进程工作流,也不能用于推断异步任务的完成顺序。多个监听器若通过隐式状态相互依赖,例如后一个默认前一个已经更新数据,理解事件处理就必须追踪整条调用链,解耦的收益会随之降低。
幂等指同一个业务操作重复执行时,不额外产生业务副作用。监听器应考虑重复执行:业务重放、自定义重试、测试中重复发布事件,或未来迁移到消息系统,都可能让同一业务事件被处理多次。重建测试上下文本身不等于重放事件,是否重复仍取决于发布路径。
外部写入应使用幂等键,即用稳定的业务标识识别同一次操作,并在接收端防止重复生效。原则见分布式 13 - 幂等性与重复请求。
7. 最小验证矩阵
以下是验证方案及预期检查点。测试需要注册发布者和监听器,明确广播器、执行器和异常处理配置;事务用例还需要真实的事务管理器与数据访问环境。仅检查注解是否存在,不能证明对应执行路径生效。
| 用例 | 应验证内容 |
|---|---|
| 普通同步监听 | 线程与发布者相同,异常传播符合预期 |
| BEFORE_COMMIT | 监听器失败时主事务是否回滚 |
| AFTER_COMMIT | 主数据已提交,监听器失败不能撤销 |
| 无事务发布 | 默认事务监听器是否未执行 |
| fallbackExecution | 无事务时是否按显式契约执行 |
| 异步监听 | Executor、线程、上下文、拒绝和异常处理 |
| 进程关闭 | 已提交但未完成的异步事件是否可能丢失 |
测试事务阶段时,应让被测事务实际提交或回滚,再从独立事务查询数据库最终状态,避免测试框架自动回滚干扰结果。异步用例需要等待明确的完成信号,再断言执行结果;发布方法返回不能作为监听完成的证据。
8. 排障清单
- 接收方法使用普通
@EventListener还是@TransactionalEventListener? - 发布时是否存在真实事务,事务代理是否生效?
- 监听阶段是 BEFORE_COMMIT、AFTER_COMMIT 还是其他阶段?无事务时是否启用 fallbackExecution?
- 广播器和监听方法分别如何配置异步执行,使用哪个 Executor?
- 失败发生在提交任务还是执行任务时?异常返回了发布者、进入异步处理器还是只写入日志?
- 监听器是否可能重复执行,外部副作用是否幂等?
- 需求是否已经超出单进程事件能力,需要采用 Outbox/MQ 并设计恢复流程?
9. 总结
Spring 事件提供进程内发布订阅,事务监听器绑定处理阶段,异步监听改变执行线程。选择时应分别判断时机、线程和可靠性。
- 默认同步监听占用发布线程,耗时和未处理异常可能影响业务调用。
- AFTER_COMMIT 表示主事务已经成功,不能消除提交后的崩溃窗口,也不能撤销主事务。
- 异步处理需要容量与异常策略;可靠跨进程投递还需要持久化、幂等与恢复机制。
阅读导航
- Bean 与容器生命周期:05 - Bean 生命周期与扩展点顺序
- 事务提交阶段:11 - Spring 声明式事务执行链
- 扩展点选型:18 - Spring 扩展点选型
- 异步代理边界:10 - 同类调用为什么绕过 AOP
- 可靠事件投递:分布式 29 - Outbox 与 CDC
- 消息重复与幂等:分布式 22 - 消息重复与幂等消费