diff --git a/docs/agents/capabilities/springboot-starter/event-system.md b/docs/agents/capabilities/springboot-starter/event-system.md index b07b3e41..a0477c33 100644 --- a/docs/agents/capabilities/springboot-starter/event-system.md +++ b/docs/agents/capabilities/springboot-starter/event-system.md @@ -70,30 +70,54 @@ EventPusher.push(new MyEvent(data), true); ### 配置项 ```properties -# 启用事务事件模式(事件在事务提交后触发) -codingapi.framework.event.transaction.enable=true +# 同一 trace 内的异步事件是否按推送顺序串行执行(默认值 true) +# 关闭后退回完全并发行为,适合无顺序依赖、追求极致吞吐的场景 +codingapi.framework.event.async.ordered=true # 异步事件线程池大小(默认值 20) codingapi.framework.handler-thread-pool-size=20 + +# 兼容旧配置:现已不再产生行为差异(事件默认即为事务提交后分发),可不配置 +codingapi.framework.event.transaction.enable=true ``` ### 事件分发模式 -框架通过 `SpringHandlerConfiguration` 自动装配事件分发器: +框架通过 `SpringHandlerConfiguration` 自动装配 `SpringDefaultEventHandler`。事件监听统一使用 `@TransactionalEventListener(phase = AFTER_COMMIT, fallbackExecution = true)`: + +- **事务提交后分发**:事件在事务提交后才触发,订阅方可读到已提交数据;事务回滚则事件不分发。 +- **无事务上下文**:`fallbackExecution = true` 保证事件即时分发,行为与事务外推送一致。 +- `SpringTransactionEventHandler` 已标记为 `@Deprecated`,仅作为按类名注入的兼容别名保留,与 `SpringDefaultEventHandler` 行为完全一致;`codingapi.framework.event.transaction.enable` 不再产生行为差异。 -- **默认模式**(`SpringDefaultEventHandler`):使用 Spring `@EventListener` 即时触发,同步事件在当前线程执行,异步事件提交到固定大小线程池。 -- **事务模式**(`SpringTransactionEventHandler`):当配置 `codingapi.framework.event.transaction.enable=true` 时激活,使用 `@TransactionalEventListener(phase = AFTER_COMMIT)` 确保事件在事务提交后才触发,避免读取到未提交的数据。设置 `fallbackExecution = true` 保证无事务上下文时也能正常执行。 +### 顺序保证与 trace 归属 -两种模式互斥,事务模式优先(`@ConditionalOnMissingBean` 兜底默认模式)。 +异步事件的串行维度是 `traceId`,同一 trace 内的异步事件严格按推送顺序串行执行,不同 trace 之间保持并行(线程池大小决定并发 trace 数)。traceId 的归属规则: + +1. **handler 内嵌套 push**:复用当前事件链的 traceId; +2. **批量 push**:调用 `EventPusher.push(e1, e2, ...)`,整批共享一个 traceId,异步事件按参数顺序串行执行; +3. **事务内连续 push**:共享同一事务级 traceId(`TransactionSynchronizationManager` 绑定,`afterCompletion` 解绑,避免线程复用串 trace); +4. **无事务的独立 push**:每次新建独立 traceId,**不保证顺序**。 + +因此: + +> 需要严格顺序时,请将事件置于事务内连续 push,或使用 `EventPusher.push(a, b)` 批量推送;无事务的独立 push 之间不保证顺序。串行维度是 trace(约等于单事务/单批次),**同一聚合在两个并发事务中的事件之间仍无顺序保证**,业务方若要求聚合级串行需自行按聚合键排队。 ### 事件循环检测 框架通过 `EventTraceContext` 和 `EventStackContext` 实现同一条事件链路内的循环检测: 1. 每次推送事件时生成/复用 traceId,将事件类压入该 traceId 对应的事件栈。 -2. 若同一 traceId 下出现相同事件类,立即抛出 `EventLoopException`,并附带完整的事件调用栈信息。 -3. 事件处理完成后自动清理 traceId 和事件栈。 -4. 若确实需要允许循环(如状态机重试),可调用 `EventPusher.push(event, true)` 跳过检测。 +2. **循环检测只对 handler 内嵌套 push 生效**:若同一 traceId 下出现相同事件类,立即抛出 `EventLoopException`,并附带完整的事件调用栈信息。 +3. 业务线程中连续 push 的多个事件(批量或事务内)属于同一批次,即使同类也不会被误判为循环。 +4. 事件处理完成后自动清理 traceId 和事件栈;若确实需要允许 handler 内嵌套循环(如状态机重试),可调用 `EventPusher.push(event, true)` 跳过检测。 + +### Handler 异常处理策略 + +当某个 Handler 抛出异常时: +1. 若异常为 `EventLoopException`,直接向上抛出,终止后续所有 Handler。 +2. 否则调用该 Handler 的 `error(exception)` 回调。 +3. 若 `error()` 也抛出异常,标记为"有异常"并继续执行下一个 Handler。 +4. 所有 Handler 执行完毕后,若存在异常,统一包装为 `EventException` 抛出。 ### Handler 异常处理策略 diff --git a/docs/capabilities/springboot-starter/event-system.md b/docs/capabilities/springboot-starter/event-system.md index e50a945f..7bb6c736 100644 --- a/docs/capabilities/springboot-starter/event-system.md +++ b/docs/capabilities/springboot-starter/event-system.md @@ -81,30 +81,46 @@ EventPusher.push(new MyEvent(data), true); ### 配置项 ```properties -# 启用事务事件模式(事件在事务提交后触发) -codingapi.framework.event.transaction.enable=true +# 同一 trace 内的异步事件是否按推送顺序串行执行(默认值 true) +# 关闭后退回完全并发行为,适合无顺序依赖、追求极致吞吐的场景 +codingapi.framework.event.async.ordered=true # 异步事件线程池大小(默认值 20) codingapi.framework.handler-thread-pool-size=20 + +# 兼容旧配置:现已不再产生行为差异(事件默认即为事务提交后分发),可不配置 +codingapi.framework.event.transaction.enable=true ``` ### 事件分发模式 -框架通过 `SpringHandlerConfiguration` 自动装配事件分发器: +框架通过 `SpringHandlerConfiguration` 自动装配 `SpringDefaultEventHandler`。事件监听统一使用 `@TransactionalEventListener(phase = AFTER_COMMIT, fallbackExecution = true)`: + +- **事务提交后分发**:事件在事务提交后才触发,订阅方可读到已提交数据;事务回滚则事件不分发。 +- **无事务上下文**:`fallbackExecution = true` 保证事件即时分发,行为与事务外推送一致。 +- `SpringTransactionEventHandler` 已标记为 `@Deprecated`,仅作为按类名注入的兼容别名保留,与 `SpringDefaultEventHandler` 行为完全一致;`codingapi.framework.event.transaction.enable` 不再产生行为差异。 + +### 顺序保证与 trace 归属 + +异步事件的串行维度是 `traceId`,同一 trace 内的异步事件严格按推送顺序串行执行,不同 trace 之间保持并行(线程池大小决定并发 trace 数)。traceId 的归属规则: + +1. **handler 内嵌套 push**:复用当前事件链的 traceId; +2. **批量 push**:调用 `EventPusher.push(e1, e2, ...)`,整批共享一个 traceId,异步事件按参数顺序串行执行; +3. **事务内连续 push**:共享同一事务级 traceId(`TransactionSynchronizationManager` 绑定,`afterCompletion` 解绑,避免线程复用串 trace); +4. **无事务的独立 push**:每次新建独立 traceId,**不保证顺序**。 -- **默认模式**(`SpringDefaultEventHandler`):使用 Spring `@EventListener` 即时触发,同步事件在当前线程执行,异步事件提交到固定大小线程池。 -- **事务模式**(`SpringTransactionEventHandler`):当配置 `codingapi.framework.event.transaction.enable=true` 时激活,使用 `@TransactionalEventListener(phase = AFTER_COMMIT)` 确保事件在事务提交后才触发,避免读取到未提交的数据。设置 `fallbackExecution = true` 保证无事务上下文时也能正常执行。 +因此: -两种模式互斥,事务模式优先(`@ConditionalOnMissingBean` 兜底默认模式)。 +> 需要严格顺序时,请将事件置于事务内连续 push,或使用 `EventPusher.push(a, b)` 批量推送;无事务的独立 push 之间不保证顺序。串行维度是 trace(约等于单事务/单批次),**同一聚合在两个并发事务中的事件之间仍无顺序保证**,业务方若要求聚合级串行需自行按聚合键排队。 ### 事件循环检测 框架通过 `EventTraceContext` 和 `EventStackContext` 实现同一条事件链路内的循环检测: 1. 每次推送事件时生成/复用 traceId,将事件类压入该 traceId 对应的事件栈。 -2. 若同一 traceId 下出现相同事件类,立即抛出 `EventLoopException`,并附带完整的事件调用栈信息。 -3. 事件处理完成后自动清理 traceId 和事件栈。 -4. 若确实需要允许循环(如状态机重试),可调用 `EventPusher.push(event, true)` 跳过检测。 +2. **循环检测只对 handler 内嵌套 push 生效**:若同一 traceId 下出现相同事件类,立即抛出 `EventLoopException`,并附带完整的事件调用栈信息。 +3. 业务线程中连续 push 的多个事件(批量或事务内)属于同一批次,即使同类也不会被误判为循环。 +4. 事件处理完成后自动清理 traceId 和事件栈;若确实需要允许 handler 内嵌套循环(如状态机重试),可调用 `EventPusher.push(event, true)` 跳过检测。 ### Handler 异常处理策略 diff --git a/docs/wiki/springboot-starter.md b/docs/wiki/springboot-starter.md index 7bed3759..72f5ca86 100644 --- a/docs/wiki/springboot-starter.md +++ b/docs/wiki/springboot-starter.md @@ -537,4 +537,5 @@ public class FrameWorkApplication { | 配置项 | 说明 | 默认值 | |--------|------|--------| | `codingapi.framework.handler-thread-pool-size` | 事件异步线程池大小,对应`FrameworkProperties.handlerThreadPoolSize`(绑定前缀`codingapi.framework`) | 20 | -| `codingapi.framework.event.transaction.enable` | 开启事务事件处理器。配置为`true`时,`SpringHandlerConfiguration`通过`@ConditionalOnProperty`注册`SpringTransactionEventHandler`,否则使用默认的`SpringDefaultEventHandler` | 不开启 | +| `codingapi.framework.event.async.ordered` | 同一 trace 内的异步事件是否按推送顺序串行执行;关闭后退回去完全并发行为 | true | +| `codingapi.framework.event.transaction.enable` | 兼容旧配置,现已不再产生行为差异(事件默认即为事务提交后分发)。`SpringTransactionEventHandler` 已废弃,仅为按类名注入的兼容别名 | 不开启 | diff --git a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/DomainEventContext.java b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/DomainEventContext.java index 7d10e38c..8731cf37 100644 --- a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/DomainEventContext.java +++ b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/DomainEventContext.java @@ -2,14 +2,14 @@ import org.springframework.context.ApplicationContext; +import java.util.List; + class DomainEventContext { private static DomainEventContext instance; private ApplicationContext context; - private DomainEventContext() { - } public static DomainEventContext getInstance() { @@ -23,37 +23,62 @@ public static DomainEventContext getInstance() { return instance; } - private void push(IEvent event, boolean sync,boolean hasLoopEvent) { - if (context != null) { - String traceId = EventTraceContext.getInstance().getOrCreateTrace(); - if(hasLoopEvent){ - EventTraceContext.getInstance().clearTrace(); - traceId = EventTraceContext.getInstance().getOrCreateTrace(); - } - EventTraceContext.getInstance().addEvent(traceId,event); - context.publishEvent(new DomainEvent(event, sync,traceId)); + private boolean isAsync(IEvent event) { + return event instanceof IAsyncEvent; + } + + private void publish(IEvent event, String traceId) { + context.publishEvent(new DomainEvent(event, !isAsync(event), traceId)); + } + + private void doPush(IEvent event, boolean hasLoopEvent) { + if (context == null) { + return; } + EventTraceContext traceContext = EventTraceContext.getInstance(); + String traceId = hasLoopEvent + ? traceContext.newTrace() + : traceContext.getOrCreateTrace(); + traceContext.addEvent(traceId, event); + publish(event, traceId); } /** - * @param event - * @see EventPusher - * 默认 同步事件 + * 批量推送:整批事件共享同一 traceId,从而按顺序串行分发。 + * 批量内的同类事件不会被误判为循环调用(防环只针对 handler 内嵌套 push)。 */ - public void push(IEvent event,boolean hasLoopEvent) { - if (event instanceof IAsyncEvent) { - this.push(event, false,hasLoopEvent); - } else if (event instanceof ISyncEvent) { - this.push(event, true,hasLoopEvent); - } else { - this.push(event, true,hasLoopEvent); + void pushBatch(List events) { + if (context == null || events == null || events.isEmpty()) { + return; + } + EventTraceContext traceContext = EventTraceContext.getInstance(); + String previous = traceContext.getBatchTrace(); + String traceId = traceContext.newTrace(); + traceContext.setBatchTrace(traceId); + try { + for (IEvent event : events) { + traceContext.addEvent(traceId, event); + publish(event, traceId); + } + } finally { + if (previous == null) { + traceContext.clearBatchTrace(); + } else { + traceContext.setBatchTrace(previous); + } } } + /** + * 默认 同步事件 + * + * @see EventPusher + */ + public void push(IEvent event, boolean hasLoopEvent) { + doPush(event, hasLoopEvent); + } protected void initContext(ApplicationContext context) { this.context = context; } - - } diff --git a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventPusher.java b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventPusher.java index 333569ea..f43cb587 100644 --- a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventPusher.java +++ b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventPusher.java @@ -1,5 +1,8 @@ package com.codingapi.springboot.framework.event; +import java.util.Arrays; +import java.util.List; + /** * Even推送助手 */ @@ -24,4 +27,17 @@ public static void push(IEvent event) { public static void push(IEvent event, boolean hasLoopEvent) { DomainEventContext.getInstance().push(event, hasLoopEvent); } + + /** + * 批量推送:整批事件共享同一 trace,异步事件将严格按参数顺序串行执行。 + * 批内同类事件不会被误判为循环调用。 + * + * @param events 事件(按期望的执行顺序排列) + */ + public static void push(IEvent... events) { + if (events == null || events.length == 0) { + return; + } + DomainEventContext.getInstance().pushBatch(Arrays.asList(events)); + } } diff --git a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventStackContext.java b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventStackContext.java index bcc01407..3d7d1a1e 100644 --- a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventStackContext.java +++ b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventStackContext.java @@ -3,44 +3,35 @@ import lombok.Getter; import java.util.ArrayList; -import java.util.HashMap; +import java.util.Collections; import java.util.List; import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; /** - * 事件栈上下文 + * 事件栈上下文。 */ public class EventStackContext { - private final Map>> eventClassStack = new HashMap<>(); - private final Map> eventStack = new HashMap<>(); + private final Map>> eventClassStack = new ConcurrentHashMap<>(); + private final Map> eventStack = new ConcurrentHashMap<>(); @Getter private final static EventStackContext instance = new EventStackContext(); private EventStackContext() { - } private void addEventClass(String traceId, IEvent event) { - List> events = eventClassStack.get(traceId); - if (events == null) { - events = new ArrayList<>(); - } - events.add(event.getClass()); - eventClassStack.put(traceId, events); + eventClassStack.computeIfAbsent(traceId, key -> Collections.synchronizedList(new ArrayList<>())) + .add(event.getClass()); } private void addEventStack(String traceId, IEvent event) { - List events = eventStack.get(traceId); - if (events == null) { - events = new ArrayList<>(); - } - events.add(event); - eventStack.put(traceId, events); + eventStack.computeIfAbsent(traceId, key -> Collections.synchronizedList(new ArrayList<>())) + .add(event); } - void addEvent(String traceId, IEvent event) { addEventClass(traceId, event); addEventStack(traceId, event); @@ -49,32 +40,47 @@ void addEvent(String traceId, IEvent event) { boolean checkEventLoop(String traceId, IEvent event) { List> events = eventClassStack.get(traceId); if (events != null) { - return events.contains(event.getClass()); + synchronized (events) { + return events.contains(event.getClass()); + } } return false; } + /** + * 返回事件列表的快照,不暴露内部可变状态。 + */ public List getEvents(String eventKey) { - if(eventKey!=null) { + if (eventKey != null) { String traceId = eventKey.split("#")[0]; - return eventStack.get(traceId); + List events = eventStack.get(traceId); + if (events != null) { + synchronized (events) { + return new ArrayList<>(events); + } + } } return null; } + /** + * 返回事件类型列表的快照,不暴露内部可变状态。 + */ public List> getEventClasses(String eventKey) { - if(eventKey!=null) { + if (eventKey != null) { String traceId = eventKey.split("#")[0]; - return eventClassStack.get(traceId); + List> events = eventClassStack.get(traceId); + if (events != null) { + synchronized (events) { + return new ArrayList<>(events); + } + } } return null; } - void remove(String traceId) { eventStack.remove(traceId); eventClassStack.remove(traceId); } - - } diff --git a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventTraceContext.java b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventTraceContext.java index 4ed13171..c249ed85 100644 --- a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventTraceContext.java +++ b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventTraceContext.java @@ -1,41 +1,124 @@ package com.codingapi.springboot.framework.event; + import com.codingapi.springboot.framework.exception.EventLoopException; import com.codingapi.springboot.framework.utils.RandomGenerator; import lombok.Getter; +import org.springframework.transaction.support.TransactionSynchronization; +import org.springframework.transaction.support.TransactionSynchronizationManager; -import java.util.*; +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import java.util.UUID; +import java.util.concurrent.ConcurrentHashMap; /** - * 事件跟踪上下文 + * 事件跟踪上下文。 + * + *

traceId 是异步事件串行分发的维度。为让「同一业务操作里连续 push 的多个事件」 + * 真正共享同一 traceId,这里按以下优先级解析:

+ *
    + *
  1. handler 内嵌套 push:复用当前事件链的 traceId;
  2. + *
  3. 显式批量 push:复用批量上下文的 traceId;
  4. + *
  5. 活跃事务内:绑定并复用事务级 traceId,事务完成后解绑(避免线程复用串 trace);
  6. + *
  7. 其余:每次 push 新建独立 traceId(保持单次推送既有语义)。
  8. + *
*/ public class EventTraceContext { @Getter private final static EventTraceContext instance = new EventTraceContext(); - // trace key - private final Set traceKeys = new HashSet<>(); + /** + * 事务级 traceId 的绑定 key。 + */ + private static final Object TRANSACTION_TRACE_KEY = new Object(); - // thread local + // 当前线程正在执行的事件 key(traceId#random) private final ThreadLocal threadLocal = new ThreadLocal<>(); - // event listenerKey state - private final Map eventKeyState = new HashMap<>(); + // event listenerKey state,异步事件由线程池线程并发读写,需使用并发容器 + private final Map eventKeyState = new ConcurrentHashMap<>(); + // 显式批量 push 时共享的 traceId + private final ThreadLocal batchTraceLocal = new ThreadLocal<>(); private EventTraceContext() { } + /** + * 创建一个全新的 traceId。 + */ + String newTrace() { + return UUID.randomUUID().toString().replaceAll("-", ""); + } + + /** + * 解析本次 push 使用的 traceId。 + */ String getOrCreateTrace() { String eventKey = threadLocal.get(); if (eventKey != null) { return eventKey.split("#")[0]; } - String traceId = UUID.randomUUID().toString().replaceAll("-", ""); - traceKeys.add(traceId); + String batchTrace = batchTraceLocal.get(); + if (batchTrace != null) { + return batchTrace; + } + // registerSynchronization 要求 synchronization 处于激活状态; + // isActualTransactionActive() 为 true 但 synchronization 未激活时(如 + // SYNCHRONIZATION_NEVER 的事务管理器)必须回退,否则抛 IllegalStateException 打断业务。 + if (TransactionSynchronizationManager.isActualTransactionActive() + && TransactionSynchronizationManager.isSynchronizationActive()) { + return getOrCreateTransactionTrace(); + } + return newTrace(); + } + + /** + * 在同一事务内绑定并共享 traceId;事务完成后解绑,避免连接池线程复用串 trace。 + */ + private String getOrCreateTransactionTrace() { + Object existing = TransactionSynchronizationManager.getResource(TRANSACTION_TRACE_KEY); + if (existing instanceof String) { + return (String) existing; + } + String traceId = newTrace(); + TransactionSynchronizationManager.bindResource(TRANSACTION_TRACE_KEY, traceId); + try { + TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() { + @Override + public void afterCompletion(int status) { + TransactionSynchronizationManager.unbindResourceIfPossible(TRANSACTION_TRACE_KEY); + } + }); + } catch (IllegalStateException e) { + // 防御:synchronization 在并发边界失效时解绑资源并回退为独立 trace,绝不影响业务操作 + TransactionSynchronizationManager.unbindResourceIfPossible(TRANSACTION_TRACE_KEY); + return newTrace(); + } return traceId; } + /** + * 当前线程是否正处于 handler 执行中(即本次 push 为嵌套 push)。 + */ + boolean isNestedPush() { + return threadLocal.get() != null; + } + + String getBatchTrace() { + return batchTraceLocal.get(); + } + + void setBatchTrace(String traceId) { + batchTraceLocal.set(traceId); + } + + void clearBatchTrace() { + batchTraceLocal.remove(); + } + /** * get event key * traceId = eventKey.split("#")[0] @@ -46,6 +129,7 @@ public String getEventKey() { /** * create event key + * * @param traceId traceId */ void createEventKey(String traceId) { @@ -61,10 +145,8 @@ void checkEventState() { String eventKey = threadLocal.get(); if (eventKey != null) { Boolean state = eventKeyState.get(eventKey); - if (state!=null && !state) { - // event execute finish + if (state != null && !state) { String traceId = eventKey.split("#")[0]; - traceKeys.remove(traceId); EventStackContext.getInstance().remove(traceId); } eventKeyState.remove(eventKey); @@ -73,19 +155,18 @@ void checkEventState() { } /** - * add event - * @param traceId traceId - * @param event event + * 注册事件到事件栈。 + * + *

循环检测只对 handler 内嵌套 push 生效:业务线程中连续 push 的多个 + * (可能同类的)事件属于同一批次,不应被误判为循环调用。

*/ void addEvent(String traceId, IEvent event) { - boolean hasEventLoop = EventStackContext.getInstance().checkEventLoop(traceId, event); - if (hasEventLoop) { + if (isNestedPush() && EventStackContext.getInstance().checkEventLoop(traceId, event)) { List> stack = EventStackContext.getInstance().getEventClasses(traceId); - traceKeys.remove(traceId); EventStackContext.getInstance().remove(traceId); eventKeyState.remove(traceId); threadLocal.remove(); - throw new EventLoopException(stack, event); + throw new EventLoopException(stack == null ? new ArrayList<>() : new ArrayList<>(stack), event); } EventStackContext.getInstance().addEvent(traceId, event); } @@ -97,7 +178,6 @@ public void clearTrace() { String eventKey = threadLocal.get(); if (eventKey != null) { String traceId = eventKey.split("#")[0]; - traceKeys.remove(traceId); EventStackContext.getInstance().remove(traceId); eventKeyState.remove(eventKey); threadLocal.remove(); diff --git a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/OrderedAsyncDispatcher.java b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/OrderedAsyncDispatcher.java new file mode 100644 index 00000000..bda4c2c2 --- /dev/null +++ b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/OrderedAsyncDispatcher.java @@ -0,0 +1,78 @@ +package com.codingapi.springboot.framework.event; + +import com.codingapi.springboot.framework.exception.EventLoopException; +import lombok.extern.slf4j.Slf4j; + +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.ConcurrentMap; +import java.util.concurrent.ExecutorService; + +/** + * 按 traceId 串行、跨 traceId 并行的异步任务分发器。 + * + *

同一 traceId 的任务按提交顺序串行执行(前一个任务完成后才开始下一个), + * 不同 traceId 的任务仍交由同一个线程池并行处理,不牺牲吞吐。

+ */ +@Slf4j +class OrderedAsyncDispatcher { + + /** + * 每个 traceId 当前队尾任务。任务完成后若仍是队尾则移除,避免内存泄漏。 + */ + private final ConcurrentMap> tails = new ConcurrentHashMap<>(); + + private final ExecutorService executorService; + + private final boolean ordered; + + OrderedAsyncDispatcher(ExecutorService executorService, boolean ordered) { + this.executorService = executorService; + this.ordered = ordered; + } + + /** + * 提交一个异步任务。 + * + * @param key 串行维度(事件场景为 traceId) + * @param task 任务 + */ + void execute(String key, Runnable task) { + Runnable wrapped = wrap(task); + if (!ordered) { + executorService.execute(wrapped); + return; + } + + CompletableFuture tail = tails.compute(key, (traceId, previous) -> { + CompletableFuture base = previous == null + ? CompletableFuture.completedFuture(null) + : previous.handle((ignored, throwable) -> null); + return base.thenRunAsync(wrapped, executorService); + }); + tail.whenComplete((ignored, throwable) -> tails.remove(key, tail)); + } + + /** + * 统一两条路径的异常语义:捕获任务异常并记录,保证异常不会静默消失, + * 也不会中断同一 trace 的后续任务。循环事件异常额外给出明确日志。 + */ + private Runnable wrap(Runnable task) { + return () -> { + try { + task.run(); + } catch (EventLoopException e) { + log.error("event loop detected while executing async event task", e); + } catch (Exception e) { + log.error("async event task execute error", e); + } + }; + } + + /** + * 当前仍在排队/执行的 trace 数量,用于测试与内存泄漏校验。 + */ + int pendingTraceCount() { + return tails.size(); + } +} diff --git a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/SpringDefaultEventHandler.java b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/SpringDefaultEventHandler.java index 9293ec16..8b444098 100644 --- a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/SpringDefaultEventHandler.java +++ b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/SpringDefaultEventHandler.java @@ -3,35 +3,39 @@ import com.codingapi.springboot.framework.properties.PropertiesContext; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.InitializingBean; -import org.springframework.context.event.EventListener; +import org.springframework.transaction.event.TransactionPhase; +import org.springframework.transaction.event.TransactionalEventListener; import java.util.List; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; /** - * handler订阅的Spring触发器,在异步的情况下可配置多线程。 + * handler订阅的Spring触发器。 + * + *

事件默认在事务提交后分发(AFTER_COMMIT + fallbackExecution),保证订阅方 + * 能读到已提交数据;异步事件交由 {@link OrderedAsyncDispatcher} 按 traceId 串行分发。

*/ @Slf4j public class SpringDefaultEventHandler extends SpringEventHandler implements InitializingBean { - /** - * 异步多线程的KEY - */ private ExecutorService executorService; + private OrderedAsyncDispatcher dispatcher; + public SpringDefaultEventHandler(List handlers) { ApplicationHandlerUtils.getInstance().addHandlers(handlers); log.info("SpringDefaultEventHandler Success Initial."); } @Override - public void afterPropertiesSet() throws Exception { + public void afterPropertiesSet() { executorService = Executors.newFixedThreadPool(PropertiesContext.getInstance().getHandlerThreadPoolSize()); + dispatcher = new OrderedAsyncDispatcher(executorService, PropertiesContext.getInstance().isEventAsyncOrdered()); } - @EventListener - public synchronized void dispatch(DomainEvent domainEvent) { + @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT, fallbackExecution = true) + public void dispatch(DomainEvent domainEvent) { String traceId = domainEvent.getTraceId(); if (domainEvent.isSync()) { @@ -42,7 +46,7 @@ public synchronized void dispatch(DomainEvent domainEvent) { EventTraceContext.getInstance().checkEventState(); } } else { - executorService.execute(() -> { + dispatcher.execute(traceId, () -> { try { EventTraceContext.getInstance().createEventKey(traceId); ApplicationHandlerUtils.getInstance().handler(domainEvent.getEvent()); @@ -52,5 +56,4 @@ public synchronized void dispatch(DomainEvent domainEvent) { }); } } - } diff --git a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/SpringTransactionEventHandler.java b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/SpringTransactionEventHandler.java index 1f69d59a..12607562 100644 --- a/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/SpringTransactionEventHandler.java +++ b/springboot-starter/src/main/java/com/codingapi/springboot/framework/event/SpringTransactionEventHandler.java @@ -1,58 +1,19 @@ package com.codingapi.springboot.framework.event; -import com.codingapi.springboot.framework.properties.PropertiesContext; -import lombok.extern.slf4j.Slf4j; -import org.springframework.beans.factory.InitializingBean; -import org.springframework.transaction.event.TransactionPhase; -import org.springframework.transaction.event.TransactionalEventListener; - import java.util.List; -import java.util.concurrent.ExecutorService; -import java.util.concurrent.Executors; /** - * handler订阅的Spring触发器,在异步的情况下可配置多线程。 + * 事务事件处理器的兼容别名。 + * + * @deprecated 自事件分发统一为「事务提交后按 trace 串行」后,本类与 + * {@link SpringDefaultEventHandler} 行为完全一致。保留仅用于兼容按类名注入的既有代码; + * 新代码请直接使用 {@link SpringDefaultEventHandler}。配置 + * {@code codingapi.framework.event.transaction.enable} 不再产生行为差异。 */ -@Slf4j -public class SpringTransactionEventHandler extends SpringEventHandler implements InitializingBean { - - /** - * 异步多线程的KEY - */ - - private ExecutorService executorService ; +@Deprecated +public class SpringTransactionEventHandler extends SpringDefaultEventHandler { public SpringTransactionEventHandler(List handlers) { - ApplicationHandlerUtils.getInstance().addHandlers(handlers); - log.info("SpringTransactionEventHandler Success Initial."); - } - - @Override - public void afterPropertiesSet() throws Exception { - executorService = Executors.newFixedThreadPool(PropertiesContext.getInstance().getHandlerThreadPoolSize()); + super(handlers); } - - @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT, fallbackExecution = true) - public synchronized void dispatch(DomainEvent domainEvent) { - String traceId = domainEvent.getTraceId(); - - if (domainEvent.isSync()) { - try { - EventTraceContext.getInstance().createEventKey(traceId); - ApplicationHandlerUtils.getInstance().handler(domainEvent.getEvent()); - } finally { - EventTraceContext.getInstance().checkEventState(); - } - } else { - executorService.execute(() -> { - try { - EventTraceContext.getInstance().createEventKey(traceId); - ApplicationHandlerUtils.getInstance().handler(domainEvent.getEvent()); - } finally { - EventTraceContext.getInstance().checkEventState(); - } - }); - } - } - } diff --git a/springboot-starter/src/main/java/com/codingapi/springboot/framework/properties/FrameworkProperties.java b/springboot-starter/src/main/java/com/codingapi/springboot/framework/properties/FrameworkProperties.java index 6bd1f036..fe269233 100644 --- a/springboot-starter/src/main/java/com/codingapi/springboot/framework/properties/FrameworkProperties.java +++ b/springboot-starter/src/main/java/com/codingapi/springboot/framework/properties/FrameworkProperties.java @@ -12,5 +12,27 @@ public class FrameworkProperties { */ private int handlerThreadPoolSize = 20; + /** + * 事件相关配置。 + */ + private Event event = new Event(); + + @Setter + @Getter + public static class Event { + + private Async async = new Async(); + } + + @Setter + @Getter + public static class Async { + + /** + * 同一 trace 内的异步事件是否按推送顺序串行执行,默认 true。 + * 关闭后退回完全并发行为,适合无顺序依赖且追求极致吞吐的场景。 + */ + private boolean ordered = true; + } } diff --git a/springboot-starter/src/main/java/com/codingapi/springboot/framework/properties/PropertiesContext.java b/springboot-starter/src/main/java/com/codingapi/springboot/framework/properties/PropertiesContext.java index efb6bd43..4bdcfe68 100644 --- a/springboot-starter/src/main/java/com/codingapi/springboot/framework/properties/PropertiesContext.java +++ b/springboot-starter/src/main/java/com/codingapi/springboot/framework/properties/PropertiesContext.java @@ -19,4 +19,8 @@ public int getHandlerThreadPoolSize() { return properties.getHandlerThreadPoolSize(); } + public boolean isEventAsyncOrdered() { + return properties.getEvent().getAsync().isOrdered(); + } + } diff --git a/springboot-starter/src/test/java/com/codingapi/springboot/framework/event/EventOrderE2ETest.java b/springboot-starter/src/test/java/com/codingapi/springboot/framework/event/EventOrderE2ETest.java new file mode 100644 index 00000000..062579a8 --- /dev/null +++ b/springboot-starter/src/test/java/com/codingapi/springboot/framework/event/EventOrderE2ETest.java @@ -0,0 +1,119 @@ +package com.codingapi.springboot.framework.event; + +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.TestConfiguration; +import org.springframework.context.annotation.Bean; +import org.springframework.transaction.PlatformTransactionManager; +import org.springframework.transaction.support.TransactionTemplate; +import org.springframework.boot.test.context.SpringBootTest; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.HashSet; +import java.util.List; +import java.util.Set; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 端到端顺序回归:事件必须经由 {@link EventPusher#push(IEvent)} 真实推送, + * 覆盖「业务操作连续 push 共享 trace + 异步严格串行」这一此前遗漏的场景。 + */ +@SpringBootTest +class EventOrderE2ETest { + + static class OrderedAsyncEvent implements IAsyncEvent { + final String name; + + OrderedAsyncEvent(String name) { + this.name = name; + } + } + + static final List ORDER = Collections.synchronizedList(new ArrayList<>()); + static final List TRACES = Collections.synchronizedList(new ArrayList<>()); + static volatile CountDownLatch LATCH; + + @TestConfiguration + static class HandlerConfig { + @Bean + IHandler orderedAsyncEventHandler() { + return event -> { + String eventKey = EventTraceContext.getInstance().getEventKey(); + synchronized (ORDER) { + ORDER.add("start-" + event.name); + TRACES.add(eventKey == null ? null : eventKey.split("#")[0]); + } + try { + Thread.sleep(50); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + synchronized (ORDER) { + ORDER.add("end-" + event.name); + } + if (LATCH != null) { + LATCH.countDown(); + } + }; + } + } + + @Autowired + private PlatformTransactionManager transactionManager; + + @BeforeEach + void reset() { + ORDER.clear(); + TRACES.clear(); + LATCH = null; + } + + @Test + void transaction_push_events_share_trace_and_execute_in_order() throws Exception { + LATCH = new CountDownLatch(2); + TransactionTemplate template = new TransactionTemplate(transactionManager); + template.executeWithoutResult(status -> { + EventPusher.push(new OrderedAsyncEvent("A")); + EventPusher.push(new OrderedAsyncEvent("B")); + }); + + assertTrue(LATCH.await(5, TimeUnit.SECONDS), "两个异步事件应全部执行完成"); + assertEquals(java.util.Arrays.asList("start-A", "end-A", "start-B", "end-B"), ORDER, + "同一业务操作中连续 push 的异步事件必须严格按 push 顺序串行执行"); + + Set distinctTraces = new HashSet<>(TRACES); + assertEquals(1, distinctTraces.size(), "同一事务内的连续 push 应共享同一 traceId"); + } + + @Test + void batch_push_same_type_events_not_treated_as_loop() throws Exception { + LATCH = new CountDownLatch(2); + EventPusher.push(new OrderedAsyncEvent("B1"), new OrderedAsyncEvent("B2")); + + assertTrue(LATCH.await(5, TimeUnit.SECONDS), "批量异步事件应全部执行完成"); + assertEquals(java.util.Arrays.asList("start-B1", "end-B1", "start-B2", "end-B2"), ORDER, + "批量内同类事件应串行执行,且不被误判为循环调用"); + assertEquals(1, new HashSet<>(TRACES).size(), "批量事件应共享同一 traceId"); + } + + @Test + void rollback_transaction_does_not_dispatch_events() throws Exception { + LATCH = new CountDownLatch(1); + TransactionTemplate template = new TransactionTemplate(transactionManager); + assertThrows(IllegalStateException.class, () -> template.executeWithoutResult(status -> { + EventPusher.push(new OrderedAsyncEvent("R")); + throw new IllegalStateException("force rollback"); + })); + + // AFTER_COMMIT 语义:事务回滚不应触发事件,等待客户端确认无 handler 执行 + Thread.sleep(300); + assertTrue(ORDER.isEmpty(), "事务回滚后事件不应被分发"); + } +} diff --git a/springboot-starter/src/test/java/com/codingapi/springboot/framework/event/OrderedAsyncDispatcherTest.java b/springboot-starter/src/test/java/com/codingapi/springboot/framework/event/OrderedAsyncDispatcherTest.java new file mode 100644 index 00000000..217a1778 --- /dev/null +++ b/springboot-starter/src/test/java/com/codingapi/springboot/framework/event/OrderedAsyncDispatcherTest.java @@ -0,0 +1,133 @@ +package com.codingapi.springboot.framework.event; + +import org.junit.jupiter.api.Test; + +import java.util.ArrayList; +import java.util.List; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicBoolean; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +class OrderedAsyncDispatcherTest { + + @Test + void same_trace_tasks_execute_in_submit_order() throws Exception { + ExecutorService pool = Executors.newFixedThreadPool(8); + OrderedAsyncDispatcher dispatcher = new OrderedAsyncDispatcher(pool, true); + List order = new ArrayList<>(); + CountDownLatch done = new CountDownLatch(3); + + for (int i = 0; i < 3; i++) { + final int index = i; + dispatcher.execute("trace-1", () -> { + order.add("start-" + index); + try { + Thread.sleep(30); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + order.add("end-" + index); + done.countDown(); + }); + } + + assertTrue(done.await(5, TimeUnit.SECONDS)); + assertEquals(List.of( + "start-0", "end-0", + "start-1", "end-1", + "start-2", "end-2"), order); + pool.shutdownNow(); + } + + @Test + void different_trace_tasks_run_in_parallel() throws Exception { + ExecutorService pool = Executors.newFixedThreadPool(4); + OrderedAsyncDispatcher dispatcher = new OrderedAsyncDispatcher(pool, true); + CountDownLatch bothStarted = new CountDownLatch(2); + CountDownLatch release = new CountDownLatch(1); + AtomicBoolean parallel = new AtomicBoolean(false); + + for (int i = 0; i < 2; i++) { + dispatcher.execute("trace-" + i, () -> { + bothStarted.countDown(); + try { + if (!release.await(3, TimeUnit.SECONDS)) { + return; + } + if (bothStarted.getCount() == 0) { + parallel.set(true); + } + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + }); + } + + assertTrue(bothStarted.await(3, TimeUnit.SECONDS), "不同 trace 的任务应能并行启动"); + release.countDown(); + Thread.sleep(100); + assertTrue(parallel.get(), "不同 trace 的任务应并行执行"); + pool.shutdownNow(); + } + + @Test + void exception_does_not_break_chain() throws Exception { + ExecutorService pool = Executors.newFixedThreadPool(4); + OrderedAsyncDispatcher dispatcher = new OrderedAsyncDispatcher(pool, true); + List order = new ArrayList<>(); + CountDownLatch done = new CountDownLatch(2); + + dispatcher.execute("trace-ex", () -> { + order.add("first"); + done.countDown(); + throw new RuntimeException("boom"); + }); + dispatcher.execute("trace-ex", () -> { + order.add("second"); + done.countDown(); + }); + + assertTrue(done.await(5, TimeUnit.SECONDS)); + assertEquals(List.of("first", "second"), order); + pool.shutdownNow(); + } + + @Test + void completed_trace_is_removed() throws Exception { + ExecutorService pool = Executors.newFixedThreadPool(4); + OrderedAsyncDispatcher dispatcher = new OrderedAsyncDispatcher(pool, true); + CountDownLatch done = new CountDownLatch(2); + + dispatcher.execute("trace-clean", done::countDown); + dispatcher.execute("trace-clean", done::countDown); + + assertTrue(done.await(5, TimeUnit.SECONDS)); + long deadline = System.currentTimeMillis() + 3000; + while (dispatcher.pendingTraceCount() > 0 && System.currentTimeMillis() < deadline) { + Thread.sleep(20); + } + assertEquals(0, dispatcher.pendingTraceCount(), "已完成的 trace 应被清理,避免内存泄漏"); + pool.shutdownNow(); + } + + @Test + void unordered_mode_keeps_legacy_behavior() throws Exception { + ExecutorService pool = Executors.newFixedThreadPool(4); + OrderedAsyncDispatcher dispatcher = new OrderedAsyncDispatcher(pool, false); + assertEquals(0, dispatcher.pendingTraceCount()); + + CountDownLatch done = new CountDownLatch(1); + dispatcher.execute("trace-x", done::countDown); + assertTrue(done.await(5, TimeUnit.SECONDS)); + assertEquals(0, dispatcher.pendingTraceCount(), "关闭有序模式时不应维护 trace 队列"); + pool.shutdownNow(); + } +}