Skip to content

Commit d5376c4

Browse files
committed
feat: 流程事件统一走 FlowEventPublisher,保证提交后投递与按流程串行
- 新增 IFlowEventPublisher SPI 与 FlowEventPublisher 门面;IFlowEvent 增加 eventKey() 分区键(默认 processId) - 引擎内全部事件推送点由 EventPusher 收敛到 FlowEventPublisher,未注册实现时自动回退,行为不变 - starter 新增 SpringFlowEventPublisher:事务 afterCommit 投递(回滚不投递)、按 eventKey 分区单线程串行、 同步执行 handler 以获得确定顺序、单 handler 异常不影响后续事件 - 新增配置 codingapi.flow.event.ordered(默认开启) - 补充发布门面与发布器单元测试,更新事件集成文档与 AGENTS.md Closes #274
1 parent b42a66e commit d5376c4

33 files changed

Lines changed: 761 additions & 48 deletions

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ REST 层通过请求参数 `mockKey` 分流到 Mock 实例(见 `FlowRecordCont
6464

6565
### 事件(IFlowEvent + EventPusher)
6666

67-
9 种事件:开始 / 待办 / 已办 / 完成 / 催办 / 撤销(`FlowRecordRevokeEvent`)/ 删除(`FlowRecordDeleteEvent`)/ 子流程重置(`FlowSubProcessResetEvent`)/ 减签(`FlowRecordReduceAuditEvent`)。操作完成后用 `EventPusher.push(event)` 推送;记录类事件携带 `FlowRecord` + `mock` 标记,重置事件携带新旧聚合组快照。外部可用 Spring `@EventListener` 订阅。
67+
9 种事件:开始 / 待办 / 已办 / 完成 / 催办 / 撤销(`FlowRecordRevokeEvent`)/ 删除(`FlowRecordDeleteEvent`)/ 子流程重置(`FlowSubProcessResetEvent`)/ 减签(`FlowRecordReduceAuditEvent`)。操作完成后用 `FlowEventPublisher.push(event)` 推送(**禁止**直接调用 `EventPusher`);引入 starter 时由 `SpringFlowEventPublisher` 保证「事务提交后投递 + 按 `eventKey()`(默认 processId)分区串行」,未注册实现时自动回退 `EventPusher`。记录类事件携带 `FlowRecord` + `mock` 标记,重置事件携带新旧聚合组快照。外部可用 Spring `@EventListener` 订阅。
6868

6969
### API 模块划分
7070

‎docs/Integration/event-integration.md‎

Lines changed: 43 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,23 @@ public class FlowRecordUrgeEvent implements IFlowEvent {
7676
- 并行:`getParallelId()`、`getParallelBranchNodeId()`、`getParallelBranchTotal()`
7777
- 时间:`getCreateTime()`、`getUpdateTime()`、`getFinishTime()`、`getTimeoutTime()`
7878

79-
## 2. 推送:`EventPusher`
79+
## 2. 推送:`FlowEventPublisher`(引擎内统一入口)
80+
81+
引擎内部**不再直接调用** `EventPusher`,统一走 `com.codingapi.flow.event.FlowEventPublisher`:
82+
83+
```java
84+
FlowEventPublisher.push(new FlowRecordStartEvent(flowRecord, session.isMock()));
85+
```
86+
87+
`FlowEventPublisher` 是门面,行为取决于是否注册了发布器实现(`IFlowEventPublisher`):
88+
89+
| 场景 | 行为 |
90+
|---|---|
91+
| 引入 `flow-engine-starter`(默认) | 由 `SpringFlowEventPublisher` 投递:**事务提交后**才投递、按 `IFlowEvent.eventKey()`(默认流程id)分区**串行**,见 4.5 |
92+
| 仅使用 framework / 单元测试 | **回退**为 `EventPusher.push`,与旧版本行为一致 |
93+
| 配置 `codingapi.flow.event.ordered=false` | 不注册实现,回退为 `EventPusher.push` |
94+
95+
底层 `EventPusher`(回退路径)语义:
8096

8197
```java
8298
package com.codingapi.springboot.framework.event;
@@ -96,12 +112,6 @@ public class EventPusher {
96112
}
97113
```
98114

99-
调用方式(引擎内部统一使用单参形式):
100-
101-
```java
102-
EventPusher.push(new FlowRecordStartEvent(flowRecord, session.isMock()));
103-
```
104-
105115
### 引擎内推送事件的位置
106116

107117
| 位置 | 推送内容 |
@@ -184,17 +194,22 @@ public class MyFlowRecordUrgeEventHandler implements IHandler<FlowRecordUrgeEven
184194

185195
## 4. 完整分发管道
186196

197+
引入 starter 时(默认):
198+
187199
```
188-
业务代码 → EventPusher.push(event)
189-
→ DomainEventContext.push (IAsyncEvent → 异步)
190-
→ EventTraceContext 记录 trace + 循环事件检测(命中抛 EventLoopException)
191-
→ Spring ApplicationContext.publishEvent(new DomainEvent(event, sync, traceId))
192-
→ SpringDefaultEventHandler.@EventListener dispatch
193-
→ 异步:executorService.execute(() -> ApplicationHandlerUtils.handler(event))
194-
同步:内联执行
195-
→ 按 order() 排序,按泛型匹配执行所有 IHandler
200+
业务代码 → FlowEventPublisher.push(event)
201+
→ SpringFlowEventPublisher.push
202+
→ 有事务:登记 TransactionSynchronization#afterCommit(提交后才投递;回滚不投递)
203+
→ 无事务:立即投递
204+
→ 按 eventKey(默认 processId)散列到单线程分区(同流程串行、跨流程并行)
205+
→ ApplicationContext.publishEvent(new DomainEvent(event, sync=true, traceId))
206+
→ SpringDefaultEventHandler.dispatch(同步分支)
207+
→ 在分区线程内按 order() 排序,按泛型匹配执行所有 IHandler
208+
→ handler 异常仅记录日志,不阻塞同分区后续事件
196209
```
197210

211+
回退路径(未注册发布器):`EventPusher.push → DomainEventContext.push → ...` 与旧版本一致。
212+
198213
### 4.1 循环事件检测
199214

200215
- 同一 traceId 内,同类事件再次 push 会抛 `EventLoopException`(防止事件→动作→事件的无限循环)。
@@ -214,6 +229,19 @@ public class MyFlowRecordUrgeEventHandler implements IHandler<FlowRecordUrgeEven
214229

215230
`DomainEventContext` 在 `ApplicationContext` 未初始化时(如纯单元测试)**静默丢弃事件**。
216231

232+
### 4.5 顺序与事务可见性保障(`SpringFlowEventPublisher`)
233+
234+
为解决「订阅方在事务提交前消费、同流程事件乱序」的问题(issue #274),starter 默认装配 `SpringFlowEventPublisher`:
235+
236+
- **提交后投递**:有活动事务时通过 `TransactionSynchronization#afterCommit` 投递,订阅方回查数据库一定能读到流程记录/待办/关系数据;事务回滚不投递。
237+
- **按流程串行**:`IFlowEvent.eventKey()` 默认取 `processId`(子流程重置事件取主流程id),散列到固定的单线程分区(默认 4 个分区),同一流程严格按产生顺序执行,不同流程并行。
238+
- **同步执行**:投递时使用 `DomainEvent(sync=true)`,handler 在分区线程内执行完毕,避免再次落入 20 线程池导致乱序。
239+
- **异常隔离**:单个 handler 异常只记录日志,不阻塞同分区后续事件;**注意**:异常不会再回传给业务线程(旧版本异步路径同样不会)。
240+
- **线程模型**:`flow-event-dispatch-{分区}-{序号}` 守护线程;应用关闭时 `destroy()` 注销发布器并停止分区线程。
241+
- **配置**:`codingapi.flow.event.ordered=false` 可整体关闭(回退为直接 `EventPusher.push`)。
242+
243+
**尚未覆盖(见 issue #274 阶段二)**:事件未持久化,进程崩溃或停机瞬间尚未投递的事件会丢失;重试目前仅有单次执行 + 日志。后续将引入 `t_flow_event_outbox`(与业务同事务落库 + 定时补偿重试 + 死信),实现「至少一次」,届时订阅方需按 `processId + eventType + recordId` 做幂等。
244+
217245
## 5. 通知/消息扩展点
218246

219247
引擎**不提供**任何消息发送/桥接抽象。与「通知」相关的能力:

‎flow-engine-framework/src/main/java/com/codingapi/flow/action/actions/AddAuditAction.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
import com.codingapi.flow.script.node.OperatorLoadScript;
1717
import com.codingapi.flow.session.FlowSession;
1818
import com.codingapi.flow.session.IRepositoryHolder;
19-
import com.codingapi.springboot.framework.event.EventPusher;
19+
import com.codingapi.flow.event.FlowEventPublisher;
2020
import org.springframework.util.StringUtils;
2121

2222
import java.util.ArrayList;
@@ -137,7 +137,7 @@ public void run(FlowSession flowSession) {
137137
}
138138

139139
repositoryHolder.saveRecords(flowRecords);
140-
flowEvents.forEach(EventPusher::push);
140+
flowEvents.forEach(FlowEventPublisher::push);
141141
}
142142

143143
/**

‎flow-engine-framework/src/main/java/com/codingapi/flow/action/actions/DelegateAction.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
import com.codingapi.flow.script.node.OperatorLoadScript;
1616
import com.codingapi.flow.session.FlowSession;
1717
import com.codingapi.flow.session.IRepositoryHolder;
18-
import com.codingapi.springboot.framework.event.EventPusher;
18+
import com.codingapi.flow.event.FlowEventPublisher;
1919
import org.springframework.util.StringUtils;
2020

2121
import java.util.ArrayList;
@@ -101,7 +101,7 @@ public void run(FlowSession flowSession) {
101101
}
102102

103103
repositoryHolder.saveRecords(recordList);
104-
flowEvents.forEach(EventPusher::push);
104+
flowEvents.forEach(FlowEventPublisher::push);
105105

106106
}
107107

‎flow-engine-framework/src/main/java/com/codingapi/flow/action/actions/PassAction.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
import com.codingapi.flow.session.IRepositoryHolder;
2525
import com.codingapi.flow.strategy.node.MultiOperatorAuditStrategy;
2626
import com.codingapi.flow.strategy.node.OperatorSelectType;
27-
import com.codingapi.springboot.framework.event.EventPusher;
27+
import com.codingapi.flow.event.FlowEventPublisher;
2828

2929
import java.util.ArrayList;
3030
import java.util.List;
@@ -246,7 +246,7 @@ public void run(FlowSession flowSession) {
246246
// 其 Todo 事件在引擎内虽会生成,但推送业务订阅方前需拦截,避免下游收到"已完成流程的待办"。
247247
flowEvents.stream()
248248
.filter(event -> !isEndNodeTodoEvent(event))
249-
.forEach(EventPusher::push);
249+
.forEach(FlowEventPublisher::push);
250250
}
251251

252252
/**

‎flow-engine-framework/src/main/java/com/codingapi/flow/action/actions/ReduceAuditAction.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
import com.codingapi.flow.session.FlowSession;
1919
import com.codingapi.flow.session.IRepositoryHolder;
2020
import com.codingapi.flow.strategy.node.MultiOperatorAuditStrategy;
21-
import com.codingapi.springboot.framework.event.EventPusher;
21+
import com.codingapi.flow.event.FlowEventPublisher;
2222
import org.springframework.util.StringUtils;
2323

2424
import java.util.ArrayList;
@@ -155,7 +155,7 @@ public void run(FlowSession flowSession) {
155155

156156
// 循序审批的链路由通过时的「最近一条更大 nodeOrder」激活保证,撤销中间记录不需要额外补链
157157
repositoryHolder.saveRecords(saveRecords);
158-
flowEvents.forEach(EventPusher::push);
158+
flowEvents.forEach(FlowEventPublisher::push);
159159
}
160160

161161
/**

‎flow-engine-framework/src/main/java/com/codingapi/flow/action/actions/RejectAction.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
import com.codingapi.flow.script.action.ActionRejectScript;
1616
import com.codingapi.flow.session.FlowSession;
1717
import com.codingapi.flow.session.IRepositoryHolder;
18-
import com.codingapi.springboot.framework.event.EventPusher;
18+
import com.codingapi.flow.event.FlowEventPublisher;
1919
import lombok.Getter;
2020

2121
import java.util.ArrayList;
@@ -129,7 +129,7 @@ public void run(FlowSession flowSession) {
129129
// 结束节点的虚拟记录不是真实业务待办,其 Todo 事件推送业务订阅方前需拦截
130130
flowEvents.stream()
131131
.filter(event -> !isEndNodeTodoEvent(event))
132-
.forEach(EventPusher::push);
132+
.forEach(FlowEventPublisher::push);
133133

134134
}
135135
}

‎flow-engine-framework/src/main/java/com/codingapi/flow/action/actions/ReturnAction.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
import com.codingapi.flow.record.FlowRecord;
1313
import com.codingapi.flow.session.FlowSession;
1414
import com.codingapi.flow.session.IRepositoryHolder;
15-
import com.codingapi.springboot.framework.event.EventPusher;
15+
import com.codingapi.flow.event.FlowEventPublisher;
1616

1717
import java.util.ArrayList;
1818
import java.util.List;
@@ -78,7 +78,7 @@ public void run(FlowSession flowSession) {
7878

7979
repositoryHolder.saveRecords(recordList);
8080

81-
flowEvents.forEach(EventPusher::push);
81+
flowEvents.forEach(FlowEventPublisher::push);
8282

8383
}
8484
}

‎flow-engine-framework/src/main/java/com/codingapi/flow/action/actions/TransferAction.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
import com.codingapi.flow.script.node.OperatorLoadScript;
1616
import com.codingapi.flow.session.FlowSession;
1717
import com.codingapi.flow.session.IRepositoryHolder;
18-
import com.codingapi.springboot.framework.event.EventPusher;
18+
import com.codingapi.flow.event.FlowEventPublisher;
1919
import org.springframework.util.StringUtils;
2020

2121
import java.util.ArrayList;
@@ -107,7 +107,7 @@ public void run(FlowSession flowSession) {
107107
}
108108

109109
repositoryHolder.saveRecords(recordList);
110-
flowEvents.forEach(EventPusher::push);
110+
flowEvents.forEach(FlowEventPublisher::push);
111111
}
112112

113113
@Override
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
package com.codingapi.flow.event;
2+
3+
import com.codingapi.springboot.framework.event.EventPusher;
4+
5+
/**
6+
* 流程事件发布门面。
7+
*
8+
* <p>引擎内统一使用该门面推送事件(不再直接调用 {@code EventPusher.push}):</p>
9+
* <ul>
10+
* <li>已注册 {@link IFlowEventPublisher}(如 starter 提供的实现)时,交由实现投递,
11+
* 可获得「事务提交后投递 + 按流程串行」的语义;</li>
12+
* <li>未注册时回退为 {@code EventPusher.push},与旧版本行为完全一致
13+
* (仅使用 framework、单元测试等场景)。</li>
14+
* </ul>
15+
*/
16+
public class FlowEventPublisher {
17+
18+
private static volatile IFlowEventPublisher publisher;
19+
20+
private FlowEventPublisher() {
21+
}
22+
23+
/**
24+
* 注册事件发布器实现(由 starter 初始化时调用)。
25+
*
26+
* @param eventPublisher 事件发布器
27+
*/
28+
public static void register(IFlowEventPublisher eventPublisher) {
29+
publisher = eventPublisher;
30+
}
31+
32+
/**
33+
* 注销事件发布器实现,恢复为直接调用 {@code EventPusher}(测试或关闭能力时使用)。
34+
*
35+
* @param eventPublisher 待注销的事件发布器,仅当其为当前实现时才生效
36+
*/
37+
public static void unregister(IFlowEventPublisher eventPublisher) {
38+
if (publisher == eventPublisher) {
39+
publisher = null;
40+
}
41+
}
42+
43+
/**
44+
* 推送流程事件。
45+
*
46+
* @param event 流程事件
47+
*/
48+
public static void push(IFlowEvent event) {
49+
IFlowEventPublisher eventPublisher = publisher;
50+
if (eventPublisher == null) {
51+
EventPusher.push(event);
52+
return;
53+
}
54+
eventPublisher.push(event);
55+
}
56+
}

0 commit comments

Comments
 (0)