从入门到源码：LiteFlow 规则引擎完全指南

前言

在每个公司的系统中，总有一些承载着核心业务逻辑的模块，业务冗长、逻辑复杂，涉及内部运算、缓存操作、持久化、外部 RPC 调用等各方面。随着时间推移和需求迭代，代码中充斥着各种 if-else 硬编码，分支条件越来越多，模块之间的耦合度也越来越高。这时候，一款优秀的流程编排框架就显得尤为重要。

LiteFlow 就是一个为解决复杂业务逻辑解耦而生的国产编排式规则引擎。它诞生于 2020 年，目前已发展为拥有全新 DSL 规则表达式的轻量级框架，支持组件复用、同步/异步编排、动态编排、多语言脚本、热部署、平滑刷新规则等强大功能。本文将从入门、深入、源码三个层面，带你全面掌握 LiteFlow。

应用提示 ：如果你正在设计人为参与的审批流程（OA/工作流），LiteFlow 并不是合适的选择。

一、入门速通：十分钟掌握 LiteFlow 核心用法

1.1 设计理念：组件化与编排化

LiteFlow 的设计灵感来源于"工作台模式"------想象一个工作台周围围着一圈工人，每个工人只负责自己手中的零件生产，所有资源都从工作台（上下文）上取用，生产好的成品也放回工作台。工人之间互不干扰，调整工位（流程）时每个人无需改变任何东西。

映射到 LiteFlow 框架中：

• 工人 = 组件（Component）：每个业务逻辑片段
• 工位顺序 = 流程配置（Chain）：组件执行顺序
• 工作台 = 上下文（Context）：共享数据容器
• 最终成品 = 业务流程结果

这种设计的核心理念只有两点：

• 组件化：把业务逻辑切碎，每个组件只负责一件事
• 编排化：用规则文件来决定执行顺序，而不是硬编码

1.2 三个核心概念

在开始编码之前，你需要先理解这三个核心概念：

概念	说明	类比
Component（组件）	最小的执行单元，继承 NodeComponent，重写 process()	一个工人
Chain（流程链）	通过 EL 表达式定义组件执行顺序	工人的工位顺序
Context（上下文）	流程执行的共享数据容器，所有组件从中存取数据	工作台

EL 表达式是 LiteFlow 独创的语法，例如 THEN(a, b, c) 表示串行执行，WHEN(a, b, c) 表示并行执行。

1.3 快速上手：第一个 Spring Boot 示例

第一步：添加依赖

<dependency>
    <groupId>com.yomahub</groupId>
    <artifactId>liteflow-spring-boot-starter</artifactId>
    <version>2.15.3</version>
</dependency>

第二步：配置文件

liteflow:
  rule-source: flow/order-flow.el.xml

第三步：编写组件

@LiteflowComponent("checkStock")
public class CheckStockComponent extends NodeComponent {
    @Override
    public void process() {
        System.out.println("1. 校验库存");
        this.getContextBean(DefaultContext.class).setData("stock", "OK");
    }
}

@LiteflowComponent("calculatePrice")
public class CalculatePriceComponent extends NodeComponent {
    @Override
    public void process() {
        System.out.println("2. 计算价格");
        String stock = this.getContextBean(DefaultContext.class).getData("stock");
    }
}

第四步：定义规则文件 （flow/order-flow.el.xml）

<?xml version="1.0" encoding="UTF-8"?>
<flow>
    <chain name="orderChain">
        THEN(checkStock, calculatePrice);
    </chain>
</flow>

第五步：执行流程

@RestController
public class OrderController {
    @Autowired
    private FlowExecutor flowExecutor;

    @GetMapping("/test")
    public String test() {
        LiteflowResponse<DefaultContext> response = 
            flowExecutor.execute2Resp("orderChain");
        return response.isSuccess() ? "成功" : "失败";
    }
}

以上就是 LiteFlow 最基础的用法。可以看到，业务逻辑被拆分成独立的组件，执行顺序由规则文件统一管理。

二、深入进阶：掌握 LiteFlow 完整应用能力

2.1 核心关键词：流程编排的积木

LiteFlow 的 EL 表达式语法简单直观，你可以像搭积木一样组合流程：

• THEN ：串行执行组件。THEN(a, b, c) 表示 a → b → c 依次执行。
• WHEN ：并行执行组件。WHEN(a, b, c) 表示 a、b、c 同时执行。
• IF ：条件分支。IF(x, a, b) 表示根据组件 x 的执行结果选择 a 或 b。
• SWITCH ：多路选择。SWITCH(selector).TO(a, b, c).DEFAULT(y)。
• FOR / WHILE ：循环支持。FOR(5).DO(THEN(a, b)) 表示循环 5 次执行 a 和 b。
• AND / OR / NOT ：逻辑组合，IF( AND(condition1, condition2), a, b)。

更强大的是这些关键字可以随意组合嵌套：

<chain name="complexChain">
    THEN(a, WHEN(b, c, d), IF(x, e, f), SWITCH(selector).TO(g, h, i).DEFAULT(j));
</chain>

2.2 并行执行：WHEN 的四种等待策略

在实际业务中，WHEN 并行任务的处理远比"同时跑"复杂。LiteFlow 通过策略模式提供了四种精巧的并行策略：

策略	对应执行器	行为	使用方式
ALL	AllOfParallelExecutor	等待所有任务完成	默认行为
ANY	AnyOfParallelExecutor	任一完成即继续	添加 .any(true)
SPECIFY	SpecifyParallelExecutor	等待指定组件完成	添加 .must("id1", "id2")
IGNORE_ERROR	组合特性	忽略部分节点异常	添加 .ignoreError(true)

并行编排的执行器都基于策略模式实现，获取对应的执行器后，再通过 CompletableFuture 完成具体调度。底层使用 CompletableFuture.allOf() 实现全部等待，CompletableFuture.anyOf() 实现任一等待。

2.3 数据传递：上下文是唯一的数据总线

LiteFlow 中组件方法都是无参无返回值的，数据通过共享上下文来传递。组件之间通过 this.getContextBean() 存取数据，实现解耦。

@Component("producer")
public class ProducerComponent extends NodeComponent {
    @Override
    public void process() {
        OrderContext context = this.getContextBean(OrderContext.class);
        context.setResult("done");
    }
}

每个请求会产生独立的上下文对象，所有组件向其中读写数据后，流程结束时从响应中统一获取最终结果。这种设计消除了组件间的参数传递依赖，组件之间彻底解耦。

2.4 脚本组件：灵活动态的业务逻辑

LiteFlow 支持使用脚本语言定义组件，目前支持 Java、Groovy、Python、QLExpress、Lua、Aviator、Kotlin、JavaScript 8 种脚本语言。脚本组件支持运行时热刷新，修改后无需重启服务即可生效。

以 Python 为例（需要引入 liteflow-script-python 依赖）：

<node id="pythonCalc" name="价格计算" type="script" language="python">
    <![CDATA[
        base_price = orderContext.getBasePrice()
        discount = orderContext.getDiscount()
        final_price = base_price * (1 - discount)
        orderContext.setFinalPrice(final_price)
    ]]>
</node>

⚠️ Python 版本警告 ：LiteFlow 的 Python 支持依赖于 Jython ，而 Jython 目前仅能运行 Python 2.7 语法，不支持 Python 3。这意味着你无法使用 async/await、类型注解等现代 Python 特性，也无法引入 numpy、pandas、requests 等流行第三方库。如果你的业务对 Python 生态有强依赖，建议用 Java 组件封装，或将任务交给外部 Python 服务。

2.5 优雅的热刷新：业务变更零停机

LiteFlow 支持优雅平滑热刷新，即在不重启服务的情况下进行规则重载。高并发下刷新时，正在执行的流程线程完全平滑，不会因刷新过程而中断或出现错乱。

热刷新本质上是通过重新解析规则并更新内存中的元数据来实现的。使用 ZooKeeper 等配置中心作为规则源时，LiteFlow 原生支持自动热刷新，开发者只需修改配置中心的数据即可。

// 主动刷新单个脚本
LiteflowMetaOperator.reloadScript("myPythonScript", newScriptContent);

2.6 组件生命周期与高级特性

每个继承 NodeComponent 的组件都有丰富的生命周期钩子：

钩子方法	作用	应用场景
process()	核心业务逻辑（必须实现）	主要业务处理
isAccess()	是否允许执行	熔断、灰度判断
isContinueOnError()	出错是否继续	非核心任务容错
rollback()	失败后的业务回滚	补偿操作

框架的 SPI 机制保证了在各种运行时环境（Spring、Solon 等）下的兼容性。开发者可以通过实现特定接口来扩展框架功能，实现松耦合和模块化设计。

2.7 使用误区：为什么说 LiteFlow 不适合 OA 系统？

框架选型时一个常见误区是用 LiteFlow 来做审批流（OA 系统）。结论是：LiteFlow 并不适合，也不计划支持基于角色的审批流转。

设计定位的根本区别：

维度	LiteFlow	Flowable / Activiti
本质	无状态规则/逻辑编排引擎	有状态工作流引擎
数据持久化	不持久化流程状态	持久化流程实例、任务、变量
执行特点	单次请求内完成	可跨天、跨周，支持暂停/恢复
用户交互	不关心"人"的因素	支持待办任务、委派、代理人、会签
典型场景	订单处理、价格计算、数据清洗	请假审批、报销流程、合同盖章

人脑"流程" vs 机器"逻辑" ：OA 系统中的"提交→部门主管审批→财务审核→结束"是一个有状态的、多角色的长周期过程，需要等待人工介入 。LiteFlow 的设计初衷是高效编排一次性完成的自动化逻辑，它没有待办任务表，也无法持久化"当前审批到哪一步了"。

正确的工具选择 ：对于任何涉及多人、多角色、需持久化的审批/工作流场景，请选择 Flowable 、Activiti 或 Camunda 等专业工作流引擎。LiteFlow 可与它们配合使用------比如用 Flowable 驱动审批流程，而在审批通过后的自动化处理环节（如积分发放、库存扣减）调用 LiteFlow 编排的逻辑链。各司其职，才是优雅的架构。

三、源码剖析：深入 LiteFlow 核心实现

3.1 四大核心模块解析

LiteFlow 的核心架构由四个核心类紧密协作，共同构建了一个高效、灵活的流程执行引擎：

① FlowExecutor：流程执行的指挥官

FlowExecutor 是 LiteFlow 对外暴露的主要入口，承担两个核心职责。

• 框架初始化 ：Spring Boot 启动时，扫描并注册组件（initCmp()）、解析规则文件（parser.parseMain()）、初始化 DataBus 数据槽位、启动文件监听。
• 流程执行 ：execute2Resp() 被调用时，向 DataBus 申请 Slot、从 FlowBus 获取 Chain、执行流程、最后释放 Slot。

这里有个巧妙设计：LiteFlow 不直接传递庞大的 Context 对象，而是传递一个轻量级的 Integer 下标，组件需要数据时再拿下标去 DataBus 换取真正的 Slot，大大降低了参数传递开销。

② FlowBus：元数据的交通枢纽

FlowBus 是一个静态类，充当 LiteFlow 的"内存数据库"，维护两个核心 Map：

public class FlowBus {
    private static final Map<String, Chain> chainMap;   // 存储流程链
    private static final Map<String, Node> nodeMap;     // 存储节点组件
}

热刷新功能本质上就是重新解析规则并更新 FlowBus 中的这两个 Map。

③ DataBus：高性能的数据池化管理

DataBus 是 LiteFlow 高性能的关键设计。它内部维护了一个 Slot 池（默认 1024 个）：

• 结构：ConcurrentHashMap<Integer, Slot> 存数据 + ConcurrentLinkedQueue<Integer> 存空闲下标
• 申请：从 QUEUE 中 poll() 下标，没有则扩容（1.75 倍）
• 释放：QUEUE.add(index) 归还下标

这种池化设计避免了频繁创建和销毁 Context 对象，极大地降低了 GC 压力。

④ NodeComponent：业务组件的基类

所有业务组件都继承自 NodeComponent，内部有一个 self 属性------这是为了解决 Spring AOP 代理问题的精心设计。如果组件被代理了，this 指向原始对象，而 self 指向代理对象，确保切面能正确生效。

3.2 运行时完整执行流程

当一个流程被触发时，以下步骤依次执行：

1. 申请槽位：DataBus 分配一个空闲的 slotIndex
2. 获取流程链：从 FlowBus 的 chainMap 中获取 Chain 对象
3. 执行 Condition：Chain 按顺序执行内部的 Condition
4. 编排与分发：串行 Condition 直接调用；并行 Condition 触发异步调度
5. 执行组件：NodeExecutor 执行 process()，并插入前后置逻辑
6. 数据交换：组件通过 DataBus 读写 Slot 中的数据
7. 释放槽位：Slot 归还原，等待下次复用

并行调度底层使用了 CompletableFuture。AllOfParallelExecutor 获取所有并行任务列表后，通过 CompletableFuture.allOf() 把它们合成一个等待全部完成的任务，再统一处理结果。

3.3 监控扩展：实现自定义监控

LiteFlow 自带了简单的监控功能，统计每个组件的平均耗时并按倒序打印。这些数据来自对每个组件的前置时间记录，最终通过 MonitorBus 输出。

但内置监控是单机内存级别的。要对接 Prometheus 等监控系统，只需实现 MonitorBus 接口：

@Component
public class PrometheusMonitorBus implements MonitorBus {
    @Override
    public void record(Map<String, ComponentStatistics> statisticsMap) {
        for (Map.Entry<String, ComponentStatistics> stat : statisticsMap.entrySet()) {
            // 转换为 Prometheus 指标
            componentDurationHistogram
                .labels(stat.getKey())
                .observe(stat.getValue().getAverageTimeTaken());
        }
    }
}

通过 SPI 机制注册后，LiteFlow 会自动调用 record 方法。

总结

LiteFlow 通过组件化与编排化的设计哲学，让复杂的业务逻辑得以优雅解耦、灵活编排。从入门到进阶再到源码剖析，我们可以看到：

• 架构精巧：FlowExecutor + FlowBus + DataBus + NodeComponent 四核驱动，职责分明
• 高性能：Slot 池化设计，轻量级下标传递异步调度
• 灵活扩展：SPI 机制、脚本组件、多种规则源支持，适应各种业务场景
• 热刷新：规则变更零重启，业务响应更快
• 开放生态：支持多种 Java 框架和配置中心，易于集成

但也要注意框架的适用边界 ：LiteFlow 擅长一次性完成的自动化逻辑编排，对于需要持久化、人工参与的审批流程（如 OA 系统），应选择 Flowable 等专业工作流引擎。只有正确选型，才能让每一款工具在合适的场景下发挥最大价值。

如果你正被复杂业务逻辑的解耦与维护问题所困扰，LiteFlow 绝对是一个值得一试的高效利器。