JQuick-Java快速入门教程：轻量级规则引擎环境搭建与首个脚本运行实战

前言

在传统 Java 开发中，业务规则往往以硬编码 if-else 的形式散落在 Service 层，每次调整阈值、权重都需要改代码、编译、重启部署，迭代成本极高。JQuick-Java 是一款面向规则引擎的轻量级类 Java 脚本语言，它以声明式配置驱动开发，支持运行时动态加载、解析与执行业务规则，让"规则即配置、改完即生效"成为现实。本文作为 JQuick-Java 快速入门教程，带你从环境搭建到运行第一个脚本，完整走通落地链路。

核心技术原理

JQuick-Java 采用编译技术生成词法/语法解析器（JQuickJavaLexer / JQuickJavaParser），将类 Java 脚本解析为语法树后，由 JQuickJavaCommonVisitor 驱动的分层 Visitor 执行链逐步求值：字面量 → 表达式 → 控制结构 → 方法调用 → 作用域 → 函数注册。整体执行入口是 JQuickJavaExecutor，而开箱即用的封装则是统一入口类 JQuickJava，它把包声明、变量初始化、脚本执行、规则代理整合成一条链式 API。

实战代码演示

1. 引入 Maven 依赖

xml 复制代码

<dependency>
    <groupId>io.github.paohaijiao</groupId>
    <artifactId>jquick-java</artifactId>
    <version>2.5.0</version>
</dependency>

2. 运行第一个 JQuick 脚本

java 复制代码

import com.github.paohaijiao.xml.JQuickJava;

public class QuickStart {
    public static void main(String[] args) {
        Object result = JQuickJava.create()
                .importPackage("java.lang.String", "type1")
                .variable("base", 60)
                .execute(
                        "type1 def a(int:a,int:b) {\n" +
                        "   int t = a + b;\n" +
                        "   type1 p = java.lang.String::valueOf(int:t);\n" +
                        "   return p;\n" +
                        "}\n" +
                        "int c=1;\n" +
                        "int d=2;\n" +
                        "this.a(int:c,int:d);"
                );
        System.out.println("execute result: " + result); // 输出 3
    }
}

该示例与官方测试 JQuickJavaTest#testEntryExecute 完全一致：定义函数 a，调用 java.lang.String::valueOf 静态方法完成 int→String 转换，最终返回字符串 "3"。

3. 更原生的脚本写法

jquick 复制代码

import List<java.lang.String> as StringList;
StringList list=["A","B","C"];

这是 README 中的"第一个 JQuick 脚本"：声明泛型导入并把 List 字面量赋给变量，语法与 Java 高度一致。

核心技术细节解析

统一入口 JQuickJava ：create() 创建默认实例；execute(scriptBody) 直接执行脚本主体，包声明与初始化语句由入口统一注入（buildScript 拼接 import + init + body）。
静态上下文隔离 ：JQuickJavaParser.context 是静态字段，execute 执行前后会执行 restoreStaticParserContext 备份/恢复，避免一次脚本的变量污染后续调用------这是入门阶段最容易踩的坑之一。
函数定义语法 ：返回类型 def 函数名(类型:参数名, ...) { ... }，参数采用 类型:参数名 显式强类型声明，例如 int def sum(int:a, int:b)。

常见踩坑与解决方案

重复执行报 "already has been imported" ：同 JVM 内反复执行脚本，全局导入容器会重复注册。入口通过 registerImports() 幂等注册并跳过已存在的别名来解决，遇到该异常请优先改用 JQuickJava.create() 入口。
泛型导入无法自动起别名 ：importPackage("List<java.lang.String>") 会抛 IllegalArgumentException，必须显式指定别名，如 importPackage("List<java.lang.String>", "StringList")。
变量未定义 ：脚本引用了 JContext/环境变量中不存在的变量，解析器会打印 Undefined variable: xxx 并返回 null。请先通过 variable()/env() 注入再执行。

最佳实践

单例复用 JQuickJava 入口实例，避免重复解析；执行链本身有 ASM 调用器缓存，但脚本解析仍是主要开销。
常量用 constant()、上下文变量用 variable()、运行时环境变量用 env()，三者语义不同，生产环境请按用途区分。
业务规则建议直接走 createApi(接口, xml路径) 的 XML 代理模式，execute 适合快速验证与一次性计算。

总结

通过本文的 JQuick-Java 快速入门教程，你已经完成环境搭建、首个脚本运行与核心 API 初体验。JQuick-Java 用"类 Java 语法 + 声明式配置"把规则从代码中剥离出来，适用于企业信用评级、风险决策、动态校验等典型规则引擎落地场景，是低代码规则引擎选型的轻量之选。