Repository navigation
Open
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Description
版本概览
17.3.3 是 17.x 版本线(JDK 17 / Spring Boot 3.x / jakarta.*)的补丁版本。本版只包含一个核心修复:异步事件分发缺少顺序保证(#222)。此前同一业务操作里连续 EventPusher.push 的多个异步事件被并发投放到固定线程池,投放顺序不等于执行顺序,订阅方可能乱序甚至并发执行;本版把事件分发统一收敛到「事务提交后按 trace 串行、跨 trace 并行」,并提供批量推送 API 与配置开关。
| 端 | 版本跨度 | 主要变化 |
|---|---|---|
| 后端 | v17.3.2 → v17.3.3 | 异步事件改为事务提交后按 trace 串行分发;新增批量推送 EventPusher.push(IEvent...) 与 codingapi.framework.event.async.ordered 配置;SpringTransactionEventHandler 标记废弃 |
| 前端 | 不适用 | 本次为框架核心后端补丁,无前端改动 |
一、后端变更
- 异步事件顺序与可见性修复(异步事件分发缺少顺序保证:同一 trace 内事件被无序投放固定线程池,订阅方可能乱序或并发执行 #222)
- 事件监听统一收敛到
SpringDefaultEventHandler,使用@TransactionalEventListener(phase = AFTER_COMMIT, fallbackExecution = true):事务提交后分发,订阅方可读到已提交数据;事务回滚不分发;无事务上下文时即时分发。 - 新增
OrderedAsyncDispatcher:以ConcurrentHashMap<String, CompletableFuture<Void>>维护每个 traceId 的队尾任务链,同一 trace 内严格按推送顺序串行,不同 trace 仍共享同一个线程池并行,不牺牲吞吐;任务完成后若为队尾则移除条目,避免内存泄漏。 - 统一异常语义:单个 handler 异常记录日志,不静默消失,也不中断同一 trace 的后续任务;循环事件异常额外给出明确日志。
EventTraceContext/EventStackContext增强:删除只写不读的traceKeys;事务级 trace 通过TransactionSynchronizationManager绑定、afterCompletion解绑,避免线程复用串 trace。
- 新增批量推送 API
EventPusher.push(IEvent... events):整批事件共享同一 traceId,异步事件按参数顺序串行执行;批内同类事件不会被误判为循环调用。- 需要严格顺序时,除「事务内连续 push」外,推荐改用
EventPusher.push(a, b)批量推送;无事务的独立 push 之间仍不保证顺序。
- 配置项与废弃项
- 新增
codingapi.framework.event.async.ordered(默认true):同一 trace 内异步事件是否按推送顺序串行;关闭后退回完全并发行为,适合无顺序依赖、追求极致吞吐的场景。 SpringTransactionEventHandler标记@Deprecated,仅作为按类名注入的兼容别名保留,行为与SpringDefaultEventHandler完全一致;新代码请直接使用SpringDefaultEventHandler。codingapi.framework.event.transaction.enable不再产生行为差异,旧配置可保留,可不配置。
- 事件循环检测语义调整
- 循环检测现在只对 handler 内嵌套 push 生效:同一 trace 下出现相同事件类仍抛
EventLoopException并附带完整调用栈。 - 业务线程中连续 push 的多个事件(批量或事务内)属于同一批次,即使同类也不会被误判为循环。
- 若确实需要在 handler 内允许嵌套循环(如状态机重试),仍可用
EventPusher.push(event, true)跳过检测。
- 依赖与测试
- 新增
OrderedAsyncDispatcherTest(覆盖同 trace 串行、跨 trace 并行、队尾清理、开关回退)与EventOrderE2ETest(3 项端到端用例:事务内事件共享 trace 且顺序执行、批量同类事件不误判循环、事务回滚不分发事件)。 - 全量
./mvnw clean test -P travis在 JDK 17 下 BUILD SUCCESS(6 模块全过)。
二、兼容性影响点
| 位置 | 变化 | 兼容性 | 说明 |
|---|---|---|---|
| 异步事件时序 | 同一 trace 内由并发改为严格串行 | 行为变化 | 依赖「多个事件并发执行」的 handler 属于错误假设;单 trace 内总耗时为顺序累加,跨 trace 并行度不变 |
| 事件分发阶段 | 统一为 AFTER_COMMIT 分发 |
行为变化 | 订阅方总是读到已提交数据;事务回滚不分发事件 |
EventPusher.push(IEvent...) |
新增重载 | 新增 API | 无破坏性;原有单事件 push 行为不变 |
codingapi.framework.event.async.ordered |
新增配置,默认 true |
新增 | 无顺序依赖且追求吞吐时可设为 false 回退并发 |
SpringTransactionEventHandler |
标记 @Deprecated |
兼容别名 | 按类名注入仍可用;新代码建议迁移到 SpringDefaultEventHandler |
codingapi.framework.event.transaction.enable |
不再产生行为差异 | 行为收敛 | 旧配置保留即可,无需修改 |
| 事件循环检测 | 仅对 handler 内嵌套 push 生效 | 行为变化 | 事务内或批量推送的同类事件不再抛 EventLoopException |
结论:新增 API 与配置项均为增量,旧代码无需修改即可升级;需要重点关注的是事件时序与循环检测的行为变化。串行维度是 trace(约等于单事务/单批次),同一聚合在两个并发事务中的事件之间仍无顺序保证,业务方若要求聚合级串行需自行按聚合键排队。
三、升级建议
- 直接把
com.codingapi.springboot:*依赖升级到17.3.3,无需改代码;旧的codingapi.framework.event.transaction.enable配置可保留。 - 若订阅方依赖「同一操作的多个异步事件并发执行」,请确认改为串行后单批耗时是否可接受;确需吞吐且无顺序依赖时,将
codingapi.framework.event.async.ordered=false。 - 需要保证多个事件顺序时,请将事件置于同一事务内连续 push,或改用
EventPusher.push(a, b)批量推送;无事务的独立 push 之间不保证顺序。 - 事件订阅方不要再假设「能读到未提交数据」,本版统一为事务提交后分发;事务回滚场景下事件不会分发。
- 按类名注入
SpringTransactionEventHandler的既有代码仍可运行,但建议迁移到SpringDefaultEventHandler,避免后续版本移除兼容别名时受影响。 - 同一聚合若存在并发事务写入,本版不提供聚合级串行,请在业务侧按聚合键自行排队。
四、关联 PR / ISSUE
- 异步事件分发缺少顺序保证:同一 trace 内事件被无序投放固定线程池,订阅方可能乱序或并发执行 #222 异步事件分发缺少顺序保证:同一 trace 内事件被无序投放固定线程池,订阅方可能乱序或并发执行
- Feature/issue 222 async event ordered 17x #224 Feature/issue 222 async event ordered 17x
- 17.3.x #225 17.3.x
- Release:https://github.com/codingapi/springboot-framework/releases/tag/v17.3.3
- Full Changelog:v17.3.2...v17.3.3
- 8.x 对应版本说明:8.2.3(https://github.com/codingapi/springboot-framework/issues/227)
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Activity