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

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

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

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

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

// 开启沙箱模式，禁止所有 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.getRiskName());
                }
            } 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);
    }
}

🔍 注意事项与调试

实际使用中，请注意以下几点：

1. 性能：对高频执行的规则使用预编译缓存（如上例所示），避免重复解析。
2. 错误处理：务必捕获 QLException，并根据业务需求转换为友好提示。
3. 调试：在开发阶段，可以通过 runner.setIsTrace(true) 开启执行轨迹跟踪，方便排查逻辑问题。

🤔 如何选择与进一步学习

QLExpress 适合规则简单、对性能敏感、需要快速集成的场景。如果你的规则极其复杂或需要完整的 DSL 支持，可以考虑更重的规则引擎（如 Drools）。

进一步学习，你可以阅读官方 GitHub 仓库的文档和测试用例。