Repository navigation
Description
版本概览
8.2.3 是 8.x 版本线(JDK 8 / Spring Boot 2.7.18 / javax.*)的补丁版本。本版同步了 issue #222 的异步事件顺序与可见性修复,并按 8.x 代际做了适配(未直接 cherry-pick 17.x 代码)。此前同一业务操作里连续 EventPusher.push 的多个异步事件被并发投放到固定线程池,订阅方可能乱序甚至并发执行;本版把事件分发统一收敛到「事务提交后按 trace 串行、跨 trace 并行」,并提供批量推送 API 与配置开关。
标签异常提示(务必先确认):当前
v8.2.3标签指向的是 main/17.3.x 上的提交abf66f8a(pom 为 Spring Boot 3.3.5 / JDK 17 /revision=17.3.0-SNAPSHOT),并不在8.2.x分支上。因此 GitHub Release 页面自动生成的 changelog(compare/v17.3.1...v8.2.3,PR #215–#220)反映的是 17.x 提交,其中列出的 Groovy 脚本缓存跨实例同步等改动实际已在v8.2.2中包含,不属于本次 8.2.3 内容。本文以8.2.x分支相对v8.2.2的实际改动(HEAD88c386c3)为准。请发布方核对并修正标签指向,避免 8.x 用户拉到 17.x 产物。
| 端 | 版本跨度 | 主要变化 |
|---|---|---|
| 后端(8.x) | v8.2.2 → 8.2.3(以 8.2.x 分支实际内容为准) |
异步事件改为事务提交后按 trace 串行分发;新增批量推送 EventPusher.push(IEvent...) 与 codingapi.framework.event.async.ordered 配置;SpringTransactionEventHandler 标记废弃;完成 JDK 8 / javax.* 代际适配 |
| 前端 | 不适用 | 8.x 版本线不含前端模块 |
一、后端变更
- 异步事件顺序与可见性修复(异步事件分发缺少顺序保证:同一 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不再产生行为差异,旧配置可保留,可不配置。
- 8.x 代际适配说明
- 本次修复未从 17.x 直接 cherry-pick,而是按 JDK 8 语法重新适配(匿名内部类显式泛型、
new ArrayList<>()代替stream().toList()等),命名空间继续使用javax.*。 - 8.x 提交信息使用
Ref #222(8.x 合入8.2.x不会自动关闭 issue);17.x 对应版本为 17.3.3,两条版本线各自独立验证。
- 依赖与测试
- 新增
OrderedAsyncDispatcherTest(覆盖同 trace 串行、跨 trace 并行、队尾清理、开关回退)与EventOrderE2ETest(3 项端到端用例:事务内事件共享 trace 且顺序执行、批量同类事件不误判循环、事务回滚不分发事件)。 - 全量
./mvnw clean test -P travis在 Corretto 8(字节码 major version 52)下 BUILD SUCCESS,模块全过。
二、兼容性影响点
| 位置 | 变化 | 兼容性 | 说明 |
|---|---|---|---|
| 异步事件时序 | 同一 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 |
v8.2.3 标签指向 |
当前指向 main/17.3.x 提交 | 发布流程问题 | 以 8.2.x 分支产物为准,需发布方修正标签,详见文首提示 |
结论:新增 API 与配置项均为增量,旧代码无需修改即可升级;需要重点关注的是事件时序与循环检测的行为变化。串行维度是 trace(约等于单事务/单批次),同一聚合在两个并发事务中的事件之间仍无顺序保证,业务方若要求聚合级串行需自行按聚合键排队。
三、升级建议
- 升级前先确认拉取的 8.2.3 产物来自
8.2.x分支(Spring Boot 2.7.18 / JDK 8 /javax.*);当前v8.2.3标签指向有误,详见文首提示。 - 直接把
com.codingapi.springboot:*依赖升级到8.2.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 8x #223 Merge pull request Feature/issue 222 async event ordered 8x #223 from codingapi/feature/issue-222-async-event-ordered-8x
- 17.x 对应版本说明:17.3.3(https://github.com/codingapi/springboot-framework/issues/226)
- Release 页面(标签异常,仅供参考):https://github.com/codingapi/springboot-framework/releases/tag/v8.2.3
- 实际内容基线:
8.2.x@88c386c3,相对v8.2.2的变更为 PR Feature/issue 222 async event ordered 8x #223
Activity