Skip to content

release: 8.2.3 版本说明(异步事件顺序保障 + 8.x 代际适配 + 标签异常提示) #227

Open

Description

@xlorne

版本概览

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 的实际改动(HEAD 88c386c3)为准。请发布方核对并修正标签指向,避免 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 版本线不含前端模块

一、后端变更

  1. 异步事件顺序与可见性修复(异步事件分发缺少顺序保证:同一 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。
  1. 新增批量推送 API
  • EventPusher.push(IEvent... events):整批事件共享同一 traceId,异步事件按参数顺序串行执行;批内同类事件不会被误判为循环调用。
  • 需要严格顺序时,除「事务内连续 push」外,推荐改用 EventPusher.push(a, b) 批量推送;无事务的独立 push 之间仍不保证顺序。
  1. 配置项与废弃项
  • 新增 codingapi.framework.event.async.ordered(默认 true):同一 trace 内异步事件是否按推送顺序串行;关闭后退回完全并发行为。
  • SpringTransactionEventHandler 标记 @Deprecated,仅作为按类名注入的兼容别名保留,行为与 SpringDefaultEventHandler 完全一致;新代码请直接使用 SpringDefaultEventHandler。
  • codingapi.framework.event.transaction.enable 不再产生行为差异,旧配置可保留,可不配置。
  1. 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,两条版本线各自独立验证。
  1. 依赖与测试
  • 新增 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(约等于单事务/单批次),同一聚合在两个并发事务中的事件之间仍无顺序保证,业务方若要求聚合级串行需自行按聚合键排队。


三、升级建议

  1. 升级前先确认拉取的 8.2.3 产物来自 8.2.x 分支(Spring Boot 2.7.18 / JDK 8 / javax.*);当前 v8.2.3 标签指向有误,详见文首提示。
  2. 直接把 com.codingapi.springboot:* 依赖升级到 8.2.3,无需改代码;旧的 codingapi.framework.event.transaction.enable 配置可保留。
  3. 若订阅方依赖「同一操作的多个异步事件并发执行」,请确认改为串行后单批耗时是否可接受;确需吞吐且无顺序依赖时,将 codingapi.framework.event.async.ordered=false。
  4. 需要保证多个事件顺序时,请将事件置于同一事务内连续 push,或改用 EventPusher.push(a, b) 批量推送;无事务的独立 push 之间不保证顺序。
  5. 事件订阅方不要再假设「能读到未提交数据」,本版统一为事务提交后分发;事务回滚场景下事件不会分发。
  6. 按类名注入 SpringTransactionEventHandler 的既有代码仍可运行,但建议迁移到 SpringDefaultEventHandler,避免后续版本移除兼容别名时受影响。
  7. 同一聚合若存在并发事务写入,本版不提供聚合级串行,请在业务侧按聚合键自行排队。

四、关联 PR / ISSUE

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions