# rule_engine

**Repository Path**: ahaow/rule_engine

## Basic Information

- **Project Name**: rule_engine
- **Description**: Drule业务规则可视化平台。基于Drools 封装的业务规则可视化平台，用于简化规则开发，将规则表达式、规则条件和规则动作等进行可视化展示，并降低学习和开发成本，帮助用户快速创建业务规则。并在其基础之上，拓展更多功能，如规则文件的变更差异、规则对象的热加载、KieBase管理与监控、规则执行信息监控等。
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 27
- **Forks**: 14
- **Created**: 2024-08-27
- **Last Updated**: 2026-02-08

## Categories & Tags

**Categories**: rule-engine

**Tags**: Java, drools, 规则引擎, 可视化编辑, DRULE

## README

# Drule

> 基于 Drools 封装的业务规则可视化平台

[![Java](https://img.shields.io/badge/Java-8+-blue.svg)](https://www.oracle.com/java/)
[![Drools](https://img.shields.io/badge/Drools-7.60.0.Final-green.svg)](https://www.drools.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 📚 介绍

Drule 是一个业务规则可视化平台，基于 Drools 规则引擎进行封装，旨在简化规则开发流程。平台将规则表达式、规则条件和规则动作等进行可视化展示，降低学习和开发成本，帮助用户快速创建业务规则。

### 核心特性

- 🎨 **可视化规则编辑** - 通过可视化界面配置规则条件和动作，无需编写 DRL 代码
- 🔄 **热加载支持** - 规则对象支持热加载，无需重启服务即可更新规则
- 📊 **规则差异对比** - 支持规则文件的变更差异可视化展示
- 🔍 **中文转译** - 将规则内容转译为中文，便于业务人员理解
- 📈 **执行监控** - 提供 KieBase 管理与监控、规则执行信息监控等功能
- 🧩 **灵活扩展** - 提供丰富的扩展点，支持自定义前置/后置处理器、监听器等

## 🌈 体验地址

- **在线演示**：[http://ahaoweb.cn/drule/visual](http://ahaoweb.cn/drule/visual)
- **账号**：test
- **密码**：123456
- **使用文档**：[CSDN 专栏](https://blog.csdn.net/qq_51513626/category_12897737.html)

## 🪙 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Java | 8+ | 基础运行环境 |
| Drools | 7.60.0.Final | 规则引擎核心 |
| Lombok | 1.18.30 | 简化代码 |
| JUnit | 4.8.2 | 单元测试 |
| PowerMock | 2.0.9 | Mock 测试 |

## 🏗️ 架构设计

### 整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│                        Drule 规则引擎平台                         │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────┐ │
│  │ drule-models│  │drule-compile│  │ drule-parse │  │drule-   │ │
│  │  对象配置   │──▶│  内容编译   │──▶│  DRL解析   │──▶│execute  │ │
│  │    模块     │  │    模块     │  │    模块     │  │执行模块 │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                        Drools 7.60.0.Final                       │
└─────────────────────────────────────────────────────────────────┘
```

### 模块说明

```xml
<modules>
   <module>drule-core</module>
</modules>
```

`drule-core` 是 Drule 的核心包，当前版本包含以下 4 个模块：

| 模块 | 说明 | 核心功能 |
|------|------|----------|
| `drule-models` | 对象配置模块 | 规则对象结构扫描、TreeNode 构建 |
| `drule-compile` | 内容编译模块 | 可视化结构编译为 DRL、规则校验、中文转译 |
| `drule-parse` | DRL 解析模块 | DRL 文件解析、语法树构建 |
| `drule-execute` | 执行模块 | 规则服务构建、会话管理、规则执行调度 |

### 数据流转

```
┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   Java 对象   │    │  可视化结构   │    │   DRL 文件   │    │   规则执行   │
│  @ClassAnn   │───▶│  DruleBlock  │───▶│   编译生成   │───▶│  RuleService │
│              │    │              │    │              │    │              │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
       │                   │                   │                   │
       ▼                   ▼                   ▼                   ▼
   TreeNode          规则条件/动作         DRL 内容          执行结果
```

## 📖 快速开始

### Maven 依赖

```xml
<dependency>
    <groupId>cn.ahaoweb.drule</groupId>
    <artifactId>drule-execute</artifactId>
    <version>1.7</version>
</dependency>
```

### 基础示例

#### 1. 定义规则对象

```java
@ClassAnn(name = "测试入参")
public class TestIn {
    @FieldAnn(name = "姓名")
    private String name;
    @FieldAnn(name = "年龄")
    private Integer age;
    // getter/setter...
}

@ClassAnn(name = "测试出参")
public class TestOut {
    @FieldAnn(name = "结果")
    private String result;
    // getter/setter...
}
```

#### 2. 创建规则服务

```java
// 方式一：使用 DruleServiceHelper（推荐）
RuleService ruleService = new DruleServiceHelper()
    .identifier("test_rule")
    .addContent(RuleType.RULE_BLOCK, drlContent)
    .addConfig(RuleServiceConfiguration.EXECUTE_MODE.DEBUG)
    .getRuleService();

// 方式二：使用构造器
RuleService ruleService = new RuleServiceImpl("test_rule")
    .addContent(RuleType.RULE_BLOCK, drlContent)
    .init();
```

#### 3. 执行规则

```java
// 创建会话并执行
RuleSession session = ruleService.createSession();
TestIn input = new TestIn();
input.setName("张三");
input.setAge(25);

FactInfo result = session.execute(input, new TestOut());
System.out.println(result.getOutput());
```

## 📖 详细使用说明

### 1. drule-models 模块

#### 1.1 TreeNode - 对象结构树

`TreeNode` 类用于构建类型（`Class`）结构树，提供了构建树节点、获取节点信息、判断节点类型以及根据路径查找节点等功能。

**核心方法**：`TreeNode.treeNode(Class<?> clazz)`

**使用示例**：

```java
// 设置默认的配置信息
RuleModelConfiguration.setChildDepth(2);

// 扫描规则对象，转换为树形结构
TreeNode treeNode = TreeNode.treeNode(TestObj.class);
System.out.println(treeNode);

// 通过路径获取对应节点
System.out.println(treeNode.find("testObj.treeNodes.cesu"));
```

> ⚠️ 注意：所扫描的 Class 必须使用 `@ClassAnn` 注解标注。

### 2. drule-compile 模块

#### 2.1 DefaultDruleCompile - 规则编译器

`DefaultDruleCompile` 是默认规则编译器，用于将结构化规则对象编译为 DRL 文件。

**核心方法**：

| 方法 | 功能 | 参数 | 返回值 |
|------|------|------|--------|
| `addFunction(DruleFunction)` | 添加函数 | 函数对象 | boolean |
| `addImport(String)` | 添加包/类引入 | 包/类名 | void |
| `addGlobal(String, String)` | 添加全局变量 | 标识符, 类型 | void |
| `compile()` | 编译规则 | - | DruleCompileStructure |
| `compileRule(DruleBlock)` | 编译单个规则块 | 规则块 | String |
| `validateRules()` | 校验规则结构 | - | ValidateResult |

**使用示例**：

```java
// 配置好规则块集合
List<DruleBlock> rules = ...;
// 入参对象的树形结构
TreeNode inNode = TreeNode.treeNode(TestIn.class);
// 出参对象的树形结构
TreeNode outNode = TreeNode.treeNode(TestOut.class);

// 构建默认编译器
DefaultDruleCompile compiler = new DefaultDruleCompile(rules, inNode, outNode);

// 校验规则结构
ValidateResult validate = compiler.validateRules();
if (validate.isSuccess()) {
    // 执行编译
    DruleCompileStructure result = compiler.compile();
    // 输出最终编译的 DRL 内容
    System.out.println(result.toDrl());
}
```

#### 2.2 DruleChineseTranslation - 中文转译器

`DruleChineseTranslation` 用于将规则块转译为中文文本，便于业务人员理解。

**使用示例**：

```java
// 构建中文转译器
ChineseTranslation translator = DruleChineseTranslation.buildTranslation(rules, inNode, outNode);

// 方式一：获取转译后的规则结构体集合
List<TranslatedRuleText> translatedRules = translator.translateRules();

// 方式二：获取转译后的规则文本内容
String translatedText = translator.generateText();
```

#### 2.3 DiffHandleUtils - 差异对比工具

用于对比规则内容的差异，支持生成可视化 HTML 文件。

```java
// 需要对比的内容
List<String> oldContent = ...;
List<String> newContent = ...;

// 执行对比
List<String> diffList = DiffHandleUtils.diffList(oldContent, newContent, "原内容", "新内容");

// 生成可视化 HTML 文件
DiffHandleUtils.generateDiffHtml(diffList, "/path/to/output.html");
```

#### 2.4 FieldUsedLocator - 字段定位器

用于定位出入参字段被使用在哪些规则块（`DruleBlock`）中。

```java
// 使用默认的字段匹配器
List<MatchedField> result = FieldUsedLocator.simpleLocate(druleBlockList, nodes);

// 使用自定义字段匹配器
List<MatchedField> result = FieldUsedLocator.locate(druleBlockList, nodes, customMatcher);
```

### 3. drule-parse 模块

#### 3.1 DruleContentParser - DRL 解析器

`DruleContentParser` 用于解析 DRL 文本内容，将其转换为结构化的 `DrlFile` 对象。

**支持的 DRL 元素类型**：

| 类型 | 说明 | 示例 |
|------|------|------|
| `PACKAGE` | 包声明 | `package com.example;` |
| `IMPORT` | 导入声明 | `import com.example.Model;` |
| `GLOBAL` | 全局变量 | `global Logger log;` |
| `RULE` | 规则定义 | `rule "test" when ... then ... end` |
| `FUNCTION` | 函数定义 | `function void test() { ... }` |
| `DECLARE` | 类型声明 | `declare Person ... end` |
| `QUERY` | 查询定义 | `query "findPerson" ... end` |
| `COMMENT` | 注释 | `// 单行注释` 或 `/* 多行注释 */` |

**使用示例**：

```java
// 解析 DRL 文本
DrlFile drlFile = DruleContentParser.parseDrl(drlText);
drlFile.parse();

// 获取所有规则
List<DrlTree> rules = drlFile.getDrlTrees(DrlType.RULE);

// 获取所有导入
List<DrlTree> imports = drlFile.getDrlTrees(DrlType.IMPORT);
```

### 4. drule-execute 模块

#### 4.1 RuleService - 规则服务

`RuleService` 是规则服务的核心接口，用于配置和构建规则会话。

**创建方式一：构造器方法**

```java
RuleService ruleService = new RuleServiceImpl("id01", "1.0.0", "cn.ahaoweb", null)
    // 添加规则内容（必要）
    .addContent(RuleType.RULE_BLOCK, drl)
    // 修改配置（可选）
    .addConfig(RuleServiceConfiguration.RULE_CONTENT_CACHE.PROPERTY_NAME,
               RuleServiceConfiguration.RULE_CONTENT_CACHE.OPEN.value())
    // 事实对象类型选择器（可选）
    .factClassSelector(new FactClassSelector() {
        @Override
        public Class inType() { return TestIn.class; }
        @Override
        public Class outType() { return TestOut.class; }
    })
    // 初始化（必要）
    .init();
```

**创建方式二：DruleServiceHelper（推荐）**

```java
RuleService ruleService = new DruleServiceHelper()
    .identifier("test_rule")
    .addContent(RuleType.RULE_BLOCK, drl)
    .addConfig(RuleServiceConfiguration.RULE_CONTENT_CACHE.CLOSE)
    .addConfig(RuleServiceConfiguration.EXECUTE_MODE.DEBUG)
    .getRuleService();
```

#### 4.2 RuleSession - 规则会话

`RuleSession` 用于执行规则，支持添加前置/后置处理器、监听器等。

**执行流程**：

```
┌─────────────────────────────────────────────────────────────────────────┐
│                          RuleSession 执行流程                            │
├─────────────────────────────────────────────────────────────────────────┤
│  1. enter()                    ──▶ 可扩展入口点                          │
│  2. preExecuteHandlers         ──▶ 执行前置处理器                        │
│  3. afterPreHandlers()         ──▶ 可扩展点                              │
│  4. listeners + 执行规则        ──▶ 添加监听器并执行规则                  │
│  5. afterExecuted()            ──▶ 可扩展点                              │
│  6. postExecuteHandlers        ──▶ 执行后置处理器                        │
│  7. afterPostHandlers()        ──▶ 可扩展点                              │
│  8. destroy()                  ──▶ 销毁会话                              │
│  9. exit()                     ──▶ 可扩展出口点                          │
└─────────────────────────────────────────────────────────────────────────┘
```

**使用示例**：

```java
// 创建规则会话
RuleSession session = ruleService.createSession()
    // 添加前置处理器
    .addPreExecuteHandler(new PreExecuteHandler<TestIn, TestOut>() {
        @Override
        public void preHandler(FactInfo<TestIn, TestOut> factInfo) {
            TestIn input = factInfo.getInput();
            input.setAge(10);
            System.out.println("前置处理器：" + input);
        }
    })
    // 添加后置处理器
    .addPostExecuteHandler(new PostExecuteHandler() {
        @Override
        public void postHandler(FactInfo factInfo) {
            TestOut output = (TestOut) factInfo.getOutput();
            System.out.println("后置处理器：" + output);
        }
    });

// 执行方式一：使用 FactInfo
FactInfo factInfo = FactInfo.FactInfoBuilder.builder()
    .input(new TestIn())
    .inputClass(TestIn.class)
    .inputName("testIn")
    .outputClass(TestOut.class)
    .build();
session.execute(factInfo);

// 执行方式二：直接传入对象
FactInfo result = session.execute(new TestIn(), new TestOut());
```

#### 4.3 RuleServiceScheduler - 规则服务调度器

`RuleServiceScheduler` 提供统一管理规则服务的功能，支持通过标识符或入参对象类型执行规则。

**使用方式一：通用流程**

```java
// 1. 构建调度器
RuleServiceScheduler scheduler = new RuleServiceScheduler();

// 2. 添加规则服务
scheduler.addService(ruleService1);
scheduler.addService("test2", ruleService2);

// 3. 配置会话（可选）
RuleSession session = scheduler.getRuleSession("test1");
session.addPreExecuteHandler(...);

// 4. 执行规则
scheduler.execute("test1", new TestIn());  // 通过标识符
scheduler.execute(new TestIn());           // 通过入参类型（需确保一一对应）
```

**使用方式二：动态流程**

```java
// 构建调度器，配置 RuleServiceConstructor
RuleServiceScheduler scheduler = new RuleServiceScheduler(new RuleServiceConstructor() {
    @Override
    public RuleService getRuleService(String identifier) {
        // 可从数据库等动态获取规则服务
        if ("test1".equals(identifier)) {
            return buildRuleService1();
        }
        return null;
    }
});

// 直接执行，调度器会自动获取规则服务
scheduler.execute("test1", new TestIn());
```

#### 4.4 AfterCreateSessionCallback - 会话创建回调

在规则会话创建后提供扩展点，允许执行自定义逻辑。

```java
RuleService ruleService = new DruleServiceHelper()
    .identifier("test")
    .addContent(RuleType.RULE_BLOCK, drl)
    .afterCreateSessionCallback(session -> {
        // 在会话创建后添加处理器
        session.addPreExecuteHandler(new PreExecuteHandler() {
            @Override
            public void preHandler(FactInfo factInfo) {
                log.info("执行前处理：{}", factInfo);
            }
        });
        return session;
    })
    .getRuleService();
```

## 📝 配置说明

### 规则条件运算符

| 运算符 | 符号 | 说明 | 示例 |
|--------|------|------|------|
| `eq` | `==` | 等于 | `name == "jack"` |
| `neq` | `!=` | 不等于 | `name != "jack"` |
| `lt` | `<` | 小于 | `age < 18` |
| `lte` | `<=` | 小于等于 | `age <= 18` |
| `gt` | `>` | 大于 | `age > 18` |
| `gte` | `>=` | 大于等于 | `age >= 18` |
| `left_contains` | `contains` | 包含（左） | `name contains "jack"` |
| `right_contains` | `contains` | 包含（右） | `"jack" contains name` |
| `not_left_contains` | `not contains` | 不包含（左） | `name not contains "jack"` |
| `not_right_contains` | `not contains` | 不包含（右） | `"jack" not contains name` |
| `in` | `in` | 存在于 | `name in ("jack", "mary")` |
| `not_in` | `not in` | 不存在于 | `name not in ("jack", "mary")` |
| `matches` | `matches` | 正则匹配 | `name matches "ja.*"` |
| `not_matches` | `not matches` | 正则不匹配 | `name not matches "ja.*"` |

### 运算符详细说明

#### eq、neq
等价于 Java 中的 `equals()` 和 `!equals()`。

#### lt、lte、gt、gte
关系运算 `<`、`<=`、`>`、`>=`。

#### left_contains、right_contains
- **包含（左）**：参数字段在左侧，如 `name contains "jack"`
- **包含（右）**：参数字段在右侧，如 `"jack" contains name`
- 支持 List 和字符串类型

#### in、not_in
相当于 SQL 中的 `IN` 操作符，用于检查某个值是否包含在给定的多个可能值中。

#### matches、not_matches
与指定的 Java 正则表达式匹配或不匹配。

## 🎋 版本历史

| 版本 | 主要更新 |
|------|----------|
| **release-1.7** | 新增 `drule-parse` 模块，支持 DRL 文件解析和语法树构建 |
| **release-1.6** | 1. 新增字段定位器 `FieldUsedLocator`<br/>2. 新增规则执行异常处理器 `RuleExecuteExceptionHandler`<br/>3. 新增会话创建回调 `AfterCreateSessionCallback` |
| **release-1.5** | 1. 新增 8 种条件运算符<br/>2. 规则服务调度器支持通过入参对象执行规则 |
| **release-1.4** | 1. 新增规则服务调度器 `RuleServiceScheduler`<br/>2. 新增事实对象类型选择器 `factClassSelector` |
| **release-1.3** | 1. 新增中文转译器 `ChineseTranslation`<br/>2. 新增文本差异对比工具 `DiffHandleUtils`<br/>3. 修复节点类型中布尔类型问题 |
| **release-1.2** | 1. 新增规则校验方法 `validateRules`<br/>2. 根据类型选择不同的值处理逻辑 |
| **release-1.1** | 新增 `drule-execute` 模块，统一执行框架 |
| **release-1.0** | 初版发布，支持规则对象配置和规则编译功能 |

## 📦 合作与支持

感谢大家对此项目的支持，如有其他需要，可直接联系本人。

- **QQ**：1298894906
- **邮箱**：1298894906@qq.com

## 📄 License

[MIT License](LICENSE)