业务规则引擎

试用

编辑任意条件，语句、判定和解释会同步更新。

1. 01

   安装

   按需引入。引擎与类型定义没有任何运行时依赖；构建器是独立的包，因为只做规则求值的服务器不必附带 React 编辑器。

   terminal复制

   # the engine and its vocabulary
   pnpm add @adysre/rules-core @adysre/rules-types
   
   # the visual builder, when you want one
   pnpm add @adysre/rules-ui @adysre/rules-react @adysre/rules-theme

2. 02

   编写规则

   规则就是普通 JSON。构建函数负责 ID 和时间戳，但你也可以手写对象、直接存储、在评审中做差异对比。

   rules/large-orders.ts复制

   import { all, condition, field, literal, rule } from '@adysre/rules-core';
   
   // A rule is plain JSON. The builders exist so ids and timestamps are handled
   // for you, but nothing stops you writing the object by hand.
   const largeOrders = rule({
     name: 'Large orders from new customers need approval',
     kind: 'validation',
     when: all([
       condition({
         left: field('order.total'),
         operator: 'greaterThan',
         args: [literal(1000)],
       }),
     ]),
     then: [{ id: 'a_hold', type: 'requireApproval' }],
   });

3. 03

   运行

   同步且纯粹。注册表默认为空，因为规则能做什么由你决定。结果包含判定、动作和执行轨迹。

   rules/run.ts复制

   import { builtinPlugins, createContext, createRegistry, evaluateRule } from '@adysre/rules-core';
   
   // The registry starts EMPTY: what rules may do is your choice. Pass the
   // built-ins for the usual twenty-seven operators and twenty-three functions.
   const registry = createRegistry(builtinPlugins);
   
   const outcome = evaluateRule(registry, largeOrders, createContext(order));
   
   outcome.verdict;      // 'matched' | 'unmatched' | 'skipped' | 'errored'
   outcome.actions;      // what to do — the engine never does it for you
   outcome.trace;        // every node that ran, and what it concluded

4. 04

   读回来

   每条规则都能渲染成一句话，由树生成，且永不反向解析。先有结构，后有文本。

   rules/explain.ts复制

   import { describeRule } from '@adysre/rules-renderer';
   
   describeRule(largeOrders, { plugins: registry }).text;
   // When order total is greater than 1,000
   // Then require approval
   
   // Structure first, text second: `.lines` gives typed segments, so a UI can
   // highlight the field being edited or colour the condition that decided it.

5. 05

   添加自己的运算符

   引擎能做的一切都是插件。注册之后构建器会提供它，调试器会解释它，而规则仍是普通 JSON。

   rules/registry.ts复制

   import { createRegistry, builtinPlugins, RuleError } from '@adysre/rules-core';
   import type { OperatorPlugin } from '@adysre/rules-types';
   
   // Your own operator. The builder picks it up, the debugger explains it, and
   // your rules stay plain JSON — no change to the engine.
   const withinBusinessHours: OperatorPlugin = {
     id: 'withinBusinessHours',
     labelKey: 'operators.withinBusinessHours',
     arity: 0,
     accepts: ['date'],
     evaluate: (left) => {
       if (typeof left !== 'string') {
         // Not `false`: a broken comparison must not look like a failed one.
         throw new RuleError('type_mismatch', 'withinBusinessHours needs a date.');
       }
       const hour = new Date(left).getHours();
       return hour >= 9 && hour < 17;
     },
   };
   
   const registry = createRegistry(builtinPlugins, { operators: [withinBusinessHours] });

6. 06

   让别人来编辑

   可视化构建器完全由插件元数据驱动：arity 决定显示几个输入框，accepts 决定字段可用哪些运算符。

   app/editor.tsx复制

   'use client';
   
   import { RuleBuilder } from '@adysre/rules-ui';
   
   export function Editor({ rule, onChange }) {
     return (
       <RuleBuilder
         rule={rule}
         registry={registry}
         sample={sampleOrder}   // runs the rule as you type
         onChange={onChange}
       />
     );
   }

7. 07

   找出原因

   调试器指出决定判定的那一行，并关闭短路再跑一次，暴露快速路径跳过的故障。

   rules/debug.ts复制

   import { debugRule } from '@adysre/rules-devtools';
   
   const session = debugRule(registry, largeOrders, createContext(order));
   
   session.decision;                  // which row decided, or that several did
   session.comparison.hiddenErrors;   // faults a short circuit stepped over

8. 08

   持久化

   一个带版本与还原的存储契约。还原会写入新版本而不是回退历史。

   rules/storage.ts复制

   import { createMemoryStorage, runStorageConformance } from '@adysre/rules-storage';
   
   const storage = createMemoryStorage();
   await storage.save(largeOrders);          // version 1
   await storage.restore(largeOrders.id, 1); // a NEW version holding version 1
   
   // Writing your own adapter? Check it against the same contract:
   const results = await runStorageConformance(() => createMyAdapter());

软件包

每个包都在需要它的阶段落地。按需安装。