档案软件轻量规则引擎从零搭建到生产环境落地全流程实操指南

一、前置准备

所有工具均给出明确版本及获取方式，无需额外搜索：

• JDK 1.8.301+：下载地址 https://adoptium.net/zh-CN/temurin/releases/?version=8
• Maven 3.6.3+：下载地址 https://maven.apache.org/download.cgi
• 现有档案系统：SpringBoot 2.7.x 版本（其他版本适配方式见最后排查部分）
• 规则引擎选型：EasyRule 4.1.0（轻量无冗余，适合档案类规则复杂度场景）

二、基础环境搭建

2.1 依赖导入

在项目pom.xml中加入以下可直接复制的依赖：

```xml org.jeasy easy-rules-core 4.1.0 org.jeasy easy-rules-yaml 4.1.0 org.springframework.boot spring-boot-starter-web 2.7.14 ```

2.2 规则引擎初始化配置

在config目录下新建RuleEngineConfig.java，完整代码如下：

```java package com.archives.system.config; import org.jeasy.rules.api.RulesEngine; import org.jeasy.rules.core.DefaultRulesEngine; import org.jeasy.rules.core.DefaultRulesEngineParameters; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class RuleEngineConfig { @Bean public RulesEngine rulesEngine() { // 规则引擎参数配置，可根据业务调整 DefaultRulesEngineParameters parameters = new DefaultRulesEngineParameters(); parameters.setSkipOnFirstAppliedRule(false); // 匹配到第一条规则后继续执行后续规则 parameters.setSkipOnFirstFailedRule(false); // 某条规则执行失败后继续执行后续规则 parameters.setSkipOnFirstNonTriggeredRule(false); // 某条规则未触发后继续执行后续规则 return new DefaultRulesEngine(parameters); } } ```

必须将配置类放在SpringBoot启动类的扫描路径下，否则规则引擎无法注入

三、档案业务规则配置

在resource目录下新建rules文件夹，所有规则文件均存放在该目录下，以下为档案系统3个高频规则的可直接复用配置：

3.1 归档期限自动赋值规则

新建archive-term.yml，内容如下：

```yaml name: "归档期限自动赋值规则" description: "文书类档案未填写保管期限时自动赋值为30年" priority: 1 condition: "archives.getType().equals(\"文书类\") && archives.getTerm() == null" actions: - "archives.setTerm(\"30年\");" ```

3.2 密级校验规则

新建secret-check.yml，内容如下：

```yaml name: "密级校验规则" description: "绝密级档案仅允许保密部门上传" priority: 2 condition: "archives.getSecretLevel().equals(\"绝密\") && !archives.getDepartment().equals(\"保密部\")" actions: - "throw new IllegalArgumentException(\"非保密部门无权限上传绝密级档案\");" ```

3.3 借阅权限判定规则

新建borrow-permission.yml，内容如下：

```yaml name: "借阅权限判定规则" description: "普通员工仅允许借阅公开级、内部级档案" priority: 3 condition: "user.getRole().equals(\"普通员工\") && (archives.getSecretLevel().equals(\"机密\") || archives.getSecretLevel().equals(\"绝密\"))" actions: - "throw new IllegalArgumentException(\"您无权限借阅该涉密档案\");" ```

四、接入现有档案系统

4.1 规则加载工具类

新建RuleLoader.java，用于动态加载指定目录下的所有规则文件：

```java package com.archives.system.utils; import org.jeasy.rules.api.Facts; import org.jeasy.rules.api.Rules; import org.jeasy.rules.yaml.YamlRuleDefinitionReader; import org.springframework.core.io.Resource; import org.springframework.core.io.support.PathMatchingResourcePatternResolver; import java.io.InputStreamReader; import java.nio.charset.StandardCharsets; public class RuleLoader { public static Rules loadRules(String path) throws Exception { Rules rules = new Rules(); PathMatchingResourcePatternResolver resolver = new PathMatchingResourcePatternResolver(); Resource[] resources = resolver.getResources(path); YamlRuleDefinitionReader reader = new YamlRuleDefinitionReader(); for (Resource resource : resources) { try (InputStreamReader isr = new InputStreamReader(resource.getInputStream(), StandardCharsets.UTF_8)) { rules.register(reader.read(isr)); } } return rules; } } ```

4.2 业务接口调用示例

以档案上传接口为例，插入规则校验逻辑，代码如下：

```java @RestController @RequestMapping("/archives") public class ArchivesController { @Autowired private RulesEngine rulesEngine; @Autowired private ArchivesService archivesService; @PostMapping("/upload") public Result upload(@RequestBody Archives archives) throws Exception { // 加载所有规则 Rules rules = RuleLoader.loadRules("classpath:rules/.yml"); // 构造事实参数 Facts facts = new Facts(); facts.put("archives", archives); // 执行规则前必须清空上一次请求的用户参数，避免参数残留 facts.remove("user"); facts.put("user", LoginContext.getCurrentUser()); // 执行规则 rulesEngine.fire(rules, facts); // 规则执行完成后执行后续归档逻辑 archivesService.save(archives); return Result.success(); } } ```

五、测试验证

执行以下curl命令可直接验证规则是否生效：

5.1 归档期限规则验证

```bash curl -X POST http://localhost:8080/archives/upload \ -H "Content-Type: application/json" \ -d '{"type":"文书类","term":null,"secretLevel":"内部","department":"办公室"}' ```

返回成功后查询数据库，对应档案的term字段应自动赋值为“30年”

5.2 密级校验规则验证

```bash curl -X POST http://localhost:8080/archives/upload \ -H "Content-Type: application/json" \ -d '{"type":"文书类","term":"永久","secretLevel":"绝密","department":"财务部"}' ```

应直接返回错误信息：“非保密部门无权限上传绝密级档案”

六、生产环境优化

• 规则热更新：新增定时任务，每30秒重新加载一次规则文件，无需重启系统即可更新规则，直接调用RuleLoader.loadRules方法实现即可
• 性能优化：将加载后的规则对象存入Caffeine本地缓存，缓存过期时间设置为30秒，避免每次请求都重新加载规则文件
• 规则监控：在规则执行前后加入日志，记录每条规则的触发时间、触发条件、执行结果，方便排查业务问题

七、常见问题排查

• 规则不触发：首先检查规则文件路径是否正确，其次检查规则条件中的字段名、字段类型是否和传入的facts参数完全一致，最后检查规则优先级是否设置正确
• 规则执行报错：检查规则的actions中的语法是否符合Java表达式语法，所有字符串必须用双引号包裹，特殊字符需要转义
• SpringBoot3.x适配：将EasyRule版本升级到4.2.0，同时替换所有javax依赖为jakarta依赖即可正常运行