这几年在折腾后端服务的时候我越来越觉得很多逻辑本质上都是在处理同一件事根据一堆条件决定一条数据接下来往哪儿走。不管是订单状态流转、工单分配、消息推送还是风控里那一长串“如果...就...”的判断写到最后都容易变成一团乱麻——if套elseswitch里再嵌switch全局搜一个判断条件能搜出十几个地方要一起改。我试过用规则引擎像是 Drools 这种功能是真的强但引入一套重引擎的成本也真的高规则文件语法、IDE 插件、部署方式都得跟着变团队的学习曲线一下子就拉起来了。后来我就想能不能自己写一个足够轻、足够直观、但又真的能扛住业务压力的路由判断组件于是就有了ruflo这个项目。ruflo 这个名字来自 “rule flow” 的简写定位很简单一个轻量级的规则流路由引擎。它不追求像 Drools 那样把所有知识库、推理机、工作内存都塞进来它只做一件事——把分散在代码各个角落的“条件→动作”逻辑统一收拢成一份清晰、可配置、可观测的规则集合然后用一个极简的引擎去执行它们。这篇文章我就把这个项目的设计思路、核心实现、落地细节和踩坑记录完整分享一下。这个项目适合谁看如果你正在维护一个业务规则经常变化、判断分支越来越多的后端服务或者你早就受够了那坨怎么重构都还是有味道的条件代码又或者你纯粹是想看看一个轻量级规则引擎是怎么从零设计出来的那这篇内容应该对你有帮助。我会把核心的抽象、数据结构、执行流程都讲透并且给出可以直接抄走的代码骨架。1. 项目整体设计与思路拆解1.1 需求收敛到底要解决什么问题我决定写 ruflo 之前先把自己手上服务里那些最让人头疼的判断逻辑梳理了一遍。反复出现的基本是这三类多条规则按优先级依次命中比如优惠计算先判断是否新人、再判断是否会员、再判断是否有定向券命中第一个就停止后续判断。一条数据要经过多个阶段处理比如工单创建后先自动分派、再发通知、再更新统计每个阶段都有独立的条件判断。规则需要随时调整但不想频繁发版产品说这个活动门槛从 100 改成 80最好改个配置就能生效而不是改代码、走发布流程。这三类需求有个共同点条件表达式的结构其实都不复杂复杂的只是条件和动作之间的组合关系。我真正需要的是把这种组合关系显式地建模出来而不是让它散落在一堆if语句里。所以 ruflo 的核心抽象最终收敛成三样东西Rule规则包含一个命中条件和一组动作列表。Flow流程一组有序规则的集合定义了按照什么顺序去匹配这些规则。Context上下文在整条流程里流转的数据载体规则基于它做判断动作基于它做变更。这个模型非常简单我相信任何有过业务开发经验的人看一遍就能在脑子里建立画面。而这恰恰是它最大的优势——团队协作时沟通成本才是最大的隐性成本。1.2 选型对比为什么没有直接用现成的规则引擎在动手写之前我也认真对比过市面上主流的方案这里把当时的思考完整记录下来。首先看Drools。它是 Java 生态里事实上的规则引擎标准支持复杂的 forward/backward chaining、truth maintenance、temporal reasoning 这些重型特性规则文件用 DRL 语法编写。问题是我们 90% 的实际场景用到的能力不到它的 5%却要为了这 5% 的能力背上完整的运行时开销和语法学习成本。DRL 语法对大多数业务开发同学来说并不友好IDE 提示也一般新版有改进但依然不算顺滑出了问题排查链路还长——规则引擎内部自己有一套 rete 网络执行逻辑跟业务代码之间隔着一层。再看Easy Rules。这个库确实轻量理念也很接近我的想法——用 POJO 定义规则、用注解声明条件。但它提供的主要还是单条规则的执行能力对于流程编排、规则的动态加载与热更新、完整的可观测性它给的是接口而不是内置实现需要我额外去补很多胶水代码而且规则之间的依赖关系在代码里仍然不够直观。至于Aviator / Groovy 表达式引擎这类东西它们解决的是表达式求值问题核心能力是把一个字符串表达式的计算结果算出来。但表达式引擎管不了完整的流程路由该有if-else的地方还是得有只是把判断条件换成了字符串——并没有根治代码结构的问题只是把乱从 Java 代码换成了字符串。ruflo 的差异化定位很清楚不做全功能的规则引擎只做流程化的条件路由。它刻意放弃了对复杂规则网络的支持换来了三个东西——学习成本几乎为零、执行路径完全透明、规则可以任意编排和热更新。这正好踩中了我在实际业务里感受到的最大痛点。1.3 架构分层ruflo 的整体模块划分ruflo 从代码结构上分为四层每一层各司其职下面把每层的职责和设计思路拆开讲。表达式层Expression Layer负责条件表达式的解析和求值。表达式以 JSON 结构描述解析后生成对外统一的条件求值接口Condition然后由具体实现去执行判断。这一层保证了上层完全不必关心条件是用什么语法写的——是 EQ、IN、RANGE 还是自定义函数通通屏蔽掉。规则层Rule Layer负责把一条规则的完整生命周期管理起来包括规则的创建、命中判断、动作执行、结果记录。一条规则内部有 id、name、priority、condition 和 actions 五个核心属性。这一层不关心规则在整个流程里处于什么位置它只保证我在该判断的时候判断该执行的时候执行执行结果完整记录下来。流程层Flow Layer负责规则的编排。流程在启动时会把自己包含的所有规则按优先级排序、建立索引然后按照设定的策略首个命中或全部执行逐条驱动。这一层还负责上下文的管理和传递保证一个流程执行下来用的始终是同一个上下文实例。最后是运行时层Runtime Layer它把对外的一切能力暴露出去——规则的加载从本地文件、数据库、远程配置中心、缓存管理、动态刷新、执行监控和指标埋点。应用接入时只需要面向 runtime 编程不需要依赖上面任何一层具体的类。这四层设计有一个直接的好处想替换掉任何一种实现影响的仅仅是一层。比如接入方读规则不想用我提供的 JSON loader自己写个读数据库的 loader 也完全没问题——因为接口都是独立的。1.4 规则模型设计JSON 即 DSLruflo 最终把规则文件设计成了纯 JSON 结构。这个设计决策当时有人觉得是不是太简陋了可实际用下来我发现它反而是项目里口碑最好的部分。一个最简规则定义长这样{ rules: [ { id: member-rule, name: 会员用户自动打标, priority: 1, when: { all: [ { field: user.level, operator: GTE, value: 2 }, { field: user.status, operator: EQ, value: ACTIVE } ] }, then: [ { action: user.tag, params: { tag: VIP } } ] } ] }之所以坚持用 JSON 而不是设计一套专有的 DSL原因很朴素JSON 是通用标准学习成本为零任何语言任何工具链都能解析结构化的数据天然适合做可视化展示——把这份 JSON 丢给一个简单的 Web 页面马上就能渲染成一张可视化规则树最重要的是它可以轻松实现动态修改——规则存在数据库里运营配置后台改完引擎拉取最新版本就生效。字段说明如下字段类型含义idstring规则的唯一标识流程内不允许重复namestring规则的可读名称日志和监控里展示用priorityint优先级数值小的先执行whenobject命中条件支持 AND / OR / NOT 嵌套组合thenarray命中的动作列表按数组顺序依次执行when在这里支持三种组合结构——all、any、not分别是逻辑与、逻辑或和取反。它们可以任意嵌套这样条件组合的表达能力其实完全不输传统代码里的布尔运算符组合只是用了更规整的树形结构来表达。1.5 执行引擎核心机制从条件到动作再到流程控制有了规则模型引擎的执行机制就顺理成章了。整个执行过程分三步条件求值阶段从规则的when结构出发构建一棵条件树。树的叶子节点是原子条件字段、操作符、值的三元组非叶子节点是逻辑组合节点。求值的时候递归遍历这棵树每个节点返回一个布尔值根节点的结果就是整条规则的命中结果。动作执行阶段命中之后引擎遍历规则的then数组逐个调用动作执行器。动作执行器的实现方式是基于策略模式——把动作类型字符串映射到对应的执行方法天然方便做扩展、测试和替换。流程编排阶段引擎持有一组规则通过策略控制流转。默认策略是首个命中即停止也就是按优先级依次判断一旦某条规则命中就执行并结束整条流程还有一个全部命中策略会按顺序执行所有命中的规则。这两种策略基本覆盖了业务里绝大多数场景。执行完成后引擎返回一个FlowResult对象里面包含整个执行过程的完整信息最终命中了几条规则、每条规则的命中状态、执行耗时、动作执行结果和可能的异常信息。这些数据就是可观测性的根基——业务出问题了直接翻这个结果对象就能知道到底哪条规则命中、哪个动作执行失败、花了多长时间。2. 核心细节解析与实操要点2.1 原子条件求值字段路径与操作符解析规则条件的最小单元是{ field: user.level, operator: GTE, value: 2 }这个三元组背后的实现机制是整个条件系统最基础的部分。字段路径解析我实现了一个极简的属性解析器支持点号路径访问。它会处理三种情况普通 Map 的直接获取、对象的反射获取适配一些上下文里放 POJO 的场景、以及 List / 数组的下标访问比如order.items[0].price。整体实现逻辑短小但很实用。操作符定义我预置了一份操作符集用枚举定义包括 EQ等于、NEQ不等于、GT / GTE / LT / LTE大小比较、IN / NOT_IN集合包含、CONTAINS字符串包含、BETWEEN区间判断、STARTS_WITH / ENDS_WITH、IS_NULL / NOT_NULL、REGEX正则匹配等等。每一个操作符都实现同一个函数式接口入参是实际值和预期值出参是布尔结果。类型安全这一点非常关键。条件里声明的 value 从 JSON 解析出来时在数字场景会有基础类型的不确定性整数、浮点、精度。如果不做类型归一化直接比较会出现2 1返回 false 这种诡异问题。踩过一次坑之后我在操作符执行之前加入了类型归一化逻辑统一把数字类型转成 BigDecimal 再比较彻底解决了数字比较的精度和类型问题。原子条件的求值接口定义如下这里面resolveFieldValue负责从上下文中按路径取值compareValue负责按操作符比较public interface Condition { boolean evaluate(EvalContext context); }每个原子条件都是一个Condition实例逻辑组合节点AllCondition、AnyCondition、NotCondition也都实现这个接口这样在求值时上层完全不需要关心节点类型直接递归调用evaluate就行。2.2 动作抽象与扩展机制策略模式下如何灵活对接业务动作动作系统是 ruflo 里扩展性要求最高的一个模块。业务方接入之后肯定会不断往里面加自己的动作——发消息、写库、调 API、更新状态什么都有。如果每加一个动作就要改引擎代码那就说明抽象设计有问题。我采用的是注册表模式的策略设计。动作执行器统一实现ActionExecutor接口每个执行器声明自己处理什么动作类型然后在 ruflo 启动时注册到动作注册表里。引擎执行动作时先按动作类型从注册表查出对应的执行器再调用执行。接口定义简化为这样public interface ActionExecutor { String type(); ActionResult execute(String ruleId, MapString, Object params, EvalContext context); }type()返回动作类型比如user.tag、order.updateStatus。execute做真正的业务处理。这种方式带来了一个额外的好处动作可以像插件一样装配。基础动作引擎内置业务动作由接入方自己实现自己注册双方互不干扰测试时也可以只针对单独的执行器做单元测试。讲到这还得补充一句动作执行器里不要做耗时不可控的操作。规则引擎的定位是轻量路由判断如果动作里有外部 API 调用建议通过异步消息丢给下游处理而不是在 ruflo 的执行链路里同步等待。否则一个慢接口会把整条规则流程拖死失去了引擎本身轻快的定位。2.3 流程定义与加载一个完整的 Flow 配置长什么样实际项目中肯定是多条规则组成一条流程。流程配置的结构我设计成下面这个样子整体上是一个包含元信息、变量声明和规则列表的树{ flowId: order-dispatch-flow, name: 订单分派流程, description: 新订单自动分派给对应处理小组, mode: first_match, variables: { maxDispatchAttempts: 3 }, rules: [ { id: rule-1, name: 高优客户优先分派, priority: 1, when: { any: [ { field: order.customerLevel, operator: EQ, value: PLATINUM }, { field: order.customerLevel, operator: EQ, value: GOLD } ] }, then: [ { action: dispatch.assign, params: { group: priority-group } }, { action: dispatch.notify, params: { channel: sms } } ] }, { id: rule-2, name: 普通客户按地域分派, priority: 2, when: { all: [ { field: order.region, operator: IN, value: [NORTH, SOUTH] } ] }, then: [ { action: dispatch.assign, params: { group: normal-group } } ] }, { id: rule-default, name: 兜底规则, priority: 999, when: { not: { any: [ { field: order.groupAssigned, operator: EQ, value: true } ] } }, then: [ { action: dispatch.assign, params: { group: default-group } } ] } ] }这份配置里有两个值得注意的设计点。一个是mode字段它声明了流程执行策略。first_match是首个命中即停止all_match是全部命中都执行。个别场景还需要失败中止策略后续我通过扩展支持了fail_fast允许配置规则执行出异常时是终止整条流程还是记录后继续。另一个是variables段它可以声明一些流程级的公共变量。实际使用时我会用它来暴露一些调参入口比如循环次数上限、超时时间这些可能经常需要调整的值放到流程配置里让运维改起来方便而不是写死在代码里。2.4 上下文对象设计与传递状态隔离与数据流向Context上下文在 ruflo 里承担两个职责一是存放业务数据让规则和动作都能读取二是记录执行过程数据比如哪些规则命中了、执行状态如何、有没有抛异常。这两个职责混在一个对象里容易乱所以我把上下文拆成两层EvalContext求值上下文只读业务数据提供给条件表达式求值。数据源是所有规则共享的同一个数据容器。FlowResult结果对象存储执行结果信息规则命中状态、动作执行结果、耗时、异常等全部落在这个对象里供调用方检查。上下文传递遵循一个原则整条流程共用一个 EvalContext规则动作对它的修改对后续规则可见。这一点很关键比如规则一给order.groupAssigned赋值为 true规则二读取时就能看到这个变化从而跳过执行实现规则间通过数据协作的效果。这种设计天然支持了规则之间的依赖。虽然我前面说规则之间不直接互相依赖但通过修改上下文的共享数据间接的依赖关系是可以表达的这是实际使用中非常顺滑的一个特性。3. 实操过程与核心环节实现3.1 环境准备与项目骨架搭建ruflo 的核心代码我用了 Java 11 实现构建工具用 Maven。选 Java 而不是其他语言主要考虑到我所在团队的技术栈和后续接入 Java 服务的便利性。项目本身的模块结构是这个样子的ruflo ├── ruflo-api -- 对外暴露的接口与核心模型 ├── ruflo-core -- 引擎核心条件求值、动作执行、流程编排 ├── ruflo-json-loader -- 基于 Jackson 的规则配置加载器 ├── ruflo-spring-boot -- Spring Boot 自动配置封装 └── ruflo-demo -- 可运行的示例工程搭建骨架时我把模块拆分得很早。一开始很多人劝我别上来就分模块说单模块跑通了再拆也不迟。但在这种要给别人当 SDK 用的项目里模块边界越早清晰后面迭代就越省心。接入方只依赖ruflo-api就够了完全不用暴露核心实现细节升级引擎也不会破坏接口兼容性。3.2 核心接口与模型定义代码骨架逐段解析模型类不多我把最核心的几个贴出来并逐段解释。这是理解 ruflo 代码结构最好的路径。条件树节点的核心接口和实现如下public interface Condition { boolean evaluate(EvalContext context); } // 逻辑与所有子条件都满足才返回 true public class AllCondition implements Condition { private final ListCondition conditions; public AllCondition(ListCondition conditions) { this.conditions conditions; } Override public boolean evaluate(EvalContext context) { if (conditions null || conditions.isEmpty()) { return true; } for (Condition condition : conditions) { if (!condition.evaluate(context)) { return false; } } return true; } } // 逻辑或任一子条件满足即返回 true public class AnyCondition implements Condition { private final ListCondition conditions; public AnyCondition(ListCondition conditions) { this.conditions conditions; } Override public boolean evaluate(EvalContext context) { if (conditions null || conditions.isEmpty()) { return true; } for (Condition condition : conditions) { if (condition.evaluate(context)) { return true; } } return false; } }这里有一个容易被忽视的点子条件为空时的返回策略。我统一选择返回 true。理由是业务配置里如果一个all块下面一个条件都没填说明配置方是想无条件通过这种场景在动态配置时很常见——先在 JSON 里留一个空结构后续再往里填条件。流程执行器是核心中的核心public class FlowExecutor { private final MapString, Condition compiledRuleConditions; private final MapString, ListActionCall compiledRuleActions; private final ListRuleDefinition sortedRules; private final FlowMode mode; public FlowResult execute(EvalContext context) { FlowResult result new FlowResult(context); for (RuleDefinition rule : sortedRules) { Condition condition compiledRuleConditions.get(rule.getId()); boolean matched condition.evaluate(context); result.addRuleResult(rule.getId(), matched); if (!matched) { continue; } if (mode FlowMode.FIRST_MATCH) { executeActions(rule.getId(), context, result); result.stop(); break; } executeActions(rule.getId(), context, result); } return result; } }执行顺序依赖于sortedRules在加载流程时就被按优先级排好序。条件求值和动作执行都是预先编译好的执行时不解析任何 JSON保证运行时的高效。这里我特意把规则求值和动作执行拆成独立方法是为了让单测能分别覆盖两条链路。3.3 解析器实现从 JSON 到可执行条件树的映射条件树的构建是一个典型的递归下降过程。我写了一个ConditionParser输入是 JSON 节点输出是条件树。核心逻辑如下public Condition parse(JsonNode whenNode) { if (whenNode.has(all)) { ListCondition conditions new ArrayList(); for (JsonNode child : whenNode.get(all)) { conditions.add(parse(child)); } return new AllCondition(conditions); } if (whenNode.has(any)) { ListCondition conditions new ArrayList(); for (JsonNode child : whenNode.get(any)) { conditions.add(parse(child)); } return new AnyCondition(conditions); } if (whenNode.has(not)) { return new NotCondition(parse(whenNode.get(not))); } return parseAtomicCondition(whenNode); }每一层递归都往树深处走一层直到叶子节点的原子条件解析。这样无论配置嵌套多深解析过程都是稳定、可预测的。为了让解析失败时能快速定位问题我在解析器里加了详细的错误信息——哪条规则、哪个字段路径解析失败、期望什么类型、实际是什么类型这些信息全部拼到异常消息里。3.4 一个完整的接入示例从流程配置到业务代码调用动手实践的部分来了我用一个订单自动分派的场景演示完整的接入流程。这个场景很典型新订单创建后需要根据订单属性自动决定分派给哪个小组处理。服务里直接调用 ruflo 的流程执行器RestController public class OrderController { private final FlowRuntime flowRuntime; public OrderController(FlowRuntime flowRuntime) { this.flowRuntime flowRuntime; } PostMapping(/orders) public OrderVO createOrder(RequestBody CreateOrderRequest request) { // 1. 构建业务数据 MapString, Object data new HashMap(); data.put(order.id, request.getOrderId()); data.put(order.amount, request.getAmount()); data.put(order.region, request.getRegion()); data.put(order.customerLevel, request.getCustomerLevel()); data.put(order.groupAssigned, false); // 2. 构建求值上下文 EvalContext context new EvalContext(data); // 3. 执行订单分派流程 FlowResult result flowRuntime.execute(order-dispatch-flow, context); // 4. 根据执行结果做后续业务处理 String assignedGroup (String) context.get(order.assignedGroup); log.info(订单 {} 分派完成命中规则 {}耗时 {}ms, request.getOrderId(), result.getMatchedRuleIds(), result.getCostMs()); return OrderVO.of(request, assignedGroup); } }接入方的代码量就是这么多。业务逻辑里不需要写任何一条if判断所有的条件分支全在流程配置里表达。业务的同事如果需要调整分派规则改配置就行不用动一行代码。3.5 动态刷新如何在不停机的情况下让规则变更立即生效规则配置如果只能写在本地文件里那基本等于没有解决动态调整这个核心诉求。所以我给 ruflo 加了一个轻量的动态刷新机制版本号 轮询加载。具体实现思路是在流程配置里增加一个version字段。接入方启动一个定时任务默认 30 秒轮询一次每次拉取最新配置后比对 version发现变化就触发流程实例的重建——解析新配置、编译条件树、更新内存中的执行器。整个过程对调用方完全透明不需要重启进程不需要重新发布。代码实现很简洁核心就是一个版本比较和实例重建public void refreshIfNeeded(String flowId, String latestConfig, long latestVersion) { FlowHolder holder flowRegistry.get(flowId); if (holder null || holder.getVersion() latestVersion) { FlowDefinition definition parseAndCompile(latestConfig); flowRegistry.put(flowId, new FlowHolder(latestVersion, definition)); } }这里有一个实践上的重要经验配置变更一定要保证原子性。曾经出现过一次线上事故我尝试在同一个流程里同时新增一条规则和修改一条规则两个操作先后推送到配置中心中间有一个短暂的中间态。结果刚好有请求在中间态时拉取了配置导致解析失败。后来我加了一个先完整发布、后原子切换的机制彻底解决了这个问题。3.6 性能评估执行耗时与调优记录一个轻量级规则引擎性能数据必须拿得出手。我在一个 2 核 4G 的容器里做了一个简单的基准测试模拟典型的10 条规则、每条 3 个原子条件、首条规则命中场景。测试结果是平均单次执行耗时在 0.5ms 左右P99 不到 1.2ms内存占用也很稳定没有明显波动。这个性能对我来说完全够用——在大多数业务请求链路里0.5ms 只占整个请求耗时的一个零头。性能之所以能压到这个水平主要靠三件事编译期解析流程加载时就把 JSON 解析成 Condition 树运行时不再做任何配置解析。索引直查字段路径在解析时就生成索引映射求值时直接按索引取数不再做字符串解析。共享受上下文字段池频繁访问的字段用线程安全的局部缓存避免重复的 Map 查找。如果遇到更大的规则量比如单流程超过 50 条规则建议在引擎层增加一层分组合并把同优先级的规则合并成组组间执行首个命中策略组内执行全部执行策略这样可以大幅减少被判断的规则数量。4. 常见问题与排查技巧实录4.1 规则始终不命中条件值类型与路径问题这个问题在接入初期出现频率最高。现象很典型配置看起来完全正确但规则就是不命中怎么调都不生效。排查思路可以按照下面的方向依次推进确认字段路径正确性。比如上下文里放的是user.level但是配置里写成了user.levels一个字母之差就永远取不到值。我在加载器里加了路径校验加载阶段提前暴露问题避免运行时才发现。确认类型一致性。JSON 解析后的数字是Integer还是Long跟操作符里声明的是否匹配实际执行时很容易出现类型不一致导致的误判。确认 evaluate 的递归逻辑。嵌套的all、any如果搭配不当逻辑上很容易出现看起来该命中但实际不命中的情况建议在配置里先简化成一个条件验证基础能力再从简单到复杂逐步叠加。我给 ruflo 加了一个诊断模式开启后可以把条件树里每个节点的计算过程打印出来——从哪个字段取了什么值、跟期望值比较的结果是什么——逐层显示。这个功能调规则的时候特别有用基本能省去 70% 的无效排查时间。4.2 流程执行异常动作执行器报错时的处理策略动作执行器是业务代码报错是不可避免的。关键是报错之后流程怎么走。我最后采用了双模式配置FAIL_IGNORE默认模式某个动作执行失败时记录异常到FlowResult继续执行下一个动作和后续规则。FAIL_FAST严格模式某个动作失败时立即中止整条流程后续规则不再执行调用方拿到的是带异常的结果对象。两种模式各有适用场景。比如发通知这种非核心链路用 FAIL_IGNORE 比较合适——通知挂了不能影响主流程但如果是扣库存这种核心动作那就必须用 FAIL_FAST——后面依赖库存结果的逻辑不能继续跑。另外很重要的一点是动作执行器方法体里要注意上下文的数据一致性。如果动作 A 修改了上下文字段后续动作读取到的是修改后的值这本来是我们想要的效果但如果动作 A 修改失败了还留下一个半改状态后面就全乱了。所以涉及多字段联动变更时建议在新对象上构建好数据后一次性放回上下文而不是逐个字段覆盖。4.3 动态刷新生效不及时版本号与缓存策略导致的问题动态刷新上线后有一个问题反复出现规则配置在后台已经改了但流程执行时用的还是旧版本好几分钟后才生效。查下来的原因有两个层面。一是轮询间隔设置太长。默认 30 秒一轮如果不追求秒级生效这个值其实是够的但如果你确实需要秒级生效建议把轮询改短到 5 秒或者直接对接配置中心的推送机制如 Nacos 的监听回调、Apollo 的 ChangeListener用事件驱动代替轮询。二是我踩过的一个隐蔽问题缓存了旧版本的 FlowResult结果缓存。在一些高频查询场景里我给流程执行结果加了短时缓存本意是减少重复求值但规则更新后缓存没及时清理导致旧结果被反复返回。问题出在缓存 key 只包含 flowId没包含 version。修复方案是在 key 里拼接 version这样规则一更新缓存自动失效。4.4 排查技巧快速定位问题规则的三板斧积累的排障经验总结下来就三板斧。第一板斧是每次执行后必须看 FlowResult。我在内部推动过一个规矩——所有接入 ruflo 的服务执行完后必须把 FlowResult或者至少把 matchedRuleIds 和 ruleResults打印到业务日志里。这样一旦业务异常翻日志就能看到是哪条规则的锅不用盲猜。第二板斧是提供诊断模式。通过一个开关让流程执行时把所有条件求值明细都输出出来。生产环境我默认关闭排查问题时临时打开完事再关。第三板斧是规则配置的完整版本历史。动态配置系统里每次变更都留下历史版本一旦出了问题可以一键回滚到上一个稳定版本并能直观对比版本差异。这个机制救过我好几次。4.5 常见问题速查表问题现象可能原因解决方案规则不命中字段路径写错开启诊断模式逐层打印求值过程数字比较结果异常JSON 数字类型与预期不一致统一用 BigDecimal 归一化后再比较动作执行失败但无感知默认失败忽略模式根据业务重要性按需切换为 FAIL_FAST配置已修改但不生效轮询间隔未到 / 版本缓存缩短轮询间隔或接入配置中心推送缓存返回旧结果缓存 key 未包含 version缓存 key 拼接版本号更新即失效加载流程时解析失败规则配置里类型错误完善配置校验启动时预加载检查5. 一些想对使用者说的话我们如何用好规则引擎5.1 设计原则什么时候适合用 ruflo什么时候不适合任何事情都有边界。ruflo 适合下面这些场景规则经常变每次变更都要发版的场景。比如营销活动的门槛调整、风控规则参数的动态配置通过 ruflo 改个配置就能生效。分支判断多逻辑分散在不同模块难以统一管理的场景。把规则集中看管起来以后什么时候改规则、改了什么、影响哪些流程一目了然。希望业务和开发之间能够用同一份规则语言沟通的场景。JSON 规则配置就是活的文档业务看得懂、开发也看得懂。但有些场景我明确不建议用它流程分支极少就两三个 if且基本不变这种用 ruflo 属于大炮打蚊子。需要复杂的规则推理比如规则之间有复杂的依赖链、需要回溯、需要基于历史判断这些这类需求建议上完整的规则引擎而不是轻量级路由。超高并发的主链路上引入额外抽象如果一条请求路径上只有一次判断、且这个判断已经用最简单的方式写好了没必要为了架构优雅硬套一层规则流程性能损耗虽然小但完全没必要。技术选型最怕的就是为了用某个框架而用某个框架。ruflo 的价值在于解决真实的问题不是为了替代所有代码里的if。5.2 后续演化从本地引擎到规则中心ruflo 目前是一个可以单独运行的本地引擎但我在设计时就为后续的方向留了扩展点。比较明确的有三个方向第一个是可视化规则编排。JSON 文件可以直接被一个简洁的 Web 界面渲染成规则树业务同学通过拖拽和表单填写来调整规则调整完后自动生成 JSON 配置下发到各个服务实例。这个方向一旦落地规则调整的主动权就完全可以交还给业务同学了。第二个是规则效果分析。因为 FlowResult 里记录了完整的命中率、耗时、动作执行结果把这份数据上报到日志中心后就能看到每个规则的命中率、平均执行耗时、异常率。这个数据对运营分析活动效果很有价值——比如某条规则命中率特别低可能说明它对应的客群定义有问题。第三个是灰度发布。规则配置支持按比例灰度比如先让 10% 的流量走新版本的规则观察一段时间没问题再逐步放量。实现思路是在流程执行前根据上下文里的标识如用户 id 的 hash决定是否应用新版本配置。这需要引擎侧支持动态加载和维护多个版本的流程实例但架构上预留好接口难度不大。5.3 踩坑清单三个我悔不当初的设计与实现选择写这篇文章的目的之一也是希望后来者能避免我走过的弯路下面几个坑值得认真提一下。坑一操作符类型做宽松比较最早的实现里 EQ、NEQ 直接用了equals结果 1 和 1.0 直接被判为不相等。后来全部改成基于 BigDecimal 归一化才算彻底解决。教训是规则引擎里的比较必须基于类型归一化不要依赖任何默认的基础类型比较行为。坑二动态配置的原子性问题前面提到过配置中间态的事故这里再强调一次规则配置的发布应该是一次性替换而不是增量式修改。保证任何一个时刻拉到的都是一份完整的、可解析的配置。不要让请求有机会看到配置写了一半的状态。坑三过度抽象最开始我给条件设计了一整套可插拔语法解析器想着未来支持自定义表达式语言。结果这个抽象在很长时间里根本用不上反而增加了理解和维护成本。后来果断砍掉只保留 JSON 结构和简单的自定义函数注册机制。技术人的宿命往往是想得太多把这个教训写在这与大家共勉。5.4 我现在的使用体验与建议ruflo 在我这边已经稳定运行了半年多支撑了订单分派、优惠计算、消息触达三个业务场景的规则路由累计执行了几千万次没出过一起因为引擎本身导致的线上故障。这个结果对我来说基本达到了当初的设计预期。如果看了我的分享你也想在项目里引入类似的思路我的建议是不要照搬代码先理清自己的规则场景把核心抽象规则、流程、上下文理清楚再动手。ruflo 对我来说最宝贵的并不是某一段代码而是把条件路由从业务代码里抽出来做成一等公民这个思考过程。当团队里所有人都开始用这种视角看问题代码结构的改善速度会远超预期。最后分享一个我还在持续做的实践规则配置不应该是隐藏的后门它应该成为团队共同维护的核心资产。业务规则是业务最本质的逻辑表达值得被认真对待、仔细记录、充分测试。ruflo 只是把这些规则从代码的犄角旮旯里移到阳光下让它们可以被维护、被审视、被改进——这件事本身的长期价值远大于任何一处具体的代码优化。 轻量级规则流路由引擎ruflo：从零实现的架构设计与实践
这几年在折腾后端服务的时候我越来越觉得很多逻辑本质上都是在处理同一件事根据一堆条件决定一条数据接下来往哪儿走。不管是订单状态流转、工单分配、消息推送还是风控里那一长串“如果...就...”的判断写到最后都容易变成一团乱麻——if套elseswitch里再嵌switch全局搜一个判断条件能搜出十几个地方要一起改。我试过用规则引擎像是 Drools 这种功能是真的强但引入一套重引擎的成本也真的高规则文件语法、IDE 插件、部署方式都得跟着变团队的学习曲线一下子就拉起来了。后来我就想能不能自己写一个足够轻、足够直观、但又真的能扛住业务压力的路由判断组件于是就有了ruflo这个项目。ruflo 这个名字来自 “rule flow” 的简写定位很简单一个轻量级的规则流路由引擎。它不追求像 Drools 那样把所有知识库、推理机、工作内存都塞进来它只做一件事——把分散在代码各个角落的“条件→动作”逻辑统一收拢成一份清晰、可配置、可观测的规则集合然后用一个极简的引擎去执行它们。这篇文章我就把这个项目的设计思路、核心实现、落地细节和踩坑记录完整分享一下。这个项目适合谁看如果你正在维护一个业务规则经常变化、判断分支越来越多的后端服务或者你早就受够了那坨怎么重构都还是有味道的条件代码又或者你纯粹是想看看一个轻量级规则引擎是怎么从零设计出来的那这篇内容应该对你有帮助。我会把核心的抽象、数据结构、执行流程都讲透并且给出可以直接抄走的代码骨架。1. 项目整体设计与思路拆解1.1 需求收敛到底要解决什么问题我决定写 ruflo 之前先把自己手上服务里那些最让人头疼的判断逻辑梳理了一遍。反复出现的基本是这三类多条规则按优先级依次命中比如优惠计算先判断是否新人、再判断是否会员、再判断是否有定向券命中第一个就停止后续判断。一条数据要经过多个阶段处理比如工单创建后先自动分派、再发通知、再更新统计每个阶段都有独立的条件判断。规则需要随时调整但不想频繁发版产品说这个活动门槛从 100 改成 80最好改个配置就能生效而不是改代码、走发布流程。这三类需求有个共同点条件表达式的结构其实都不复杂复杂的只是条件和动作之间的组合关系。我真正需要的是把这种组合关系显式地建模出来而不是让它散落在一堆if语句里。所以 ruflo 的核心抽象最终收敛成三样东西Rule规则包含一个命中条件和一组动作列表。Flow流程一组有序规则的集合定义了按照什么顺序去匹配这些规则。Context上下文在整条流程里流转的数据载体规则基于它做判断动作基于它做变更。这个模型非常简单我相信任何有过业务开发经验的人看一遍就能在脑子里建立画面。而这恰恰是它最大的优势——团队协作时沟通成本才是最大的隐性成本。1.2 选型对比为什么没有直接用现成的规则引擎在动手写之前我也认真对比过市面上主流的方案这里把当时的思考完整记录下来。首先看Drools。它是 Java 生态里事实上的规则引擎标准支持复杂的 forward/backward chaining、truth maintenance、temporal reasoning 这些重型特性规则文件用 DRL 语法编写。问题是我们 90% 的实际场景用到的能力不到它的 5%却要为了这 5% 的能力背上完整的运行时开销和语法学习成本。DRL 语法对大多数业务开发同学来说并不友好IDE 提示也一般新版有改进但依然不算顺滑出了问题排查链路还长——规则引擎内部自己有一套 rete 网络执行逻辑跟业务代码之间隔着一层。再看Easy Rules。这个库确实轻量理念也很接近我的想法——用 POJO 定义规则、用注解声明条件。但它提供的主要还是单条规则的执行能力对于流程编排、规则的动态加载与热更新、完整的可观测性它给的是接口而不是内置实现需要我额外去补很多胶水代码而且规则之间的依赖关系在代码里仍然不够直观。至于Aviator / Groovy 表达式引擎这类东西它们解决的是表达式求值问题核心能力是把一个字符串表达式的计算结果算出来。但表达式引擎管不了完整的流程路由该有if-else的地方还是得有只是把判断条件换成了字符串——并没有根治代码结构的问题只是把乱从 Java 代码换成了字符串。ruflo 的差异化定位很清楚不做全功能的规则引擎只做流程化的条件路由。它刻意放弃了对复杂规则网络的支持换来了三个东西——学习成本几乎为零、执行路径完全透明、规则可以任意编排和热更新。这正好踩中了我在实际业务里感受到的最大痛点。1.3 架构分层ruflo 的整体模块划分ruflo 从代码结构上分为四层每一层各司其职下面把每层的职责和设计思路拆开讲。表达式层Expression Layer负责条件表达式的解析和求值。表达式以 JSON 结构描述解析后生成对外统一的条件求值接口Condition然后由具体实现去执行判断。这一层保证了上层完全不必关心条件是用什么语法写的——是 EQ、IN、RANGE 还是自定义函数通通屏蔽掉。规则层Rule Layer负责把一条规则的完整生命周期管理起来包括规则的创建、命中判断、动作执行、结果记录。一条规则内部有 id、name、priority、condition 和 actions 五个核心属性。这一层不关心规则在整个流程里处于什么位置它只保证我在该判断的时候判断该执行的时候执行执行结果完整记录下来。流程层Flow Layer负责规则的编排。流程在启动时会把自己包含的所有规则按优先级排序、建立索引然后按照设定的策略首个命中或全部执行逐条驱动。这一层还负责上下文的管理和传递保证一个流程执行下来用的始终是同一个上下文实例。最后是运行时层Runtime Layer它把对外的一切能力暴露出去——规则的加载从本地文件、数据库、远程配置中心、缓存管理、动态刷新、执行监控和指标埋点。应用接入时只需要面向 runtime 编程不需要依赖上面任何一层具体的类。这四层设计有一个直接的好处想替换掉任何一种实现影响的仅仅是一层。比如接入方读规则不想用我提供的 JSON loader自己写个读数据库的 loader 也完全没问题——因为接口都是独立的。1.4 规则模型设计JSON 即 DSLruflo 最终把规则文件设计成了纯 JSON 结构。这个设计决策当时有人觉得是不是太简陋了可实际用下来我发现它反而是项目里口碑最好的部分。一个最简规则定义长这样{ rules: [ { id: member-rule, name: 会员用户自动打标, priority: 1, when: { all: [ { field: user.level, operator: GTE, value: 2 }, { field: user.status, operator: EQ, value: ACTIVE } ] }, then: [ { action: user.tag, params: { tag: VIP } } ] } ] }之所以坚持用 JSON 而不是设计一套专有的 DSL原因很朴素JSON 是通用标准学习成本为零任何语言任何工具链都能解析结构化的数据天然适合做可视化展示——把这份 JSON 丢给一个简单的 Web 页面马上就能渲染成一张可视化规则树最重要的是它可以轻松实现动态修改——规则存在数据库里运营配置后台改完引擎拉取最新版本就生效。字段说明如下字段类型含义idstring规则的唯一标识流程内不允许重复namestring规则的可读名称日志和监控里展示用priorityint优先级数值小的先执行whenobject命中条件支持 AND / OR / NOT 嵌套组合thenarray命中的动作列表按数组顺序依次执行when在这里支持三种组合结构——all、any、not分别是逻辑与、逻辑或和取反。它们可以任意嵌套这样条件组合的表达能力其实完全不输传统代码里的布尔运算符组合只是用了更规整的树形结构来表达。1.5 执行引擎核心机制从条件到动作再到流程控制有了规则模型引擎的执行机制就顺理成章了。整个执行过程分三步条件求值阶段从规则的when结构出发构建一棵条件树。树的叶子节点是原子条件字段、操作符、值的三元组非叶子节点是逻辑组合节点。求值的时候递归遍历这棵树每个节点返回一个布尔值根节点的结果就是整条规则的命中结果。动作执行阶段命中之后引擎遍历规则的then数组逐个调用动作执行器。动作执行器的实现方式是基于策略模式——把动作类型字符串映射到对应的执行方法天然方便做扩展、测试和替换。流程编排阶段引擎持有一组规则通过策略控制流转。默认策略是首个命中即停止也就是按优先级依次判断一旦某条规则命中就执行并结束整条流程还有一个全部命中策略会按顺序执行所有命中的规则。这两种策略基本覆盖了业务里绝大多数场景。执行完成后引擎返回一个FlowResult对象里面包含整个执行过程的完整信息最终命中了几条规则、每条规则的命中状态、执行耗时、动作执行结果和可能的异常信息。这些数据就是可观测性的根基——业务出问题了直接翻这个结果对象就能知道到底哪条规则命中、哪个动作执行失败、花了多长时间。2. 核心细节解析与实操要点2.1 原子条件求值字段路径与操作符解析规则条件的最小单元是{ field: user.level, operator: GTE, value: 2 }这个三元组背后的实现机制是整个条件系统最基础的部分。字段路径解析我实现了一个极简的属性解析器支持点号路径访问。它会处理三种情况普通 Map 的直接获取、对象的反射获取适配一些上下文里放 POJO 的场景、以及 List / 数组的下标访问比如order.items[0].price。整体实现逻辑短小但很实用。操作符定义我预置了一份操作符集用枚举定义包括 EQ等于、NEQ不等于、GT / GTE / LT / LTE大小比较、IN / NOT_IN集合包含、CONTAINS字符串包含、BETWEEN区间判断、STARTS_WITH / ENDS_WITH、IS_NULL / NOT_NULL、REGEX正则匹配等等。每一个操作符都实现同一个函数式接口入参是实际值和预期值出参是布尔结果。类型安全这一点非常关键。条件里声明的 value 从 JSON 解析出来时在数字场景会有基础类型的不确定性整数、浮点、精度。如果不做类型归一化直接比较会出现2 1返回 false 这种诡异问题。踩过一次坑之后我在操作符执行之前加入了类型归一化逻辑统一把数字类型转成 BigDecimal 再比较彻底解决了数字比较的精度和类型问题。原子条件的求值接口定义如下这里面resolveFieldValue负责从上下文中按路径取值compareValue负责按操作符比较public interface Condition { boolean evaluate(EvalContext context); }每个原子条件都是一个Condition实例逻辑组合节点AllCondition、AnyCondition、NotCondition也都实现这个接口这样在求值时上层完全不需要关心节点类型直接递归调用evaluate就行。2.2 动作抽象与扩展机制策略模式下如何灵活对接业务动作动作系统是 ruflo 里扩展性要求最高的一个模块。业务方接入之后肯定会不断往里面加自己的动作——发消息、写库、调 API、更新状态什么都有。如果每加一个动作就要改引擎代码那就说明抽象设计有问题。我采用的是注册表模式的策略设计。动作执行器统一实现ActionExecutor接口每个执行器声明自己处理什么动作类型然后在 ruflo 启动时注册到动作注册表里。引擎执行动作时先按动作类型从注册表查出对应的执行器再调用执行。接口定义简化为这样public interface ActionExecutor { String type(); ActionResult execute(String ruleId, MapString, Object params, EvalContext context); }type()返回动作类型比如user.tag、order.updateStatus。execute做真正的业务处理。这种方式带来了一个额外的好处动作可以像插件一样装配。基础动作引擎内置业务动作由接入方自己实现自己注册双方互不干扰测试时也可以只针对单独的执行器做单元测试。讲到这还得补充一句动作执行器里不要做耗时不可控的操作。规则引擎的定位是轻量路由判断如果动作里有外部 API 调用建议通过异步消息丢给下游处理而不是在 ruflo 的执行链路里同步等待。否则一个慢接口会把整条规则流程拖死失去了引擎本身轻快的定位。2.3 流程定义与加载一个完整的 Flow 配置长什么样实际项目中肯定是多条规则组成一条流程。流程配置的结构我设计成下面这个样子整体上是一个包含元信息、变量声明和规则列表的树{ flowId: order-dispatch-flow, name: 订单分派流程, description: 新订单自动分派给对应处理小组, mode: first_match, variables: { maxDispatchAttempts: 3 }, rules: [ { id: rule-1, name: 高优客户优先分派, priority: 1, when: { any: [ { field: order.customerLevel, operator: EQ, value: PLATINUM }, { field: order.customerLevel, operator: EQ, value: GOLD } ] }, then: [ { action: dispatch.assign, params: { group: priority-group } }, { action: dispatch.notify, params: { channel: sms } } ] }, { id: rule-2, name: 普通客户按地域分派, priority: 2, when: { all: [ { field: order.region, operator: IN, value: [NORTH, SOUTH] } ] }, then: [ { action: dispatch.assign, params: { group: normal-group } } ] }, { id: rule-default, name: 兜底规则, priority: 999, when: { not: { any: [ { field: order.groupAssigned, operator: EQ, value: true } ] } }, then: [ { action: dispatch.assign, params: { group: default-group } } ] } ] }这份配置里有两个值得注意的设计点。一个是mode字段它声明了流程执行策略。first_match是首个命中即停止all_match是全部命中都执行。个别场景还需要失败中止策略后续我通过扩展支持了fail_fast允许配置规则执行出异常时是终止整条流程还是记录后继续。另一个是variables段它可以声明一些流程级的公共变量。实际使用时我会用它来暴露一些调参入口比如循环次数上限、超时时间这些可能经常需要调整的值放到流程配置里让运维改起来方便而不是写死在代码里。2.4 上下文对象设计与传递状态隔离与数据流向Context上下文在 ruflo 里承担两个职责一是存放业务数据让规则和动作都能读取二是记录执行过程数据比如哪些规则命中了、执行状态如何、有没有抛异常。这两个职责混在一个对象里容易乱所以我把上下文拆成两层EvalContext求值上下文只读业务数据提供给条件表达式求值。数据源是所有规则共享的同一个数据容器。FlowResult结果对象存储执行结果信息规则命中状态、动作执行结果、耗时、异常等全部落在这个对象里供调用方检查。上下文传递遵循一个原则整条流程共用一个 EvalContext规则动作对它的修改对后续规则可见。这一点很关键比如规则一给order.groupAssigned赋值为 true规则二读取时就能看到这个变化从而跳过执行实现规则间通过数据协作的效果。这种设计天然支持了规则之间的依赖。虽然我前面说规则之间不直接互相依赖但通过修改上下文的共享数据间接的依赖关系是可以表达的这是实际使用中非常顺滑的一个特性。3. 实操过程与核心环节实现3.1 环境准备与项目骨架搭建ruflo 的核心代码我用了 Java 11 实现构建工具用 Maven。选 Java 而不是其他语言主要考虑到我所在团队的技术栈和后续接入 Java 服务的便利性。项目本身的模块结构是这个样子的ruflo ├── ruflo-api -- 对外暴露的接口与核心模型 ├── ruflo-core -- 引擎核心条件求值、动作执行、流程编排 ├── ruflo-json-loader -- 基于 Jackson 的规则配置加载器 ├── ruflo-spring-boot -- Spring Boot 自动配置封装 └── ruflo-demo -- 可运行的示例工程搭建骨架时我把模块拆分得很早。一开始很多人劝我别上来就分模块说单模块跑通了再拆也不迟。但在这种要给别人当 SDK 用的项目里模块边界越早清晰后面迭代就越省心。接入方只依赖ruflo-api就够了完全不用暴露核心实现细节升级引擎也不会破坏接口兼容性。3.2 核心接口与模型定义代码骨架逐段解析模型类不多我把最核心的几个贴出来并逐段解释。这是理解 ruflo 代码结构最好的路径。条件树节点的核心接口和实现如下public interface Condition { boolean evaluate(EvalContext context); } // 逻辑与所有子条件都满足才返回 true public class AllCondition implements Condition { private final ListCondition conditions; public AllCondition(ListCondition conditions) { this.conditions conditions; } Override public boolean evaluate(EvalContext context) { if (conditions null || conditions.isEmpty()) { return true; } for (Condition condition : conditions) { if (!condition.evaluate(context)) { return false; } } return true; } } // 逻辑或任一子条件满足即返回 true public class AnyCondition implements Condition { private final ListCondition conditions; public AnyCondition(ListCondition conditions) { this.conditions conditions; } Override public boolean evaluate(EvalContext context) { if (conditions null || conditions.isEmpty()) { return true; } for (Condition condition : conditions) { if (condition.evaluate(context)) { return true; } } return false; } }这里有一个容易被忽视的点子条件为空时的返回策略。我统一选择返回 true。理由是业务配置里如果一个all块下面一个条件都没填说明配置方是想无条件通过这种场景在动态配置时很常见——先在 JSON 里留一个空结构后续再往里填条件。流程执行器是核心中的核心public class FlowExecutor { private final MapString, Condition compiledRuleConditions; private final MapString, ListActionCall compiledRuleActions; private final ListRuleDefinition sortedRules; private final FlowMode mode; public FlowResult execute(EvalContext context) { FlowResult result new FlowResult(context); for (RuleDefinition rule : sortedRules) { Condition condition compiledRuleConditions.get(rule.getId()); boolean matched condition.evaluate(context); result.addRuleResult(rule.getId(), matched); if (!matched) { continue; } if (mode FlowMode.FIRST_MATCH) { executeActions(rule.getId(), context, result); result.stop(); break; } executeActions(rule.getId(), context, result); } return result; } }执行顺序依赖于sortedRules在加载流程时就被按优先级排好序。条件求值和动作执行都是预先编译好的执行时不解析任何 JSON保证运行时的高效。这里我特意把规则求值和动作执行拆成独立方法是为了让单测能分别覆盖两条链路。3.3 解析器实现从 JSON 到可执行条件树的映射条件树的构建是一个典型的递归下降过程。我写了一个ConditionParser输入是 JSON 节点输出是条件树。核心逻辑如下public Condition parse(JsonNode whenNode) { if (whenNode.has(all)) { ListCondition conditions new ArrayList(); for (JsonNode child : whenNode.get(all)) { conditions.add(parse(child)); } return new AllCondition(conditions); } if (whenNode.has(any)) { ListCondition conditions new ArrayList(); for (JsonNode child : whenNode.get(any)) { conditions.add(parse(child)); } return new AnyCondition(conditions); } if (whenNode.has(not)) { return new NotCondition(parse(whenNode.get(not))); } return parseAtomicCondition(whenNode); }每一层递归都往树深处走一层直到叶子节点的原子条件解析。这样无论配置嵌套多深解析过程都是稳定、可预测的。为了让解析失败时能快速定位问题我在解析器里加了详细的错误信息——哪条规则、哪个字段路径解析失败、期望什么类型、实际是什么类型这些信息全部拼到异常消息里。3.4 一个完整的接入示例从流程配置到业务代码调用动手实践的部分来了我用一个订单自动分派的场景演示完整的接入流程。这个场景很典型新订单创建后需要根据订单属性自动决定分派给哪个小组处理。服务里直接调用 ruflo 的流程执行器RestController public class OrderController { private final FlowRuntime flowRuntime; public OrderController(FlowRuntime flowRuntime) { this.flowRuntime flowRuntime; } PostMapping(/orders) public OrderVO createOrder(RequestBody CreateOrderRequest request) { // 1. 构建业务数据 MapString, Object data new HashMap(); data.put(order.id, request.getOrderId()); data.put(order.amount, request.getAmount()); data.put(order.region, request.getRegion()); data.put(order.customerLevel, request.getCustomerLevel()); data.put(order.groupAssigned, false); // 2. 构建求值上下文 EvalContext context new EvalContext(data); // 3. 执行订单分派流程 FlowResult result flowRuntime.execute(order-dispatch-flow, context); // 4. 根据执行结果做后续业务处理 String assignedGroup (String) context.get(order.assignedGroup); log.info(订单 {} 分派完成命中规则 {}耗时 {}ms, request.getOrderId(), result.getMatchedRuleIds(), result.getCostMs()); return OrderVO.of(request, assignedGroup); } }接入方的代码量就是这么多。业务逻辑里不需要写任何一条if判断所有的条件分支全在流程配置里表达。业务的同事如果需要调整分派规则改配置就行不用动一行代码。3.5 动态刷新如何在不停机的情况下让规则变更立即生效规则配置如果只能写在本地文件里那基本等于没有解决动态调整这个核心诉求。所以我给 ruflo 加了一个轻量的动态刷新机制版本号 轮询加载。具体实现思路是在流程配置里增加一个version字段。接入方启动一个定时任务默认 30 秒轮询一次每次拉取最新配置后比对 version发现变化就触发流程实例的重建——解析新配置、编译条件树、更新内存中的执行器。整个过程对调用方完全透明不需要重启进程不需要重新发布。代码实现很简洁核心就是一个版本比较和实例重建public void refreshIfNeeded(String flowId, String latestConfig, long latestVersion) { FlowHolder holder flowRegistry.get(flowId); if (holder null || holder.getVersion() latestVersion) { FlowDefinition definition parseAndCompile(latestConfig); flowRegistry.put(flowId, new FlowHolder(latestVersion, definition)); } }这里有一个实践上的重要经验配置变更一定要保证原子性。曾经出现过一次线上事故我尝试在同一个流程里同时新增一条规则和修改一条规则两个操作先后推送到配置中心中间有一个短暂的中间态。结果刚好有请求在中间态时拉取了配置导致解析失败。后来我加了一个先完整发布、后原子切换的机制彻底解决了这个问题。3.6 性能评估执行耗时与调优记录一个轻量级规则引擎性能数据必须拿得出手。我在一个 2 核 4G 的容器里做了一个简单的基准测试模拟典型的10 条规则、每条 3 个原子条件、首条规则命中场景。测试结果是平均单次执行耗时在 0.5ms 左右P99 不到 1.2ms内存占用也很稳定没有明显波动。这个性能对我来说完全够用——在大多数业务请求链路里0.5ms 只占整个请求耗时的一个零头。性能之所以能压到这个水平主要靠三件事编译期解析流程加载时就把 JSON 解析成 Condition 树运行时不再做任何配置解析。索引直查字段路径在解析时就生成索引映射求值时直接按索引取数不再做字符串解析。共享受上下文字段池频繁访问的字段用线程安全的局部缓存避免重复的 Map 查找。如果遇到更大的规则量比如单流程超过 50 条规则建议在引擎层增加一层分组合并把同优先级的规则合并成组组间执行首个命中策略组内执行全部执行策略这样可以大幅减少被判断的规则数量。4. 常见问题与排查技巧实录4.1 规则始终不命中条件值类型与路径问题这个问题在接入初期出现频率最高。现象很典型配置看起来完全正确但规则就是不命中怎么调都不生效。排查思路可以按照下面的方向依次推进确认字段路径正确性。比如上下文里放的是user.level但是配置里写成了user.levels一个字母之差就永远取不到值。我在加载器里加了路径校验加载阶段提前暴露问题避免运行时才发现。确认类型一致性。JSON 解析后的数字是Integer还是Long跟操作符里声明的是否匹配实际执行时很容易出现类型不一致导致的误判。确认 evaluate 的递归逻辑。嵌套的all、any如果搭配不当逻辑上很容易出现看起来该命中但实际不命中的情况建议在配置里先简化成一个条件验证基础能力再从简单到复杂逐步叠加。我给 ruflo 加了一个诊断模式开启后可以把条件树里每个节点的计算过程打印出来——从哪个字段取了什么值、跟期望值比较的结果是什么——逐层显示。这个功能调规则的时候特别有用基本能省去 70% 的无效排查时间。4.2 流程执行异常动作执行器报错时的处理策略动作执行器是业务代码报错是不可避免的。关键是报错之后流程怎么走。我最后采用了双模式配置FAIL_IGNORE默认模式某个动作执行失败时记录异常到FlowResult继续执行下一个动作和后续规则。FAIL_FAST严格模式某个动作失败时立即中止整条流程后续规则不再执行调用方拿到的是带异常的结果对象。两种模式各有适用场景。比如发通知这种非核心链路用 FAIL_IGNORE 比较合适——通知挂了不能影响主流程但如果是扣库存这种核心动作那就必须用 FAIL_FAST——后面依赖库存结果的逻辑不能继续跑。另外很重要的一点是动作执行器方法体里要注意上下文的数据一致性。如果动作 A 修改了上下文字段后续动作读取到的是修改后的值这本来是我们想要的效果但如果动作 A 修改失败了还留下一个半改状态后面就全乱了。所以涉及多字段联动变更时建议在新对象上构建好数据后一次性放回上下文而不是逐个字段覆盖。4.3 动态刷新生效不及时版本号与缓存策略导致的问题动态刷新上线后有一个问题反复出现规则配置在后台已经改了但流程执行时用的还是旧版本好几分钟后才生效。查下来的原因有两个层面。一是轮询间隔设置太长。默认 30 秒一轮如果不追求秒级生效这个值其实是够的但如果你确实需要秒级生效建议把轮询改短到 5 秒或者直接对接配置中心的推送机制如 Nacos 的监听回调、Apollo 的 ChangeListener用事件驱动代替轮询。二是我踩过的一个隐蔽问题缓存了旧版本的 FlowResult结果缓存。在一些高频查询场景里我给流程执行结果加了短时缓存本意是减少重复求值但规则更新后缓存没及时清理导致旧结果被反复返回。问题出在缓存 key 只包含 flowId没包含 version。修复方案是在 key 里拼接 version这样规则一更新缓存自动失效。4.4 排查技巧快速定位问题规则的三板斧积累的排障经验总结下来就三板斧。第一板斧是每次执行后必须看 FlowResult。我在内部推动过一个规矩——所有接入 ruflo 的服务执行完后必须把 FlowResult或者至少把 matchedRuleIds 和 ruleResults打印到业务日志里。这样一旦业务异常翻日志就能看到是哪条规则的锅不用盲猜。第二板斧是提供诊断模式。通过一个开关让流程执行时把所有条件求值明细都输出出来。生产环境我默认关闭排查问题时临时打开完事再关。第三板斧是规则配置的完整版本历史。动态配置系统里每次变更都留下历史版本一旦出了问题可以一键回滚到上一个稳定版本并能直观对比版本差异。这个机制救过我好几次。4.5 常见问题速查表问题现象可能原因解决方案规则不命中字段路径写错开启诊断模式逐层打印求值过程数字比较结果异常JSON 数字类型与预期不一致统一用 BigDecimal 归一化后再比较动作执行失败但无感知默认失败忽略模式根据业务重要性按需切换为 FAIL_FAST配置已修改但不生效轮询间隔未到 / 版本缓存缩短轮询间隔或接入配置中心推送缓存返回旧结果缓存 key 未包含 version缓存 key 拼接版本号更新即失效加载流程时解析失败规则配置里类型错误完善配置校验启动时预加载检查5. 一些想对使用者说的话我们如何用好规则引擎5.1 设计原则什么时候适合用 ruflo什么时候不适合任何事情都有边界。ruflo 适合下面这些场景规则经常变每次变更都要发版的场景。比如营销活动的门槛调整、风控规则参数的动态配置通过 ruflo 改个配置就能生效。分支判断多逻辑分散在不同模块难以统一管理的场景。把规则集中看管起来以后什么时候改规则、改了什么、影响哪些流程一目了然。希望业务和开发之间能够用同一份规则语言沟通的场景。JSON 规则配置就是活的文档业务看得懂、开发也看得懂。但有些场景我明确不建议用它流程分支极少就两三个 if且基本不变这种用 ruflo 属于大炮打蚊子。需要复杂的规则推理比如规则之间有复杂的依赖链、需要回溯、需要基于历史判断这些这类需求建议上完整的规则引擎而不是轻量级路由。超高并发的主链路上引入额外抽象如果一条请求路径上只有一次判断、且这个判断已经用最简单的方式写好了没必要为了架构优雅硬套一层规则流程性能损耗虽然小但完全没必要。技术选型最怕的就是为了用某个框架而用某个框架。ruflo 的价值在于解决真实的问题不是为了替代所有代码里的if。5.2 后续演化从本地引擎到规则中心ruflo 目前是一个可以单独运行的本地引擎但我在设计时就为后续的方向留了扩展点。比较明确的有三个方向第一个是可视化规则编排。JSON 文件可以直接被一个简洁的 Web 界面渲染成规则树业务同学通过拖拽和表单填写来调整规则调整完后自动生成 JSON 配置下发到各个服务实例。这个方向一旦落地规则调整的主动权就完全可以交还给业务同学了。第二个是规则效果分析。因为 FlowResult 里记录了完整的命中率、耗时、动作执行结果把这份数据上报到日志中心后就能看到每个规则的命中率、平均执行耗时、异常率。这个数据对运营分析活动效果很有价值——比如某条规则命中率特别低可能说明它对应的客群定义有问题。第三个是灰度发布。规则配置支持按比例灰度比如先让 10% 的流量走新版本的规则观察一段时间没问题再逐步放量。实现思路是在流程执行前根据上下文里的标识如用户 id 的 hash决定是否应用新版本配置。这需要引擎侧支持动态加载和维护多个版本的流程实例但架构上预留好接口难度不大。5.3 踩坑清单三个我悔不当初的设计与实现选择写这篇文章的目的之一也是希望后来者能避免我走过的弯路下面几个坑值得认真提一下。坑一操作符类型做宽松比较最早的实现里 EQ、NEQ 直接用了equals结果 1 和 1.0 直接被判为不相等。后来全部改成基于 BigDecimal 归一化才算彻底解决。教训是规则引擎里的比较必须基于类型归一化不要依赖任何默认的基础类型比较行为。坑二动态配置的原子性问题前面提到过配置中间态的事故这里再强调一次规则配置的发布应该是一次性替换而不是增量式修改。保证任何一个时刻拉到的都是一份完整的、可解析的配置。不要让请求有机会看到配置写了一半的状态。坑三过度抽象最开始我给条件设计了一整套可插拔语法解析器想着未来支持自定义表达式语言。结果这个抽象在很长时间里根本用不上反而增加了理解和维护成本。后来果断砍掉只保留 JSON 结构和简单的自定义函数注册机制。技术人的宿命往往是想得太多把这个教训写在这与大家共勉。5.4 我现在的使用体验与建议ruflo 在我这边已经稳定运行了半年多支撑了订单分派、优惠计算、消息触达三个业务场景的规则路由累计执行了几千万次没出过一起因为引擎本身导致的线上故障。这个结果对我来说基本达到了当初的设计预期。如果看了我的分享你也想在项目里引入类似的思路我的建议是不要照搬代码先理清自己的规则场景把核心抽象规则、流程、上下文理清楚再动手。ruflo 对我来说最宝贵的并不是某一段代码而是把条件路由从业务代码里抽出来做成一等公民这个思考过程。当团队里所有人都开始用这种视角看问题代码结构的改善速度会远超预期。最后分享一个我还在持续做的实践规则配置不应该是隐藏的后门它应该成为团队共同维护的核心资产。业务规则是业务最本质的逻辑表达值得被认真对待、仔细记录、充分测试。ruflo 只是把这些规则从代码的犄角旮旯里移到阳光下让它们可以被维护、被审视、被改进——这件事本身的长期价值远大于任何一处具体的代码优化。