Geng Flow 使用文档

Geng Flow 是一个纯 Rust、以有向图为核心的异步流程编排框架。它面向需要明确控制流、可靠状态和可恢复执行的业务系统，让短任务、跨服务编排和跨天人工流程使用同一套模型。

从流程定义到生产运行，框架始终围绕一张可校验、可执行、可持久化的图工作。业务代码专注领域能力，运行时负责调度与状态推进。

为什么选择 Geng Flow

企业流程的复杂度通常不在“按顺序调用几个方法”，而在分支、并行、等待、失败恢复和长期演进。Geng Flow 将这些问题收敛为稳定的框架能力。

核心价值	能力说明	适用收益
图原生建模	节点、边、条件、子图和循环使用统一模型	复杂控制流保持可读、可检查
编译后执行	定义先经过规范化、引用解析与静态校验	配置错误尽可能在运行前暴露
状态可恢复	Token、变量、等待、重试和补偿状态可序列化	进程重启后从安全位置继续
确定性并行	分支隔离、并发执行、稳定提交与汇聚	同时兼顾吞吐量和可重现性
Rust 原生扩展	通过 Trait 注册 Service、Handler、条件和存储	类型安全、无反射、易于测试
可靠执行闭环	幂等、乐观锁、Lease、Outbox、死信和补偿	面向网络抖动与部分失败设计

核心执行链路

JSON / YAML / Rust Builder
            │
            ▼
      GraphSpec 流程定义
            │  规范化 · 引用解析 · 静态校验
            ▼
    CompiledGraph 不可变执行图
            │
            ▼
       Engine + Driver
            │  调度节点 · 推进 Token · 合并变量
            ▼
       FlowInstance
            │
      ┌─────┼──────────┐
      ▼     ▼          ▼
    完成   等待       执行失败
           │          │
           ▼          ├─ 重试 / 死信
       Signal 恢复    └─ 逆序补偿

定义层与运行层明确隔离：GraphSpec 适合编辑和交换，CompiledGraph 面向高效执行，FlowInstance 只保存某一次运行的动态状态。

企业级能力矩阵

流程建模

• 线性串联、条件路由、排他与包容分支
• Fork/Join 并行、集合循环和内联子图
• 节点输入输出映射、流程变量和执行上下文
• JSON、YAML 与 Rust Builder 多种定义方式
• 编译期拓扑检查、引用检查和可达性校验

业务集成

• 类似应用 Service 的方法注册与调用
• 自定义节点 Handler、条件求值器和拦截器
• Rhai 脚本执行以及脚本能力白名单
• HTTP、SQL、消息队列等连接器扩展
• 同步业务方法与异步外部系统的统一适配

长流程与人工任务

• Signal 等待、定时等待和外部回调恢复
• 流程快照、版本号和乐观并发控制
• 人工任务认领、会签、或签、委托与退回
• 超时、升级、加签和候选人规则
• 文件、内存、SQLite 与 PostgreSQL 存储适配

可靠性与治理

• 节点级重试、退避策略和失败分类
• 幂等键、Lease 租约和异常实例接管
• Saga 补偿栈与副作用逆序回滚
• Outbox 可靠事件交付和死信处理
• 生命周期事件、指标、追踪和模拟测试

能力边界

Geng Flow 负责流程控制、运行状态和可靠性机制；订单、支付、用户、表单等领域逻辑仍由你的 Service 或 Handler 提供。框架不会侵入业务模型。

典型应用场景

场景	示例拓扑	重点能力
电商履约	风控 → 库存/支付并行 → 配送 → 通知	并行、幂等、补偿
企业审批	申请 → 部门会签 → 财务审批 → 执行	人工任务、等待、超时
微服务编排	Service → HTTP → 等待回调 → 恢复	外部调用、Signal、持久化
数据处理	数据拆分 → 有限并发 → 结果汇聚	循环、并发限制、Join
长事务 Saga	正向步骤 → 局部失败 → 逆序补偿	补偿栈、重试、审计
事件驱动流程	消费事件 → 状态变更 → Outbox 发布	可靠消息、去重、恢复
AI Agent 流程	模型 → 工具并行 → 人工确认 → 输出	上下文、分支、人工介入

最小接入模型

业务系统通常只需要完成四件事：加载定义、注册能力、创建实例、驱动执行。

// 加载并编译流程图，生产环境可以替换为数据库定义仓库
let source = std::fs::read_to_string("flows/order.json")?;
let spec = GraphSpec::from_json_strict(&source)?;
let graph = compile(spec)?;

// 将现有领域服务注册到运行时，不需要把业务逻辑写进流程框架
let mut registry = HandlerRegistry::new();
registry.register("order.reserve", ReserveInventoryService::new(inventory));
registry.register("payment.capture", CapturePaymentService::new(payment));

// 每次业务请求对应一个独立流程实例
let mut instance = engine.create_instance(&graph, variables);
let outcome = engine
    .run(&graph, &mut instance, RunOptions::default())
    .await?;

当结果为等待状态时，保存实例快照；收到审批、回调或定时事件后，通过实例 ID 和 Signal 恢复执行。

架构分层

┌──────────────────────────────────────────────────────┐
│ 接入层：JSON / YAML / Builder / Service / Script     │
├──────────────────────────────────────────────────────┤
│ 定义层：GraphSpec / Loader / Rule Loader / Compiler  │
├──────────────────────────────────────────────────────┤
│ 运行层：Engine / Driver / Registry / Interceptor     │
├──────────────────────────────────────────────────────┤
│ 能力层：Workflow / Scheduler / Connectors / Events   │
├──────────────────────────────────────────────────────┤
│ 基础设施：Storage / Observe / Simulator / Testing    │
└──────────────────────────────────────────────────────┘

这种分层让核心运行时不依赖具体数据库、Web 框架或脚本引擎。应用可以从内存模式开始，再按生产需求组合持久化、调度、观测和连接器模块。

推荐阅读路径

第一次接入

1. 快速开始：运行最小流程并理解实例结果。
2. 图模型：掌握节点、边、条件和任务。
3. JSON 与 YAML：从外部定义加载并编译流程。
4. Service 与脚本：调用已有 Rust 业务方法。

进入生产设计

1. 核心架构：理解模块边界和执行状态机。
2. 分支、并行与循环：设计复杂拓扑。
3. 等待与持久化：处理跨进程、跨时间流程。
4. 可靠执行：设计重试、幂等、死信与补偿。

需要人工协作

1. 人工工作流：认领、会签、委托和期限管理。
2. 完整示例：从可运行示例理解组合方式。
3. 开发路线：确认当前成熟度和后续规划。

设计原则

• 定义与实例分离：流程版本可以演进，已运行实例仍保持明确归属。
• 编排与业务分离：框架安排“何时调用”，Service 决定“业务做什么”。
• 状态显式化：等待、失败、重试和补偿都是可持久化状态，不依赖线程驻留。
• 副作用可治理：外部调用必须考虑幂等、超时、重试边界和补偿语义。
• 扩展点小而稳定：通过 Trait 组合能力，避免核心运行时与基础设施耦合。

从这里开始

如果你已经有 Rust 项目，直接进入快速开始。如果正在做技术选型，建议先阅读核心架构和可靠执行。