Skip to content

Commit f0d3204

Browse files
authored
Merge pull request #225 from codingapi/17.3.x
17.3.x
2 parents abf66f8 + 82360e5 commit f0d3204

14 files changed

Lines changed: 634 additions & 146 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/DomainEventContext.java‎

Lines changed: 48 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@
22

33
import org.springframework.context.ApplicationContext;
44

5+
import java.util.List;
6+
57
class DomainEventContext {
68

79
private static DomainEventContext instance;
810
private ApplicationContext context;
911

10-
1112
private DomainEventContext() {
12-
1313
}
1414

1515
public static DomainEventContext getInstance() {
@@ -23,37 +23,62 @@ public static DomainEventContext getInstance() {
2323
return instance;
2424
}
2525

26-
private void push(IEvent event, boolean sync,boolean hasLoopEvent) {
27-
if (context != null) {
28-
String traceId = EventTraceContext.getInstance().getOrCreateTrace();
29-
if(hasLoopEvent){
30-
EventTraceContext.getInstance().clearTrace();
31-
traceId = EventTraceContext.getInstance().getOrCreateTrace();
32-
}
33-
EventTraceContext.getInstance().addEvent(traceId,event);
34-
context.publishEvent(new DomainEvent(event, sync,traceId));
26+
private boolean isAsync(IEvent event) {
27+
return event instanceof IAsyncEvent;
28+
}
29+
30+
private void publish(IEvent event, String traceId) {
31+
context.publishEvent(new DomainEvent(event, !isAsync(event), traceId));
32+
}
33+
34+
private void doPush(IEvent event, boolean hasLoopEvent) {
35+
if (context == null) {
36+
return;
3537
}
38+
EventTraceContext traceContext = EventTraceContext.getInstance();
39+
String traceId = hasLoopEvent
40+
? traceContext.newTrace()
41+
: traceContext.getOrCreateTrace();
42+
traceContext.addEvent(traceId, event);
43+
publish(event, traceId);
3644
}
3745

3846
/**
39-
* @param event
40-
* @see EventPusher
41-
* 默认 同步事件
47+
* 批量推送:整批事件共享同一 traceId,从而按顺序串行分发。
48+
* 批量内的同类事件不会被误判为循环调用(防环只针对 handler 内嵌套 push)。
4249
*/
43-
public void push(IEvent event,boolean hasLoopEvent) {
44-
if (event instanceof IAsyncEvent) {
45-
this.push(event, false,hasLoopEvent);
46-
} else if (event instanceof ISyncEvent) {
47-
this.push(event, true,hasLoopEvent);
48-
} else {
49-
this.push(event, true,hasLoopEvent);
50+
void pushBatch(List<IEvent> events) {
51+
if (context == null || events == null || events.isEmpty()) {
52+
return;
53+
}
54+
EventTraceContext traceContext = EventTraceContext.getInstance();
55+
String previous = traceContext.getBatchTrace();
56+
String traceId = traceContext.newTrace();
57+
traceContext.setBatchTrace(traceId);
58+
try {
59+
for (IEvent event : events) {
60+
traceContext.addEvent(traceId, event);
61+
publish(event, traceId);
62+
}
63+
} finally {
64+
if (previous == null) {
65+
traceContext.clearBatchTrace();
66+
} else {
67+
traceContext.setBatchTrace(previous);
68+
}
5069
}
5170
}
5271

72+
/**
73+
* 默认 同步事件
74+
*
75+
* @see EventPusher
76+
*/
77+
public void push(IEvent event, boolean hasLoopEvent) {
78+
doPush(event, hasLoopEvent);
79+
}
5380

5481
protected void initContext(ApplicationContext context) {
5582
this.context = context;
5683
}
57-
58-
5984
}

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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
package com.codingapi.springboot.framework.event;
22

3+
import java.util.Arrays;
4+
import java.util.List;
5+
36
/**
47
* Even推送助手
58
*/
@@ -24,4 +27,17 @@ public static void push(IEvent event) {
2427
public static void push(IEvent event, boolean hasLoopEvent) {
2528
DomainEventContext.getInstance().push(event, hasLoopEvent);
2629
}
30+
31+
/**
32+
* 批量推送:整批事件共享同一 trace,异步事件将严格按参数顺序串行执行。
33+
* 批内同类事件不会被误判为循环调用。
34+
*
35+
* @param events 事件(按期望的执行顺序排列)
36+
*/
37+
public static void push(IEvent... events) {
38+
if (events == null || events.length == 0) {
39+
return;
40+
}
41+
DomainEventContext.getInstance().pushBatch(Arrays.asList(events));
42+
}
2743
}

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

Lines changed: 32 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,44 +3,35 @@
33
import lombok.Getter;
44

55
import java.util.ArrayList;
6-
import java.util.HashMap;
6+
import java.util.Collections;
77
import java.util.List;
88
import java.util.Map;
9+
import java.util.concurrent.ConcurrentHashMap;
910

1011
/**
11-
* 事件栈上下文
12+
* 事件栈上下文。
1213
*/
1314
public class EventStackContext {
1415

15-
private final Map<String, List<Class<?>>> eventClassStack = new HashMap<>();
16-
private final Map<String, List<IEvent>> eventStack = new HashMap<>();
16+
private final Map<String, List<Class<?>>> eventClassStack = new ConcurrentHashMap<>();
17+
private final Map<String, List<IEvent>> eventStack = new ConcurrentHashMap<>();
1718

1819
@Getter
1920
private final static EventStackContext instance = new EventStackContext();
2021

2122
private EventStackContext() {
22-
2323
}
2424

2525
private void addEventClass(String traceId, IEvent event) {
26-
List<Class<?>> events = eventClassStack.get(traceId);
27-
if (events == null) {
28-
events = new ArrayList<>();
29-
}
30-
events.add(event.getClass());
31-
eventClassStack.put(traceId, events);
26+
eventClassStack.computeIfAbsent(traceId, key -> Collections.synchronizedList(new ArrayList<>()))
27+
.add(event.getClass());
3228
}
3329

3430
private void addEventStack(String traceId, IEvent event) {
35-
List<IEvent> events = eventStack.get(traceId);
36-
if (events == null) {
37-
events = new ArrayList<>();
38-
}
39-
events.add(event);
40-
eventStack.put(traceId, events);
31+
eventStack.computeIfAbsent(traceId, key -> Collections.synchronizedList(new ArrayList<>()))
32+
.add(event);
4133
}
4234

43-
4435
void addEvent(String traceId, IEvent event) {
4536
addEventClass(traceId, event);
4637
addEventStack(traceId, event);
@@ -49,32 +40,47 @@ void addEvent(String traceId, IEvent event) {
4940
boolean checkEventLoop(String traceId, IEvent event) {
5041
List<Class<?>> events = eventClassStack.get(traceId);
5142
if (events != null) {
52-
return events.contains(event.getClass());
43+
synchronized (events) {
44+
return events.contains(event.getClass());
45+
}
5346
}
5447
return false;
5548
}
5649

50+
/**
51+
* 返回事件列表的快照,不暴露内部可变状态。
52+
*/
5753
public List<IEvent> getEvents(String eventKey) {
58-
if(eventKey!=null) {
54+
if (eventKey != null) {
5955
String traceId = eventKey.split("#")[0];
60-
return eventStack.get(traceId);
56+
List<IEvent> events = eventStack.get(traceId);
57+
if (events != null) {
58+
synchronized (events) {
59+
return new ArrayList<>(events);
60+
}
61+
}
6162
}
6263
return null;
6364
}
6465

66+
/**
67+
* 返回事件类型列表的快照,不暴露内部可变状态。
68+
*/
6569
public List<Class<?>> getEventClasses(String eventKey) {
66-
if(eventKey!=null) {
70+
if (eventKey != null) {
6771
String traceId = eventKey.split("#")[0];
68-
return eventClassStack.get(traceId);
72+
List<Class<?>> events = eventClassStack.get(traceId);
73+
if (events != null) {
74+
synchronized (events) {
75+
return new ArrayList<>(events);
76+
}
77+
}
6978
}
7079
return null;
7180
}
7281

73-
7482
void remove(String traceId) {
7583
eventStack.remove(traceId);
7684
eventClassStack.remove(traceId);
7785
}
78-
79-
8086
}

0 commit comments

Comments
 (0)