Skip to content

Commit 6a4029e

Browse files
committed
fix: 处理 issue #222 复核剩余建议 (17x/springboot-starter)
- 事务 trace 绑定守卫改为 isActualTransactionActive && isSynchronizationActive, registerSynchronization 加 try/catch 回退,避免 SYNCHRONIZATION_NEVER 事务管理器抛异常打断业务; - 删除只写不读的 traceKeys 集合,减少无界集合心智负担; - SpringTransactionEventHandler 合并为 SpringDefaultEventHandler 的 deprecated 兼容别名, 消除重复的 dispatch 实现,transaction.enable 不再产生行为差异; - 补事务回滚不投递的端到端回归用例; - 文档补充顺序边界:无事务独立 push 不保证顺序、串行维度为 trace(跨并发事务无保证), 说明批量 API、新配置项,标注旧配置废弃。 Closes #222
1 parent f60cee1 commit 6a4029e

6 files changed

Lines changed: 102 additions & 87 deletions

File tree

‎docs/agents/capabilities/springboot-starter/event-system.md‎

Lines changed: 33 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -70,30 +70,54 @@ EventPusher.push(new MyEvent(data), true);
7070
### 配置项
7171

7272
```properties
73-
# 启用事务事件模式(事件在事务提交后触发)
74-
codingapi.framework.event.transaction.enable=true
73+
# 同一 trace 内的异步事件是否按推送顺序串行执行(默认值 true)
74+
# 关闭后退回完全并发行为,适合无顺序依赖、追求极致吞吐的场景
75+
codingapi.framework.event.async.ordered=true
7576

7677
# 异步事件线程池大小(默认值 20)
7778
codingapi.framework.handler-thread-pool-size=20
79+
80+
# 兼容旧配置:现已不再产生行为差异(事件默认即为事务提交后分发),可不配置
81+
codingapi.framework.event.transaction.enable=true
7882
```
7983

8084
### 事件分发模式
8185

82-
框架通过 `SpringHandlerConfiguration` 自动装配事件分发器:
86+
框架通过 `SpringHandlerConfiguration` 自动装配 `SpringDefaultEventHandler`。事件监听统一使用 `@TransactionalEventListener(phase = AFTER_COMMIT, fallbackExecution = true)`:
87+
88+
- **事务提交后分发**:事件在事务提交后才触发,订阅方可读到已提交数据;事务回滚则事件不分发。
89+
- **无事务上下文**:`fallbackExecution = true` 保证事件即时分发,行为与事务外推送一致。
90+
- `SpringTransactionEventHandler` 已标记为 `@Deprecated`,仅作为按类名注入的兼容别名保留,与 `SpringDefaultEventHandler` 行为完全一致;`codingapi.framework.event.transaction.enable` 不再产生行为差异。
8391

84-
- **默认模式**(`SpringDefaultEventHandler`):使用 Spring `@EventListener` 即时触发,同步事件在当前线程执行,异步事件提交到固定大小线程池。
85-
- **事务模式**(`SpringTransactionEventHandler`):当配置 `codingapi.framework.event.transaction.enable=true` 时激活,使用 `@TransactionalEventListener(phase = AFTER_COMMIT)` 确保事件在事务提交后才触发,避免读取到未提交的数据。设置 `fallbackExecution = true` 保证无事务上下文时也能正常执行。
92+
### 顺序保证与 trace 归属
8693

87-
两种模式互斥,事务模式优先(`@ConditionalOnMissingBean` 兜底默认模式)。
94+
异步事件的串行维度是 `traceId`,同一 trace 内的异步事件严格按推送顺序串行执行,不同 trace 之间保持并行(线程池大小决定并发 trace 数)。traceId 的归属规则:
95+
96+
1. **handler 内嵌套 push**:复用当前事件链的 traceId;
97+
2. **批量 push**:调用 `EventPusher.push(e1, e2, ...)`,整批共享一个 traceId,异步事件按参数顺序串行执行;
98+
3. **事务内连续 push**:共享同一事务级 traceId(`TransactionSynchronizationManager` 绑定,`afterCompletion` 解绑,避免线程复用串 trace);
99+
4. **无事务的独立 push**:每次新建独立 traceId,**不保证顺序**。
100+
101+
因此:
102+
103+
> 需要严格顺序时,请将事件置于事务内连续 push,或使用 `EventPusher.push(a, b)` 批量推送;无事务的独立 push 之间不保证顺序。串行维度是 trace(约等于单事务/单批次),**同一聚合在两个并发事务中的事件之间仍无顺序保证**,业务方若要求聚合级串行需自行按聚合键排队。
88104
89105
### 事件循环检测
90106

91107
框架通过 `EventTraceContext` 和 `EventStackContext` 实现同一条事件链路内的循环检测:
92108

93109
1. 每次推送事件时生成/复用 traceId,将事件类压入该 traceId 对应的事件栈。
94-
2. 若同一 traceId 下出现相同事件类,立即抛出 `EventLoopException`,并附带完整的事件调用栈信息。
95-
3. 事件处理完成后自动清理 traceId 和事件栈。
96-
4. 若确实需要允许循环(如状态机重试),可调用 `EventPusher.push(event, true)` 跳过检测。
110+
2. **循环检测只对 handler 内嵌套 push 生效**:若同一 traceId 下出现相同事件类,立即抛出 `EventLoopException`,并附带完整的事件调用栈信息。
111+
3. 业务线程中连续 push 的多个事件(批量或事务内)属于同一批次,即使同类也不会被误判为循环。
112+
4. 事件处理完成后自动清理 traceId 和事件栈;若确实需要允许 handler 内嵌套循环(如状态机重试),可调用 `EventPusher.push(event, true)` 跳过检测。
113+
114+
### Handler 异常处理策略
115+
116+
当某个 Handler 抛出异常时:
117+
1. 若异常为 `EventLoopException`,直接向上抛出,终止后续所有 Handler。
118+
2. 否则调用该 Handler 的 `error(exception)` 回调。
119+
3. 若 `error()` 也抛出异常,标记为"有异常"并继续执行下一个 Handler。
120+
4. 所有 Handler 执行完毕后,若存在异常,统一包装为 `EventException` 抛出。
97121

98122
### Handler 异常处理策略
99123

‎docs/capabilities/springboot-starter/event-system.md‎

Lines changed: 25 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -81,30 +81,46 @@ EventPusher.push(new MyEvent(data), true);
8181
### 配置项
8282

8383
```properties
84-
# 启用事务事件模式(事件在事务提交后触发)
85-
codingapi.framework.event.transaction.enable=true
84+
# 同一 trace 内的异步事件是否按推送顺序串行执行(默认值 true)
85+
# 关闭后退回完全并发行为,适合无顺序依赖、追求极致吞吐的场景
86+
codingapi.framework.event.async.ordered=true
8687

8788
# 异步事件线程池大小(默认值 20)
8889
codingapi.framework.handler-thread-pool-size=20
90+
91+
# 兼容旧配置:现已不再产生行为差异(事件默认即为事务提交后分发),可不配置
92+
codingapi.framework.event.transaction.enable=true
8993
```
9094

9195
### 事件分发模式
9296

93-
框架通过 `SpringHandlerConfiguration` 自动装配事件分发器:
97+
框架通过 `SpringHandlerConfiguration` 自动装配 `SpringDefaultEventHandler`。事件监听统一使用 `@TransactionalEventListener(phase = AFTER_COMMIT, fallbackExecution = true)`:
98+
99+
- **事务提交后分发**:事件在事务提交后才触发,订阅方可读到已提交数据;事务回滚则事件不分发。
100+
- **无事务上下文**:`fallbackExecution = true` 保证事件即时分发,行为与事务外推送一致。
101+
- `SpringTransactionEventHandler` 已标记为 `@Deprecated`,仅作为按类名注入的兼容别名保留,与 `SpringDefaultEventHandler` 行为完全一致;`codingapi.framework.event.transaction.enable` 不再产生行为差异。
102+
103+
### 顺序保证与 trace 归属
104+
105+
异步事件的串行维度是 `traceId`,同一 trace 内的异步事件严格按推送顺序串行执行,不同 trace 之间保持并行(线程池大小决定并发 trace 数)。traceId 的归属规则:
106+
107+
1. **handler 内嵌套 push**:复用当前事件链的 traceId;
108+
2. **批量 push**:调用 `EventPusher.push(e1, e2, ...)`,整批共享一个 traceId,异步事件按参数顺序串行执行;
109+
3. **事务内连续 push**:共享同一事务级 traceId(`TransactionSynchronizationManager` 绑定,`afterCompletion` 解绑,避免线程复用串 trace);
110+
4. **无事务的独立 push**:每次新建独立 traceId,**不保证顺序**。
94111

95-
- **默认模式**(`SpringDefaultEventHandler`):使用 Spring `@EventListener` 即时触发,同步事件在当前线程执行,异步事件提交到固定大小线程池。
96-
- **事务模式**(`SpringTransactionEventHandler`):当配置 `codingapi.framework.event.transaction.enable=true` 时激活,使用 `@TransactionalEventListener(phase = AFTER_COMMIT)` 确保事件在事务提交后才触发,避免读取到未提交的数据。设置 `fallbackExecution = true` 保证无事务上下文时也能正常执行。
112+
因此:
97113

98-
两种模式互斥,事务模式优先(`@ConditionalOnMissingBean` 兜底默认模式)。
114+
> 需要严格顺序时,请将事件置于事务内连续 push,或使用 `EventPusher.push(a, b)` 批量推送;无事务的独立 push 之间不保证顺序。串行维度是 trace(约等于单事务/单批次),**同一聚合在两个并发事务中的事件之间仍无顺序保证**,业务方若要求聚合级串行需自行按聚合键排队。
99115
100116
### 事件循环检测
101117

102118
框架通过 `EventTraceContext` 和 `EventStackContext` 实现同一条事件链路内的循环检测:
103119

104120
1. 每次推送事件时生成/复用 traceId,将事件类压入该 traceId 对应的事件栈。
105-
2. 若同一 traceId 下出现相同事件类,立即抛出 `EventLoopException`,并附带完整的事件调用栈信息。
106-
3. 事件处理完成后自动清理 traceId 和事件栈。
107-
4. 若确实需要允许循环(如状态机重试),可调用 `EventPusher.push(event, true)` 跳过检测。
121+
2. **循环检测只对 handler 内嵌套 push 生效**:若同一 traceId 下出现相同事件类,立即抛出 `EventLoopException`,并附带完整的事件调用栈信息。
122+
3. 业务线程中连续 push 的多个事件(批量或事务内)属于同一批次,即使同类也不会被误判为循环。
123+
4. 事件处理完成后自动清理 traceId 和事件栈;若确实需要允许 handler 内嵌套循环(如状态机重试),可调用 `EventPusher.push(event, true)` 跳过检测。
108124

109125
### Handler 异常处理策略
110126

‎docs/wiki/springboot-starter.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -537,4 +537,5 @@ public class FrameWorkApplication {
537537
| 配置项 | 说明 | 默认值 |
538538
|--------|------|--------|
539539
| `codingapi.framework.handler-thread-pool-size` | 事件异步线程池大小,对应`FrameworkProperties.handlerThreadPoolSize`(绑定前缀`codingapi.framework`) | 20 |
540-
| `codingapi.framework.event.transaction.enable` | 开启事务事件处理器。配置为`true`时,`SpringHandlerConfiguration`通过`@ConditionalOnProperty`注册`SpringTransactionEventHandler`,否则使用默认的`SpringDefaultEventHandler` | 不开启 |
540+
| `codingapi.framework.event.async.ordered` | 同一 trace 内的异步事件是否按推送顺序串行执行;关闭后退回去完全并发行为 | true |
541+
| `codingapi.framework.event.transaction.enable` | 兼容旧配置,现已不再产生行为差异(事件默认即为事务提交后分发)。`SpringTransactionEventHandler` 已废弃,仅为按类名注入的兼容别名 | 不开启 |

‎springboot-starter/src/main/java/com/codingapi/springboot/framework/event/EventTraceContext.java‎

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@
99
import java.util.ArrayList;
1010
import java.util.List;
1111
import java.util.Map;
12-
import java.util.Set;
1312
import java.util.UUID;
1413
import java.util.concurrent.ConcurrentHashMap;
1514

@@ -35,9 +34,6 @@ public class EventTraceContext {
3534
*/
3635
private static final Object TRANSACTION_TRACE_KEY = new Object();
3736

38-
// trace key,异步事件由线程池线程并发读写,需使用并发容器
39-
private final Set<String> traceKeys = ConcurrentHashMap.newKeySet();
40-
4137
// 当前线程正在执行的事件 key(traceId#random)
4238
private final ThreadLocal<String> threadLocal = new ThreadLocal<>();
4339

@@ -54,9 +50,7 @@ private EventTraceContext() {
5450
* 创建一个全新的 traceId。
5551
*/
5652
String newTrace() {
57-
String traceId = UUID.randomUUID().toString().replaceAll("-", "");
58-
traceKeys.add(traceId);
59-
return traceId;
53+
return UUID.randomUUID().toString().replaceAll("-", "");
6054
}
6155

6256
/**
@@ -71,7 +65,11 @@ String getOrCreateTrace() {
7165
if (batchTrace != null) {
7266
return batchTrace;
7367
}
74-
if (TransactionSynchronizationManager.isActualTransactionActive()) {
68+
// registerSynchronization 要求 synchronization 处于激活状态;
69+
// isActualTransactionActive() 为 true 但 synchronization 未激活时(如
70+
// SYNCHRONIZATION_NEVER 的事务管理器)必须回退,否则抛 IllegalStateException 打断业务。
71+
if (TransactionSynchronizationManager.isActualTransactionActive()
72+
&& TransactionSynchronizationManager.isSynchronizationActive()) {
7573
return getOrCreateTransactionTrace();
7674
}
7775
return newTrace();
@@ -87,12 +85,18 @@ private String getOrCreateTransactionTrace() {
8785
}
8886
String traceId = newTrace();
8987
TransactionSynchronizationManager.bindResource(TRANSACTION_TRACE_KEY, traceId);
90-
TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {
91-
@Override
92-
public void afterCompletion(int status) {
93-
TransactionSynchronizationManager.unbindResourceIfPossible(TRANSACTION_TRACE_KEY);
94-
}
95-
});
88+
try {
89+
TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {
90+
@Override
91+
public void afterCompletion(int status) {
92+
TransactionSynchronizationManager.unbindResourceIfPossible(TRANSACTION_TRACE_KEY);
93+
}
94+
});
95+
} catch (IllegalStateException e) {
96+
// 防御:synchronization 在并发边界失效时解绑资源并回退为独立 trace,绝不影响业务操作
97+
TransactionSynchronizationManager.unbindResourceIfPossible(TRANSACTION_TRACE_KEY);
98+
return newTrace();
99+
}
96100
return traceId;
97101
}
98102

@@ -143,7 +147,6 @@ void checkEventState() {
143147
Boolean state = eventKeyState.get(eventKey);
144148
if (state != null && !state) {
145149
String traceId = eventKey.split("#")[0];
146-
traceKeys.remove(traceId);
147150
EventStackContext.getInstance().remove(traceId);
148151
}
149152
eventKeyState.remove(eventKey);
@@ -160,7 +163,6 @@ void checkEventState() {
160163
void addEvent(String traceId, IEvent event) {
161164
if (isNestedPush() && EventStackContext.getInstance().checkEventLoop(traceId, event)) {
162165
List<Class<?>> stack = EventStackContext.getInstance().getEventClasses(traceId);
163-
traceKeys.remove(traceId);
164166
EventStackContext.getInstance().remove(traceId);
165167
eventKeyState.remove(traceId);
166168
threadLocal.remove();
@@ -176,7 +178,6 @@ public void clearTrace() {
176178
String eventKey = threadLocal.get();
177179
if (eventKey != null) {
178180
String traceId = eventKey.split("#")[0];
179-
traceKeys.remove(traceId);
180181
EventStackContext.getInstance().remove(traceId);
181182
eventKeyState.remove(eventKey);
182183
threadLocal.remove();
Lines changed: 9 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,19 @@
11
package com.codingapi.springboot.framework.event;
22

3-
import com.codingapi.springboot.framework.properties.PropertiesContext;
4-
import lombok.extern.slf4j.Slf4j;
5-
import org.springframework.beans.factory.InitializingBean;
6-
import org.springframework.transaction.event.TransactionPhase;
7-
import org.springframework.transaction.event.TransactionalEventListener;
8-
93
import java.util.List;
10-
import java.util.concurrent.ExecutorService;
11-
import java.util.concurrent.Executors;
124

135
/**
14-
* handler订阅的Spring触发器,在异步的情况下可配置多线程。
6+
* 事务事件处理器的兼容别名。
7+
*
8+
* @deprecated 自事件分发统一为「事务提交后按 trace 串行」后,本类与
9+
* {@link SpringDefaultEventHandler} 行为完全一致。保留仅用于兼容按类名注入的既有代码;
10+
* 新代码请直接使用 {@link SpringDefaultEventHandler}。配置
11+
* {@code codingapi.framework.event.transaction.enable} 不再产生行为差异。
1512
*/
16-
@Slf4j
17-
public class SpringTransactionEventHandler extends SpringEventHandler implements InitializingBean {
18-
19-
/**
20-
* 异步多线程的KEY
21-
*/
22-
23-
private ExecutorService executorService ;
24-
25-
private OrderedAsyncDispatcher dispatcher;
13+
@Deprecated
14+
public class SpringTransactionEventHandler extends SpringDefaultEventHandler {
2615

2716
public SpringTransactionEventHandler(List<IHandler> handlers) {
28-
ApplicationHandlerUtils.getInstance().addHandlers(handlers);
29-
log.info("SpringTransactionEventHandler Success Initial.");
30-
}
31-
32-
@Override
33-
public void afterPropertiesSet() throws Exception {
34-
executorService = Executors.newFixedThreadPool(PropertiesContext.getInstance().getHandlerThreadPoolSize());
35-
dispatcher = new OrderedAsyncDispatcher(executorService, PropertiesContext.getInstance().isEventAsyncOrdered());
17+
super(handlers);
3618
}
37-
38-
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT, fallbackExecution = true)
39-
public void dispatch(DomainEvent domainEvent) {
40-
String traceId = domainEvent.getTraceId();
41-
42-
if (domainEvent.isSync()) {
43-
try {
44-
EventTraceContext.getInstance().createEventKey(traceId);
45-
ApplicationHandlerUtils.getInstance().handler(domainEvent.getEvent());
46-
} finally {
47-
EventTraceContext.getInstance().checkEventState();
48-
}
49-
} else {
50-
dispatcher.execute(traceId, () -> {
51-
try {
52-
EventTraceContext.getInstance().createEventKey(traceId);
53-
ApplicationHandlerUtils.getInstance().handler(domainEvent.getEvent());
54-
} finally {
55-
EventTraceContext.getInstance().checkEventState();
56-
}
57-
});
58-
}
59-
}
60-
6119
}

‎springboot-starter/src/test/java/com/codingapi/springboot/framework/event/EventOrderE2ETest.java‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
import java.util.concurrent.TimeUnit;
1919

2020
import static org.junit.jupiter.api.Assertions.assertEquals;
21+
import static org.junit.jupiter.api.Assertions.assertThrows;
2122
import static org.junit.jupiter.api.Assertions.assertTrue;
2223

2324
/**
@@ -101,4 +102,18 @@ void batch_push_same_type_events_not_treated_as_loop() throws Exception {
101102
"批量内同类事件应串行执行,且不被误判为循环调用");
102103
assertEquals(1, new HashSet<>(TRACES).size(), "批量事件应共享同一 traceId");
103104
}
105+
106+
@Test
107+
void rollback_transaction_does_not_dispatch_events() throws Exception {
108+
LATCH = new CountDownLatch(1);
109+
TransactionTemplate template = new TransactionTemplate(transactionManager);
110+
assertThrows(IllegalStateException.class, () -> template.executeWithoutResult(status -> {
111+
EventPusher.push(new OrderedAsyncEvent("R"));
112+
throw new IllegalStateException("force rollback");
113+
}));
114+
115+
// AFTER_COMMIT 语义:事务回滚不应触发事件,等待客户端确认无 handler 执行
116+
Thread.sleep(300);
117+
assertTrue(ORDER.isEmpty(), "事务回滚后事件不应被分发");
118+
}
104119
}

0 commit comments

Comments
 (0)