QLExpress Java动态脚本引擎使用指南

QLExpress是阿里开源的一款轻量级Java动态脚本引擎，常用于规则判断、公式计算等需要动态逻辑的场景。下面是其核心使用方法和一个实际项目集成示例。

🚀 快速入门

以下表格汇总了从安装到执行的关键步骤：

步骤	关键内容	说明与示例
1. 添加依赖	Maven坐标	在`pom.xml`中添加：`<dependency>` `<groupId>com.alibaba</groupId>` `<artifactId>QLExpress</artifactId>` `<version>3.3.4</version>` `</dependency>`
2. 核心API	`ExpressRunner`	核心执行器，负责脚本的编译与运行。
`DefaultContext`	用于向脚本传递参数的上下文对象。
3. 执行脚本	`execute`方法	基础执行代码： `ExpressRunner runner = new ExpressRunner();` `DefaultContext<String, Object> context = new DefaultContext<>();` `context.put("a", 10);` `Object result = runner.execute("a * 2", context, null, true, false);` `System.out.println(result); // 输出 20`

🧩 核心功能与技巧

掌握基础后，你可以利用QLExpress更灵活地处理复杂逻辑：

自定义函数与方法注入
如果脚本需要调用特定业务逻辑，可以注入自定义函数或Java方法。

// 1. 添加自定义函数 runner.addFunction("isVIP", new Operator() { @Override public Object executeInner(Object[] list) { Integer level = (Integer) list[0]; return level != null && level >= 3; } }); // 脚本中调用：isVIP(userLevel) // 2. 注入对象方法（例如StringUtils） runner.addFunctionOfServiceMethod("strLength", new StringUtils(), "length", new Class[]{String.class}, null); // 脚本中调用：strLength('hello')

对于更复杂的方法调用，QLExpress支持通过addFunctionOfClassMethod或绑定静态方法。

使用宏定义简化脚本
对于频繁使用的复杂表达式，可以定义为宏来简化脚本编写。

runner.addMacro("是否优质客户", "平均消费 > 1000 && 投诉次数 < 2"); // 后续脚本中可直接使用：“是否优质客户” 作为判断条件

安全控制至关重要
如果脚本允许外部输入，必须开启安全沙箱模式，防止恶意代码调用。

java

// 开启沙箱模式，禁止所有Java类的直接调用 QLExpressRunStrategy.setSandBoxMode(true); // 通过白名单，仅允许调用安全的方法 QLExpressRunStrategy.addSecureMethod(SafeService.class, "safeMethod");

💡 项目集成示例：动态风控规则

以搭建一个简单的风控规则引擎为例，展示如何将QLExpress集成到Spring Boot项目中。

第一步：设计规则模型

@Data public class RiskRule { private String ruleId; // 规则ID，如 "RULE_AMOUNT" private String ruleName; // 规则名称，如 "交易金额阈值" private String expression; // QL表达式，如 "amount > 10000" private String riskLevel; // 命中后的风险等级，如 "HIGH" private Integer priority; // 执行优先级 }

第二步：封装规则执行服务

@Service public class RiskEngineService { // 缓存编译后的规则，提升性能 private Map<String, IExpress<String>> ruleCache = new ConcurrentHashMap<>(); private ExpressRunner runner = new ExpressRunner(); public RiskResult evaluate(Transaction transaction, List<RiskRule> rules) { // 1. 准备脚本上下文，注入交易参数 DefaultContext<String, Object> context = new DefaultContext<>(); context.put("amount", transaction.getAmount()); context.put("userId", transaction.getUserId()); // ... 注入其他参数 // 2. 按优先级排序并执行规则 rules.sort(Comparator.comparing(RiskRule::getPriority)); for (RiskRule rule : rules) { try { IExpress<String> compiledExpress = ruleCache.computeIfAbsent( rule.getRuleId(), id -> runner.compile(rule.getExpression(), null) // 编译并缓存 ); // 3. 执行规则 Boolean isHit = (Boolean) compiledExpress.execute(context, null, true, false); if (isHit != null && isHit) { return new RiskResult(true, rule.getRiskLevel(), rule.getRuleName()); } } catch (Exception e) { // 记录规则执行异常，但不中断流程 log.error("执行规则[{}]异常", rule.getRuleId(), e); } } // 4. 所有规则均未命中，返回安全 return RiskResult.pass(); } }

第三步：模拟交易测试

@RestController @RequestMapping("/risk") public class RiskController { @Autowired private RiskEngineService riskEngineService; @Autowired private RiskRuleRepository ruleRepository; // 假设从数据库加载规则 @PostMapping("/evaluate") public RiskResult evaluate(@RequestBody Transaction transaction) { List<RiskRule> activeRules = ruleRepository.findActiveRules(); return riskEngineService.evaluate(transaction, activeRules); } }