前言
产品层面我们已经补齐中国式 OA 全套办理动词,在 sleveen‑admin 完成简单流转真人初测。
但产品按钮跑通只是表象,背后要回答三个硬核工程问题:
- 不断新增办理动作,如何避免到处复制
Gate → Hook → AfterSuccess样板代码?新增动词能不能只写业务 Core? - 用户点击同意、退回、转办,流程引擎、待办任务、业务回写、Outbox 入队,如何保证不出现「半成功」残局?为什么必须收敛到同一数据库事务信封?
- Sync 钩子如果新开连接读取未提交事务行,会触发数据库自锁死锁,这类偶现闷锅故障,引擎层面如何做防护治理?
本文面向准备嵌入 SailFlow、开发 Gate/Hook、自定义流转语义 的开发者,偏向实现契约与故障治理;业务产品视角可以阅读上一篇产品总述。更详尽的专题文档见仓库目录 doc/sail/theme/。
0 核心结论先行
把关键契约先摊开,后续代码评审、PR 提测可以直接对照这组口径:
表格
| 编号 | 契约口径 |
|---|---|
| A1 | FlowActionBase 是公共工具箱;族群基类固化钩子执行时序;业务动词子类仅实现 ExecuteCore |
| A2 | 事务、实例锁仅由 WorkflowService.RunAction / CommitOnSuccess 统一接管;Action、Manager 内部禁止自行开启事务、抢夺实例锁 |
| A3 | 同步钩子 Sync Hook 采用 FailFast,参与事务回滚;异步事件走 Outbox:同事务内完成入队,事务提交之后再消费 Drain |
| A4 | 存在主事务 kit 的场景,同库读写必须复用 ctx.Kit / kit.useSQL();钩子内部直接调用 UseRunSQL() 访问未提交行会触发自锁 |
| A5 | 携带 kit 的同步钩子同样强制埋入 BEGIN/END 埋点;采用软超时,待钩子返回后检测耗时并抛异常;不使用 Thread.Abort,暂不依靠 AsyncLocal 做连接拦截 |
| A6 | SignForward(加签)归属 Transition 族,不修改原始节点 Leave 快照;子 AI 办结 Passed 折合一票向上传递,再交由父层 Leave 规则判定是否流出节点 |
扩展新动词极简配方:
FlowOperation枚举 + 选择对应族群XxxAction(TryLoadContext + ExecuteCore)→ 调用服务薄壳 RunAction
→ 宿主 Handler + 码表配置,有合法命令才暴露到前端办理条。
1 动作骨架:废弃并列 Command Pipeline,三族群继承模型
早期方案曾经设计一层独立命令执行管道 Command Pipeline。落地迭代之后发现两点现实问题:
- Gate / Hook / Notifier 的横切能力已经沉淀在 UseXxx 能力管道,不需要再外层套一层命令管道;
- 最大重复代码不是入口横切,而是各个动词到处复制
BuildGate → ExecuteCore → AfterSuccessHook样板; - 如果事务边界散落在各个 Action 实现内部,同事务一致性契约会直接碎裂。
最终定型三层继承模型,不再维护独立 Command Pipeline。
FlowActionBase(工具箱基类)
│ TryGate / OnFireFlowHook / Build*Context
│ 只提供工具方法,**不固化完整执行时序,不持有事务、实例锁**
│
┌───────────────────┼───────────────────┐
│ │ │
AssigneeActionBase TransitionActionBase LifecycleActionBase
Load→Gate→Core→Hook Load→Gate→Core→Hook Load→Gate→Core→Hook
(可选TaskLifecycle) (可持有Runtime) (以PI流程实例为主)
│ │ │
Transfer / Consult... Run / SendBack / Suspend / Terminate...
SignForward...
三大族群职责边界
表格
| 族群 | 适用业务场景 | Context 约束红线 |
|---|---|---|
| AssigneeActionBase | 流程实例继续运行,流程活动不变;修改任务、办理人、沟通参与者等任务层面变更 | 禁止持有 WfRuntimeManager |
| TransitionActionBase | 流程活动集合、流转拓扑发生变化,包括加签产生临时子拓扑 | internal 允许持有 Runtime |
| LifecycleActionBase | 修改整个流程实例状态 ProcessState(挂起、终止、作废) | 以流程实例 PI 为主 |
统一入口在 WorkflowService.RunAction / RunActionAsync,执行外壳:
XxxProcess入参
→ RunAction / RunActionAsync
→ CommitOnSuccess(kit => {
beginTransaction
InstanceExecutionLock.Acquire(实例键)
new XxxAction(Sail, kit, runner).Execute()
// 族群内部固化时序:Gate → ExecuteCore → OnFireFlowHook
})
✅ 新增动词 PR 审查清单(技术评审直接复用)
- 补充
FlowOperation枚举,归类到正确 Action 族群;- 业务子类只实现装载逻辑与 ExecuteCore,不手写 Gate、AfterSuccess 样板;
- 非 Transition 族群,不要引入 WfRuntimeManager;
- Action 内部禁止写 beginTransaction,禁止自行获取实例锁;
- Success Hook 统一由基类 OnFireFlowHook 执行,业务层不要重复复制通知逻辑;
- Copyto 不属于三大家族,交给宿主 +
ICopytoNotifier;选人解析、Leave 判定与 Action 骨架正交,不要塞进继承树。
2 同事务信封:拒绝「半成功」作为可补偿默认语义
流程引擎线上最可怕故障,往往不是功能缺失,而是部分成功、部分失败产生不一致残局:
- 待办任务标记办结,流程活动没有推进;
- 流程节点已经流转,下游待办任务没有生成;
- 引擎已经走到终态,业务系统表状态没有回写;
- 引擎事务回滚,但外部通知已经推送出去,产生幽灵待办;
- 父记录写入成功,子记录另开连接执行失败,父子数据割裂。
SailFlow 的工程立场:流转核心路径必须严格落在同一个 DB 事务信封之内 。
通知、HTTP 回调这类旁路副作用允许延迟、允许丢失、允许重试,但不能拿来当做核心流转一致性的兜底方案。
事务决策表
表格
| ID | 决策点 |
|---|---|
| T1 | CommitOnSuccess:仅执行结果 Status == Success 才执行事务提交 |
| T2 | 事务创建、提交、回滚全部收敛在 WorkflowService 层,Action 内部不能接管 |
| T3 | 信封内可写集合:引擎流转表、同库同步业务回写、Outbox 待消费记录 INSERT |
| T4 | Sync 钩子异常、软超时 → FailFast,整体事务回滚 |
| T5 | Async 事件:在主事务内完成 Outbox 入队;事务提交成功之后,再短事务 Drain 消费 |
| T6 | kit 是强制契约,钩子读写同库必须复用 kit;禁止新开连接访问未提交行 |
| T7 | Gate 校验拒绝不属于系统故障,需要做到无副作用或者完整干净回滚 |
| T8 | 完整可观测日志作为事务护栏 |
| T9 | OnTransactionCommitted / OnTransactionFailed 运行在信封外部,Kit=null,仅做 Best‑Effort 执行,不能做强一致业务回写 |
信封内 / 信封外边界
【信封内(同一事务,强一致)】
PI流程实例 / Activity活动 / Task待办 / 流程变量 / 流转变更
Sync Hook 同库业务回写
Outbox / Notifier Pending记录入队
CreateHook落库前修改Title、BizPK等业务字段
【信封外(提交之后,尽力执行)】
Outbox Drain消费:HTTP、IM消息推送
Best‑Effort日志、对账定时任务
事务生命周期回调 OnTransactionCommitted
重试、死信处理
重点提醒:需要跟流转同生死的业务状态回写,不能只丢进 Outbox,必须走 Sync 钩子并且复用 kit 上下文。
伪代码示意整体信封逻辑:
kit.beginTransaction();
try {
var result = action(kit); // Gate → Core → Sync Hook(kit) → Enqueue Outbox
if (result.Status == Success) {
kit.commit();
FireTxLifecycle(OnTransactionCommitted); // BestEffort,Kit=null
} else {
FireTxLifecycle(OnTransactionFailed);
}
} catch {
FireTxLifecycle(OnTransactionFailed);
throw; // 抛出,连接释放触发回滚
}
InstanceExecutionLock实例锁:防御同一个流程实例并发交错写入 ;它不能替代数据库事务。锁解决并发乱序,事务解决半成功残局。二者各司其职。
3 Sync 钩子自锁故障:故障指纹、三例复盘与引擎防护
3.1 死锁故障现场(11‑21 典型自锁场景)
主连接 Conn1 开启事务,插入流程实例、任务、变量,随后执行 Sync 钩子;
钩子内部代码没有复用 kit,直接调用 UseRunSQL 新开 Conn2,去读取 Conn1 还没有提交的数据行。
Conn1(流转主kit事务) Conn2(UseRunSQL,无kit)
beginTransaction
INSERT PI / Task / Var...
RunSyncHooks
│ SELECT / UPDATE 未提交行
│◄──── 等待Conn1提交 ──────┤
│ 钩子线程挂起等待返回
▼
自锁卡死 SQLite / SQL Server锁等待
现象:堆栈停留在宿主 IFlowHook.Handle 内部无响应;人工终止之后数据库锁残留,后续所有开启事务全部挂起。
仓库专题文档收录 3 个真实复现案例:
表格
| 案例 | 根因 | 修复方案 |
|---|---|---|
| A ExtraStarted 修改变量 | 钩子内部调用无 kit 版本SaveProcessVariable |
增加携带 kit 的重载,钩子强制使用 ctx.Kit |
| B 选人相对人解析 | Resolve/Filter 内部调用 UseRunSQL 读取刚写入 PI | 传递 AssigneeInvokeRequest.Kit |
| C 子流程 Execute | 子流程新建独立 Sail 实例拿 RunSQL | 使用 kit.useSQL() 复用当前事务会话 |
3.2 防护手段
旧逻辑有一个坑:只要传入 kit,就直接执行 Hook.Handle,直接跳过超时管控。
C# 无法安全暴力终止任意同步业务代码(Thread.Abort 已经废弃;事务连接不能跨线程强杀)。
所以我们不靠 "杀死线程",而是靠日志埋点、软超时、评审契约做防御:
- 完整进度日志:每一次 Sync 钩子输出「开始 / 结束 / 执行偏慢 / 失败」日志,通过 SailClient.Log 输出;卡死排查:日志只看到【开始】,没有对应【结束】,即可定位阻塞钩子。
- 钩子软超时 :FlowHookBase 配置默认 30s 软超时;不在执行中途打断,等待 Handle 返回之后检测耗时,如果超限抛出
FlowSyncHookTimeoutException,触发 FailFast 整体回滚。 - 即使 kit 不为 null,仍然强制打钩子 BEGIN/END 埋点日志。
- 契约评审:评审检查所有 Sync 钩子是否复用 kit;本期不引入 AsyncLocal 做运行时拦截,正确性依靠 API 重载 + 代码评审保障。
3.3 宿主钩子选型自检表
表格
| 业务场景 | 选型方案 |
|---|---|
| 需要读写本次事务还未提交的流程数据 | Sync 钩子,必须传入 ctx.Kit |
| 可以延后执行的副作用(推送消息、调用外部 http) | Async Outbox,事务内入队,提交之后消费 |
| 只做观测统计,不要求强一致 | Best‑Effort 日志;禁止使用 Sync 阻塞主流转路径 |
| Sync 钩子内部调用同步长 HTTP 请求 | 重构迁移到 Outbox 异步消费 |
IFlowHook接口 XML 注释已经补充死锁风险警示;开发自定义钩子、PR 评审务必对照。
4 加签运行时模型:席位 AI 子容器(Transition 内核)
产品篇中前 / 后 / 并加签完成初测,背后做了一次语义纠偏:
❌ 废弃旧方案:为加签新建虚拟节点空壳、直接改写节点原始 ai_leave_* 快照;子 AI Passed 直接 ContinueForward。
✅ 当前实现:原始节点 Leave 快照永远不变;SignForward 把发起人 AI 升级为容器席位,创建子规则 Leave;加签人员生成子 AI 实例。
执行流程简述:
- 节点创建 AI,保留原始设计的 ai_leave_* 快照,加签操作永不修改这份快照;
- SignForward(加签)将发起人的 AI 升级为容器席位,写入临时子 Leave 规则,新建子 AI 给加签办理人;
- 办理人办结,执行 TryCanLeave (容器席位);子 AI Passed 之后折合为发起人一票,再交给父层 TryCanLeave 判定;
- 如果同级其他 Task 直接通过,触发 Race 逻辑,递归淹没未完成加签子树。
同级节点判定分母 = 直属 Task ∪ 直属子 AI(折合席位)。
很多并加签 BUG 来源于宿主侧硬编码计数逻辑,忽略子 AI 折合席位;引擎层 Parallel 强制 Percentage=1,并且把发起人打开待办计入末席。
命令族区分:
SignForward(前 / 后 / 并加签,改变拓扑)归属 TransitionActionBase;AddAssignee(普通扁节点追加办理人,不产生子拓扑)归属 AssigneeActionBase ;
两者语义完全不同,禁止揉成一个 SignForwardType 参数。
核心锚点:NodeMediatorSignForward*、LeaveSeatProjector、TryCanLeave;详细契约看专题文档《节点实例临时子规则》。
5 本期刻意不做的边界
列出不做的能力,明确项目边界,避免预期偏差。
表格
| 本期不实现 | 原因 |
|---|---|
| Action 基类内置完整全家桶 Gate‑Hook 时序 | 三大族群执行模式有差异;工具箱不等于时序上帝 |
| 跨库 Saga 冒充同事务 | 首期仅保障引擎库关键路径一致性;跨库交给宿主 Saga |
| AsyncLocal 拦截禁止 UseRunSQL | 依靠 kit 重载 API + 评审,优先可观测日志方案 |
| 给 Handle 增加 CancellationToken | 改动破坏面大,优先落地软超时机制 |
| 使用工作线程强杀阻塞 SQL | kit 持有的事务连接不可跨线程释放 |
| 将 Copyto、选人管道合并进 Action 骨架 | 属于正交能力,强行合并只会膨胀 Context |
UseAction<T>注册表替代 new XxxAction |
接口保留可用,优先显式薄壳调用 |
6 仓库文档地图
表格
| 主题 | 仓库路径 |
|---|---|
| 动作骨架 | doc/sail/theme/专题-流转动作骨架.md · Actions/FlowActionBase.cs |
| 同事务信封 | doc/sail/theme/专题-事务一致性.md · Service/WorkflowService.ProcessExecution.cs |
| 钩子调度 | doc/sail/theme/Plugin/Hooks/FlowCapabilityDispatcher.cs |
| 自锁故障案例 | doc/sail/theme/专题-Bug治理-Sync钩子同事务自锁.md |
| 可观测 | doc/sail/theme/专题-钩子治理与同事务可观测.md |
| 加签子堆栈 | doc/sail/theme/专题-节点实例临时子规则.md |
| 事件教程 | doc/helps/教程-事件体系Gate-Hook-Notifier-Outbox.md |
| 迭代实施日记 | doc/sail/progress/2026-11-15-动作骨架-A1~A4-*.md |
写给准备提交 PR 的开发者
新增办理动词标准流程:
- 分析业务形态,选择 Assignee / Transition / Lifecycle 族群;新增族群需要同步修改专题文档;
- 业务子类只做上下文装载 + 实现 ExecuteCore;事务、锁全部交给外层 RunAction;
- 同步钩子访问引擎库,必须复用
ctx.Kit;允许延后执行的逻辑交给 Outbox; - 如果是加签类拓扑变更,厘清 Leave 规则生效在哪一层帧,禁止改写节点原始 Leave 快照;
- 本地日志切到 Debug 级别,跑通发起、办理全链路,确认 Sync 钩子「开始 / 结束」日志成对输出。
产品层面看到的初测全部绿灯,底层依赖这套动作骨架、事务信封、钩子自锁防护,避免半成功与闷锅死锁。
后记
后续可以继续深挖的方向:LeaveSeatProjector 加签 Leave 判定细节、Outbox Drain 副作用分层治理,欢迎在 Issue 提需求点菜。
MIT 开源,欢迎 Issue、PR 交流。