Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ REST 层通过请求参数 `mockKey` 分流到 Mock 实例(见 `FlowRecordCont

### 事件(IFlowEvent + EventPusher)

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

### API 模块划分

Expand Down
58 changes: 43 additions & 15 deletions docs/Integration/event-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,23 @@ public class FlowRecordUrgeEvent implements IFlowEvent {
- 并行:`getParallelId()`、`getParallelBranchNodeId()`、`getParallelBranchTotal()`
- 时间:`getCreateTime()`、`getUpdateTime()`、`getFinishTime()`、`getTimeoutTime()`

## 2. 推送:`EventPusher`
## 2. 推送:`FlowEventPublisher`(引擎内统一入口)

引擎内部**不再直接调用** `EventPusher`,统一走 `com.codingapi.flow.event.FlowEventPublisher`:

```java
FlowEventPublisher.push(new FlowRecordStartEvent(flowRecord, session.isMock()));
```

`FlowEventPublisher` 是门面,行为取决于是否注册了发布器实现(`IFlowEventPublisher`):

| 场景 | 行为 |
|---|---|
| 引入 `flow-engine-starter`(默认) | 由 `SpringFlowEventPublisher` 投递:**事务提交后**才投递、按 `IFlowEvent.eventKey()`(默认流程id)分区**串行**,见 4.5 |
| 仅使用 framework / 单元测试 | **回退**为 `EventPusher.push`,与旧版本行为一致 |
| 配置 `codingapi.flow.event.ordered=false` | 不注册实现,回退为 `EventPusher.push` |

底层 `EventPusher`(回退路径)语义:

```java
package com.codingapi.springboot.framework.event;
Expand All @@ -96,12 +112,6 @@ public class EventPusher {
}
```

调用方式(引擎内部统一使用单参形式):

```java
EventPusher.push(new FlowRecordStartEvent(flowRecord, session.isMock()));
```

### 引擎内推送事件的位置

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

## 4. 完整分发管道

引入 starter 时(默认):

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

回退路径(未注册发布器):`EventPusher.push → DomainEventContext.push → ...` 与旧版本一致。

### 4.1 循环事件检测

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

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

### 4.5 顺序与事务可见性保障(`SpringFlowEventPublisher`)

为解决「订阅方在事务提交前消费、同流程事件乱序」的问题(issue #274),starter 默认装配 `SpringFlowEventPublisher`:

- **提交后投递**:有活动事务时通过 `TransactionSynchronization#afterCommit` 投递,订阅方回查数据库一定能读到流程记录/待办/关系数据;事务回滚不投递。
- **按流程串行**:`IFlowEvent.eventKey()` 默认取 `processId`(子流程重置事件取主流程id),散列到固定的单线程分区(默认 4 个分区),同一流程严格按产生顺序执行,不同流程并行。
- **同步执行**:投递时使用 `DomainEvent(sync=true)`,handler 在分区线程内执行完毕,避免再次落入 20 线程池导致乱序。
- **异常隔离**:单个 handler 异常只记录日志,不阻塞同分区后续事件;**注意**:异常不会再回传给业务线程(旧版本异步路径同样不会)。
- **线程模型**:`flow-event-dispatch-{分区}-{序号}` 守护线程;应用关闭时 `destroy()` 注销发布器并停止分区线程。
- **配置**:`codingapi.flow.event.ordered=false` 可整体关闭(回退为直接 `EventPusher.push`)。

**尚未覆盖(见 issue #274 阶段二)**:事件未持久化,进程崩溃或停机瞬间尚未投递的事件会丢失;重试目前仅有单次执行 + 日志。后续将引入 `t_flow_event_outbox`(与业务同事务落库 + 定时补偿重试 + 死信),实现「至少一次」,届时订阅方需按 `processId + eventType + recordId` 做幂等。

## 5. 通知/消息扩展点

引擎**不提供**任何消息发送/桥接抽象。与「通知」相关的能力:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
import com.codingapi.flow.script.node.OperatorLoadScript;
import com.codingapi.flow.session.FlowSession;
import com.codingapi.flow.session.IRepositoryHolder;
import com.codingapi.springboot.framework.event.EventPusher;
import com.codingapi.flow.event.FlowEventPublisher;
import org.springframework.util.StringUtils;

import java.util.ArrayList;
Expand Down Expand Up @@ -137,7 +137,7 @@ public void run(FlowSession flowSession) {
}

repositoryHolder.saveRecords(flowRecords);
flowEvents.forEach(EventPusher::push);
flowEvents.forEach(FlowEventPublisher::push);
}

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
import com.codingapi.flow.script.node.OperatorLoadScript;
import com.codingapi.flow.session.FlowSession;
import com.codingapi.flow.session.IRepositoryHolder;
import com.codingapi.springboot.framework.event.EventPusher;
import com.codingapi.flow.event.FlowEventPublisher;
import org.springframework.util.StringUtils;

import java.util.ArrayList;
Expand Down Expand Up @@ -101,7 +101,7 @@ public void run(FlowSession flowSession) {
}

repositoryHolder.saveRecords(recordList);
flowEvents.forEach(EventPusher::push);
flowEvents.forEach(FlowEventPublisher::push);

}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
import com.codingapi.flow.session.IRepositoryHolder;
import com.codingapi.flow.strategy.node.MultiOperatorAuditStrategy;
import com.codingapi.flow.strategy.node.OperatorSelectType;
import com.codingapi.springboot.framework.event.EventPusher;
import com.codingapi.flow.event.FlowEventPublisher;

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

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
import com.codingapi.flow.session.FlowSession;
import com.codingapi.flow.session.IRepositoryHolder;
import com.codingapi.flow.strategy.node.MultiOperatorAuditStrategy;
import com.codingapi.springboot.framework.event.EventPusher;
import com.codingapi.flow.event.FlowEventPublisher;
import org.springframework.util.StringUtils;

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

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

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
import com.codingapi.flow.script.action.ActionRejectScript;
import com.codingapi.flow.session.FlowSession;
import com.codingapi.flow.session.IRepositoryHolder;
import com.codingapi.springboot.framework.event.EventPusher;
import com.codingapi.flow.event.FlowEventPublisher;
import lombok.Getter;

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

}
}
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
import com.codingapi.flow.record.FlowRecord;
import com.codingapi.flow.session.FlowSession;
import com.codingapi.flow.session.IRepositoryHolder;
import com.codingapi.springboot.framework.event.EventPusher;
import com.codingapi.flow.event.FlowEventPublisher;

import java.util.ArrayList;
import java.util.List;
Expand Down Expand Up @@ -78,7 +78,7 @@ public void run(FlowSession flowSession) {

repositoryHolder.saveRecords(recordList);

flowEvents.forEach(EventPusher::push);
flowEvents.forEach(FlowEventPublisher::push);

}
}
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
import com.codingapi.flow.script.node.OperatorLoadScript;
import com.codingapi.flow.session.FlowSession;
import com.codingapi.flow.session.IRepositoryHolder;
import com.codingapi.springboot.framework.event.EventPusher;
import com.codingapi.flow.event.FlowEventPublisher;
import org.springframework.util.StringUtils;

import java.util.ArrayList;
Expand Down Expand Up @@ -107,7 +107,7 @@ public void run(FlowSession flowSession) {
}

repositoryHolder.saveRecords(recordList);
flowEvents.forEach(EventPusher::push);
flowEvents.forEach(FlowEventPublisher::push);
}

@Override
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
package com.codingapi.flow.event;

import com.codingapi.springboot.framework.event.EventPusher;

/**
* 流程事件发布门面。
*
* <p>引擎内统一使用该门面推送事件(不再直接调用 {@code EventPusher.push}):</p>
* <ul>
* <li>已注册 {@link IFlowEventPublisher}(如 starter 提供的实现)时,交由实现投递,
* 可获得「事务提交后投递 + 按流程串行」的语义;</li>
* <li>未注册时回退为 {@code EventPusher.push},与旧版本行为完全一致
* (仅使用 framework、单元测试等场景)。</li>
* </ul>
*/
public class FlowEventPublisher {

private static volatile IFlowEventPublisher publisher;

private FlowEventPublisher() {
}

/**
* 注册事件发布器实现(由 starter 初始化时调用)。
*
* @param eventPublisher 事件发布器
*/
public static void register(IFlowEventPublisher eventPublisher) {
publisher = eventPublisher;
}

/**
* 注销事件发布器实现,恢复为直接调用 {@code EventPusher}(测试或关闭能力时使用)。
*
* @param eventPublisher 待注销的事件发布器,仅当其为当前实现时才生效
*/
public static void unregister(IFlowEventPublisher eventPublisher) {
if (publisher == eventPublisher) {
publisher = null;
}
}

/**
* 推送流程事件。
*
* @param event 流程事件
*/
public static void push(IFlowEvent event) {
IFlowEventPublisher eventPublisher = publisher;
if (eventPublisher == null) {
EventPusher.push(event);
return;
}
eventPublisher.push(event);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,12 @@ public class FlowRecordDeleteEvent implements IFlowEvent {
private final FlowRecord flowRecord;

private final boolean mock;

/**
* 事件分区键:同一流程内的事件按顺序投递
*/
@Override
public String eventKey() {
return flowRecord.getProcessId();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,12 @@ public class FlowRecordDoneEvent implements IFlowEvent {

private final boolean mock;


/**
* 事件分区键:同一流程内的事件按顺序投递
*/
@Override
public String eventKey() {
return flowRecord.getProcessId();
}

}
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,12 @@ public class FlowRecordFinishEvent implements IFlowEvent {
private final FlowRecord flowRecord;

private final boolean mock;

/**
* 事件分区键:同一流程内的事件按顺序投递
*/
@Override
public String eventKey() {
return flowRecord.getProcessId();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,12 @@ public class FlowRecordReduceAuditEvent implements IFlowEvent {
* 是否为模拟环境
*/
private final boolean mock;

/**
* 事件分区键:同一流程内的事件按顺序投递
*/
@Override
public String eventKey() {
return flowRecord.getProcessId();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -22,4 +22,12 @@ public class FlowRecordRevokeEvent implements IFlowEvent {
* 是否为模拟环境
*/
private final boolean mock;

/**
* 事件分区键:同一流程内的事件按顺序投递
*/
@Override
public String eventKey() {
return currentRecord.getProcessId();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,12 @@ public class FlowRecordStartEvent implements IFlowEvent {
private final FlowRecord flowRecord;

private final boolean mock;

/**
* 事件分区键:同一流程内的事件按顺序投递
*/
@Override
public String eventKey() {
return flowRecord.getProcessId();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,12 @@ public class FlowRecordTodoEvent implements IFlowEvent {
private final FlowRecord flowRecord;

private final boolean mock;

/**
* 事件分区键:同一流程内的事件按顺序投递
*/
@Override
public String eventKey() {
return flowRecord.getProcessId();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,12 @@ public class FlowRecordUrgeEvent implements IFlowEvent {

private final boolean mock;

/**
* 事件分区键:同一流程内的事件按顺序投递
*/
@Override
public String eventKey() {
return flowRecord.getProcessId();
}

}
Original file line number Diff line number Diff line change
Expand Up @@ -44,4 +44,12 @@ public class FlowSubProcessResetEvent implements IFlowEvent {
* 是否模拟环境
*/
private final boolean mock;

/**
* 事件分区键:按主流程id串行投递
*/
@Override
public String eventKey() {
return oldRecord == null ? null : oldRecord.getParentProcessId();
}
}
Loading
Loading