由阿里的电商业务规则演化而来的嵌入式Java动态脚本工具,在阿里集团有很强的影响力,同时为了自身不断优化、发扬开源贡献精神,于2012年开源。
在基本的表达式计算的基础上,还有以下特色:
-
灵活的自定义能力,通过 Java API 自定义函数和操作符,可以快速实现业务规则的 DSL
-
兼容最新的 Java 语法,方便 Java 程序员快速熟悉。熟悉类 C 语言的业务人员使用起来也会非常顺手
-
原生支持 JSON,快捷定义复杂数据结构
-
友好的报错提示,无论是编译还是运行时错误,都能精确友好地提示错误位置
-
独一无二的表达式追踪功能,可以追踪表达式在中间节点计算的值,方便业务人员或者 AI 对线上规则的计算结果进行归因分析
-
默认安全,脚本默认不允许和应用代码进行交互,如果需要交互,也可以自行定义安全的交互方式
-
解释执行,不占用 JVM 元空间,可以开启缓存提升解释性能
-
代码精简,依赖最小,适合所有java的运行环境
QLExpress4 作为 QLExpress 的最新演进版本,基于 Antlr4 重写了解析引擎,将原先的优点进一步发扬光大,新增了大量特色功能,彻底拥抱函数式编程,在性能和表达能力上都进行了进一步增强。
如果项目还是使用旧版本的 QLExpress,可以跳转 branch_version_3.x.x 维护分支查看旧版文档。如需升级可以参考 附录一-升级指南
场景举例:
-
电商优惠券规则配置:通过 QLExpress 自定义函数和操作符快速实现优惠规则 DSL,供运营人员根据需求自行动态配置
-
表单搭建控件关联规则配置:表单搭建平台允许用户拖拽控件搭建自定义的表单,利用 QLExpress 脚本配置不同控件间的关联关系
-
流程引擎条件规则配置
-
广告系统计费规则配置
......
新版本并不是对旧版本的简单功能重构,而是我们基于对用户需求的洞察,对下一代规则表达式引擎的探索。拥有许多非常实用,但是在其他引擎中缺失的重要功能。
在业务人员完成规则脚本的配置后,很难对其线上执行情况进行感知。比如电商的促销规则,要求用户满足规则 isVip && 未登录10天以上。到底有多少线上用户是被 vip 条件拦截,又有多少用户是因为登录条件被拦截?这还是只是仅仅两个条件的简单规则,实际线上情况则更加复杂。
线上规则执行情况的追踪,不仅仅可以帮助业务人员了解线上的实际情况,排查和修复问题。其沉淀的数据也非常有价值,可以用于后续的规则优化和业务决策。以下是某个规则平台,基于 QLExpress4 的表达式追踪能力,对规则进行归因分析与附注的决策的产品简化图:
归因分析的原理在于利用 QLExpress4 的表达式追踪能力,获得表达式在计算过程中每个中间结果的值, 据此判断表达式最终运行结果产生的原因。
具体使用方法参考:表达式计算追踪
QLExpress4 原生支持 JSON 语法,可以快捷定义复杂的数据结构。
JSON 数组代表列表(List),而 JSON 对象代表映射(Map),也可以直接定义复杂对象。
产品上可以基于该特性实现 JSON 映射规则。让用户可以便捷地定义从一个模型向另一个模型的映射关系。以下是某个规则平台,基于该能力实现的模型映射产品简化图:
具体使用方法参考:方便语法元素
正常情况下,脚本执行需要的全部信息都在 context 中。context 中的 key 可以在脚本中作为变量引用,最终传递给自定义函数或者操作符。
但是出于安全,或者方便使用等因素考虑。有些信息并不希望用户通过变量引用到,比如租户名,密码等等。
此时可以通过附件(attachments)将这部分信息传递给自定义函数或者操作符使用。
具体使用方法参考:添加自定义函数与操作符 其中 hello 自定义函数根据附件中租户不同,返回不同的欢迎信息的示例。
函数被提升为 QLExpress4 中的第一等公民,可以作为变量使用,也可以作为函数的返回值。并且可以很容易地和 Java 中常见的函数式 API(比如 Stream) 结合使用。
以下是一个简单的 QLExpress 示例脚本:
add = (a, b) -> { return a + b; }; i = add(1,2); assert(i == 3);
更多使用方法参考:
QLExpress4 支持省略分号,让表达式更加简洁。具体参考 分号
<dependency> <groupId>com.alibaba</groupId> <artifactId>qlexpress4</artifactId> <version>4.0.9</version> </dependency>
环境要求:
-
JDK 8 或更高版本
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); Map<String, Object> context = new HashMap<>(); context.put("a", 1); context.put("b", 2); context.put("c", 3); Object result = express4Runner.execute("a + b * c", context, QLOptions.DEFAULT_OPTIONS).getResult(); assertEquals(7, result);
更多的表达式执行方式见文档 表达式执行
最简单的方式是通过 Java Lambda 表达式快速定义函数/操作符的逻辑:
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); // custom function express4Runner.addVarArgsFunction("join", params -> Arrays.stream(params).map(Object::toString).collect(Collectors.joining(","))); Object resultFunction = express4Runner.execute("join(1,2,3)", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS).getResult(); assertEquals("1,2,3", resultFunction); // custom operator express4Runner.addOperatorBiFunction("join", (left, right) -> left + "," + right); Object resultOperator = express4Runner.execute("1 join 2 join 3", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS).getResult(); assertEquals("1,2,3", resultOperator);
如果自定义函数的逻辑比较复杂,或者需要获得脚本的上下文信息,也可以通过继承 CustomFunction 的方式实现。
比如下面的 hello 自定义函数,根据租户不同,返回不同的欢迎信息:
package com.alibaba.qlexpress4.test.function; import com.alibaba.qlexpress4.runtime.Parameters; import com.alibaba.qlexpress4.runtime.QContext; import com.alibaba.qlexpress4.runtime.function.CustomFunction; public class HelloFunction implements CustomFunction { @Override public Object call(QContext qContext, Parameters parameters) throws Throwable { String tenant = (String)qContext.attachment().get("tenant"); return "hello," + tenant; } }
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); express4Runner.addFunction("hello", new HelloFunction()); String resultJack = (String)express4Runner.execute("hello()", Collections.emptyMap(), // Additional information(tenant for example) can be brought into the custom function from outside via attachments QLOptions.builder().attachments(Collections.singletonMap("tenant", "jack")).build()).getResult(); assertEquals("hello,jack", resultJack); String resultLucy = (String)express4Runner .execute("hello()", Collections.emptyMap(), QLOptions.builder().attachments(Collections.singletonMap("tenant", "lucy")).build()) .getResult(); assertEquals("hello,lucy", resultLucy);
QLExpress4还支持通过QLExpress脚本添加自定义函数。需要注意的是,在函数外定义的变量(如示例中的defineTime)在函数定义时就已初始化完成,后续调用函数时不会重新计算该变量的值。
Express4Runner express4Runner = new Express4Runner(InitOptions.builder().securityStrategy(QLSecurityStrategy.open()).build()); BatchAddFunctionResult addResult = express4Runner.addFunctionsDefinedInScript( "function myAdd(a,b) {\n" + " return a+b;" + "}\n" + "\n" + "function getCurrentTime() {\n" + " return System.currentTimeMillis();\n" + "}" + "\n" + "defineTime=System.currentTimeMillis();\n" + "function defineTime() {\n" + " return defineTime;" + "}\n", ExpressContext.EMPTY_CONTEXT, QLOptions.DEFAULT_OPTIONS); assertEquals(3, addResult.getSucc().size()); QLResult result = express4Runner.execute("myAdd(1,2)", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS); assertEquals(3, result.getResult()); QLResult resultCurTime1 = express4Runner.execute("getCurrentTime()", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS); Thread.sleep(1000); QLResult resultCurTime2 = express4Runner.execute("getCurrentTime()", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS); assertNotSame(resultCurTime1.getResult(), resultCurTime2.getResult()); /* * The defineTime variable is defined outside the function and is initialized when the function is defined; * it is not recalculated afterward, so the value returned is always the time at which the function was defined. */ QLResult resultDefineTime1 = express4Runner.execute("defineTime()", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS); Thread.sleep(1000); QLResult resultDefineTime2 = express4Runner.execute("defineTime()", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS); assertSame(resultDefineTime1.getResult(), resultDefineTime2.getResult());
建议尽可能使用Java方式定义自定义函数,这样可以获得更好的性能和稳定性。
更多自定义语法元素的方式见文档 自定义语法元素
在不执行脚本的情况下,单纯校验语法的正确性,其中包含了操作符的限制校验,调用 check 并且捕获异常,如果捕获到 QLSyntaxException,则说明存在语法错误
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); try { express4Runner.check("a+b;\n(a+b"); fail(); } catch (QLSyntaxException e) { assertEquals(2, e.getLineNo()); assertEquals(4, e.getColNo()); assertEquals("SYNTAX_ERROR", e.getErrorCode()); // <EOF> represents the end of script assertEquals( "[Error SYNTAX_ERROR: mismatched input '<EOF>' expecting ')']\n" + "[Near: a+b; (a+b<EOF>]\n" + " ^^^^^\n" + "[Line: 2, Column: 4]", e.getMessage()); }
你可以使用 CheckOptions 配置更精细的语法校验规则,主要支持以下两个选项:
-
operatorCheckStrategy: 操作符校验策略,用于限制脚本中可以使用的操作符 -
disableFunctionCalls: 是否禁用函数调用,默认为 false
示例1:使用操作符校验策略(白名单)
// Create a whitelist of allowed operators Set<String> allowedOps = new HashSet<>(Arrays.asList("+", "*")); // Configure check options with operator whitelist CheckOptions checkOptions = CheckOptions.builder().operatorCheckStrategy(OperatorCheckStrategy.whitelist(allowedOps)).build(); // Create runner and check script with custom options Express4Runner runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); runner.check("a + b * c", checkOptions); // This will pass as + and * are allowed
示例2:禁用函数调用
// Create a runner Express4Runner runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); // Create options with function calls disabled CheckOptions options = CheckOptions.builder().disableFunctionCalls(true).build(); // Script with function call String scriptWithFunctionCall = "Math.max(1, 2)"; // Use custom options to check script try { runner.check(scriptWithFunctionCall, options); } catch (QLSyntaxException e) { // Will throw exception as function calls are disabled }
脚本中使用的变量有的是脚本内生,有的是需要从外部通过 context 传入的。
QLExpress4 提供了一个方法,可以解析出脚本中所有需要从外部传入的变量:
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); Set<String> outVarNames = express4Runner.getOutVarNames("int a = 1, b = 10;\n" + "c = 11\n" + "e = a + b + c + d\n" + "f+e"); Set<String> expectSet = new HashSet<>(); expectSet.add("d"); expectSet.add("f"); assertEquals(expectSet, outVarNames);
更多脚本依赖解析工具:
-
getOutFunctions: 解析所有需要从外部定义的函数 -
getOutVarAttrs:解析所有需要从外部传入变量及其涉及的属性,getOutVarNames的增强版本
QLExpress 内部会用 BigDecimal 表示所有无法用 double 精确表示数字,来尽可能地表示计算精度:
举例:0.1 在 double 中无法精确表示
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); Object result = express4Runner.execute("0.1", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS).getResult(); assertTrue(result instanceof BigDecimal);
通过这种方式能够解决一些计算精度问题:
比如 0.1+0.2 因为精度问题,在 Java 中是不等于 0.3 的。 而 QLExpress 能够自动识别出 0.1 和 0.2 无法用双精度精确表示,改成用 BigDecimal 表示,确保其结果等于0.3
assertNotEquals(0.3, 0.1 + 0.2, 0.0); assertTrue((Boolean)express4Runner.execute("0.3==0.1+0.2", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS) .getResult());
除了默认的精度保证外,还提供了 precise 开关,打开后所有的计算都使用BigDecimal,防止外部传入的低精度数字导致的问题:
Map<String, Object> context = new HashMap<>(); context.put("a", 0.1); context.put("b", 0.2); assertFalse((Boolean)express4Runner.execute("0.3==a+b", context, QLOptions.DEFAULT_OPTIONS).getResult()); // open precise switch assertTrue((Boolean)express4Runner.execute("0.3==a+b", context, QLOptions.builder().precise(true).build()) .getResult());
QLExpress4 默认采用隔离安全策略,不允许脚本访问 Java 对象的字段和方法,这确保了脚本执行的安全性。如果需要访问 Java 对象,可以通过不同的安全策略进行配置。
假设应用中有如下的 Java 类:
package com.alibaba.qlexpress4.inport; /** * Author: DQinYuan */ public class MyDesk { private String book1; private String book2; public String getBook1() { return book1; } public void setBook1(String book1) { this.book1 = book1; } public String getBook2() { return book2; } public void setBook2(String book2) { this.book2 = book2; } }
脚本执行的上下文设置如下:
MyDesk desk = new MyDesk(); desk.setBook1("Thinking in Java"); desk.setBook2("Effective Java"); Map<String, Object> context = Collections.singletonMap("desk", desk);
QLExpress4 提供了四种安全策略:
默认情况下,QLExpress4 采用隔离策略,不允许访问任何字段和方法:
// default isolation strategy, no field or method can be found Express4Runner express4RunnerIsolation = new Express4Runner(InitOptions.DEFAULT_OPTIONS); assertErrorCode(express4RunnerIsolation, context, "desk.book1", "FIELD_NOT_FOUND"); assertErrorCode(express4RunnerIsolation, context, "desk.getBook2()", "METHOD_NOT_FOUND");
通过黑名单策略,可以禁止访问特定的字段或方法,其他字段和方法可以正常访问:
// black list security strategy Set<Member> memberList = new HashSet<>(); memberList.add(MyDesk.class.getMethod("getBook2")); Express4Runner express4RunnerBlackList = new Express4Runner( InitOptions.builder().securityStrategy(QLSecurityStrategy.blackList(memberList)).build()); assertErrorCode(express4RunnerBlackList, context, "desk.book2", "FIELD_NOT_FOUND"); Object resultBlack = express4RunnerBlackList.execute("desk.book1", context, QLOptions.DEFAULT_OPTIONS).getResult(); Assert.assertEquals("Thinking in Java", resultBlack);
通过白名单策略,只允许访问指定的字段或方法,其他字段和方法都会被禁止:
// white list security strategy Express4Runner express4RunnerWhiteList = new Express4Runner( InitOptions.builder().securityStrategy(QLSecurityStrategy.whiteList(memberList)).build()); Object resultWhite = express4RunnerWhiteList.execute("desk.getBook2()", context, QLOptions.DEFAULT_OPTIONS).getResult(); Assert.assertEquals("Effective Java", resultWhite); assertErrorCode(express4RunnerWhiteList, context, "desk.getBook1()", "METHOD_NOT_FOUND");
开放策略允许访问所有字段和方法,类似于 QLExpress3 的行为,但需要注意安全风险:
// open security strategy Express4Runner express4RunnerOpen = new Express4Runner(InitOptions.builder().securityStrategy(QLSecurityStrategy.open()).build()); Assert.assertEquals("Thinking in Java", express4RunnerOpen.execute("desk.book1", context, QLOptions.DEFAULT_OPTIONS).getResult()); Assert.assertEquals("Effective Java", express4RunnerOpen.execute("desk.getBook2()", context, QLOptions.DEFAULT_OPTIONS).getResult());
注意:开放策略虽然提供了最大的灵活性,但也带来了安全风险。建议只在受信任的环境中使用,不建议用于处理终端用户输入的脚本。
建议直接采用默认策略,在脚本中不要直接调用 Java 对象的字段和方法。而是通过自定义函数和操作符的方式(参考 添加自定义函数与操作符),对嵌入式脚本提供系统功能。这样能同时保证脚本的安全性和灵活性,用户体验还更好。
如果确实需要调用 Java 对象的字段和方法,至少应该使用白名单策略,只提供脚本有限的访问权限。
至于黑名单和开放策略,不建议在外部输入脚本的场景使用,除非确保每个脚本都会经过审核。
需要放开安全策略,不建议用于终端用户输入
假设应用中有如下的 Java 类(com.alibaba.qlexpress4.QLImportTester):
package com.alibaba.qlexpress4; public class QLImportTester { public static int add(int a, int b) { return a + b; } }
在 QLExpress 中有如下两种调用方式。
Express4Runner express4Runner = new Express4Runner(InitOptions.builder() // open security strategy, which allows access to all Java classes within the application. .securityStrategy(QLSecurityStrategy.open()) .build()); // Import Java classes using the import statement. Map<String, Object> params = new HashMap<>(); params.put("a", 1); params.put("b", 2); Object result = express4Runner .execute("import com.alibaba.qlexpress4.QLImportTester;" + "QLImportTester.add(a,b)", params, QLOptions.DEFAULT_OPTIONS) .getResult(); Assert.assertEquals(3, result);
Express4Runner express4Runner = new Express4Runner(InitOptions.builder() .addDefaultImport( Collections.singletonList(ImportManager.importCls("com.alibaba.qlexpress4.QLImportTester"))) .securityStrategy(QLSecurityStrategy.open()) .build()); Object result = express4Runner.execute("QLImportTester.add(1,2)", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS) .getResult(); Assert.assertEquals(3, result);
除了用 ImportManager.importCls 导入单个类外,还有其他更方便的导入方式:
-
ImportManager.importPack直接导入包路径下的所有类,比如ImportManager.importPack("java.util")会导入java.util包下的所有类,QLExpress 默认就会导入下面的包-
ImportManager.importPack("java.lang") -
ImportManager.importPack("java.util") -
ImportManager.importPack("java.math") -
ImportManager.importPack("java.util.stream") -
ImportManager.importPack("java.util.function")
-
-
ImportManager.importInnerCls导入给定类路径里的所有内部类
QLExpress4 支持通过自定义 ClassSupplier 来指定类加载器,这在插件化架构、模块化应用等场景中非常有用。通过自定义类加载器,可以让 QLExpress 脚本访问特定 ClassLoader 中的类。
下面的示例展示了如何与 PF4J 插件框架集成,让 QLExpress 脚本能够访问插件中的类:
// Specify plugin directory (test-plugins directory under test resources) Path pluginsDir = new File("src/test/resources/test-plugins").toPath(); PluginManager pluginManager = new DefaultPluginManager(pluginsDir); pluginManager.loadPlugins(); pluginManager.startPlugins(); // Get the PluginClassLoader of the first plugin PluginWrapper plugin = pluginManager.getPlugins().get(0); ClassLoader pluginClassLoader = plugin.getPluginClassLoader(); // Custom class supplier using plugin ClassLoader ClassSupplier pluginClassSupplier = clsName -> { try { return Class.forName(clsName, true, pluginClassLoader); } catch (ClassNotFoundException | NoClassDefFoundError e) { return null; } }; InitOptions options = InitOptions.builder() .securityStrategy(QLSecurityStrategy.open()) .classSupplier(pluginClassSupplier) .build(); Express4Runner runner = new Express4Runner(options); String script = "import com.alibaba.qlexpress4.pf4j.TestPluginInterface; TestPluginInterface.TEST_CONSTANT"; Object result = runner.execute(script, Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS).getResult(); Assert.assertEquals("Hello from PF4J Plugin!", result.toString());
自定义 ClassSupplier 的典型应用场景:
-
插件化架构:让脚本能够访问插件中定义的类和接口
-
模块化应用:在 OSGi 等模块化框架中,让脚本访问特定模块的类
-
动态类加载:从远程仓库或动态生成的字节码中加载类
-
类隔离:使用不同的 ClassLoader 来实现类的隔离
通过 cache 选项可以开启表达式缓存,这样相同的表达式就不会重新编译,能够大大提升性能。
注意该缓存没有限制大小,只适合在表达式为有限数量的情况下使用:
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); // open cache switch express4Runner.execute("1+2", new HashMap<>(), QLOptions.builder().cache(true).build());
但是当脚本首次执行时,因为没有缓存,依旧会比较慢。
可以通过下面的方法在首次执行前就将脚本缓存起来,保证首次执行的速度:
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); express4Runner.parseToDefinitionWithCache("a+b");
注意该缓存的大小是无限的,业务上注意控制大小,可以调用 clearCompileCache 方法定期清空编译缓存。
QLExpress 使用 ANTLR4 作为解析引擎,ANTLR4 在运行时会构建 DFA (确定有限状态自动机) 缓存来加速后续的语法解析。这个缓存会占用一定的内存空间。
在某些内存敏感的场景下,可以通过调用 clearDFACache 方法来清除 DFA 缓存,释放内存。
重要警告: 清除 DFA 缓存会导致编译性能大幅下降,正常情况下不建议使用此方法。
在解析并缓存表达式后立即调用此方法,并确保后续所有执行都打开缓存选项以避免重新编译。示例代码如下:
/* * When the expression changes, parse it and add it to the expression cache; * after parsing is complete, call clearDFACache. */ Express4Runner runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); runner.parseToDefinitionWithCache(exampleExpress); runner.clearDFACache(); /* * All subsequent runs of this script must enable the cache option to ensure that re-compilation does not occur. */ for (int i = 0; i < 3; i++) { runner.execute(exampleExpress, ExpressContext.EMPTY_CONTEXT, QLOptions.builder().cache(true).build()); }
通过这种方式,可以在保证性能的同时,最大限度地降低内存占用。
可以给脚本设置一个超时时间,防止其中存在死循环或者其他原因导致应用资源被过量消耗。
下面的示例代码给脚本给脚本设置了一个 10ms 的超时时间:
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); try { express4Runner.execute("while (true) {\n" + " 1+1\n" + "}", Collections.emptyMap(), QLOptions.builder().timeoutMillis(10L).build()); fail("should timeout"); } catch (QLTimeoutException e) { assertEquals(QLErrorCodes.SCRIPT_TIME_OUT.name(), e.getErrorCode()); }
注意,出于系统性能的考虑,QLExpress 对于超时时间的检测是不准确的。特别是在回调Java代码中(比如自定义函数或者操作符)出现的超时,不会立刻被检测到。只有在执行完,回到 QLExpress 运行时后才会被检测到并中断执行。
利用 QLExpress 提供的扩展函数能力,可以给Java类中添加额外的成员方法。
扩展函数是基于 QLExpress 运行时实现的,因此仅仅在 QLExpress 脚本中有效。
下面的示例代码给 String 类添加了一个 hello() 扩展函数:
ExtensionFunction helloFunction = new ExtensionFunction() { @Override public Class<?>[] getParameterTypes() { return new Class[0]; } @Override public String getName() { return "hello"; } @Override public Class<?> getDeclaringClass() { return String.class; } @Override public Object invoke(Object obj, Object[] args) { String originStr = (String)obj; return "Hello," + originStr; } }; Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); express4Runner.addExtendFunction(helloFunction); Object result = express4Runner.execute("'jack'.hello()", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS).getResult(); assertEquals("Hello,jack", result); // simpler way to define extension function express4Runner.addExtendFunction("add", Number.class, params -> ((Number)params[0]).intValue() + ((Number)params[1]).intValue()); QLResult resultAdd = express4Runner.execute("1.add(2)", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS); assertEquals(3, resultAdd.getResult());
QLExpress 支持通过 QLAlias 注解给对象,字段或者方法定义一个或多个别名,方便非技术人员使用表达式定义规则。
下面的例子中,根据用户是否 vip 计算订单最终金额。
用户类定义:
package com.alibaba.qlexpress4.test.qlalias; import com.alibaba.qlexpress4.annotation.QLAlias; @QLAlias("用户") public class User { @QLAlias("是vip") private boolean vip; @QLAlias("用户名") private String name; public boolean isVip() { return vip; } public void setVip(boolean vip) { this.vip = vip; } public String getName() { return name; } public void setName(String name) { this.name = name; } }
订单类定义:
package com.alibaba.qlexpress4.test.qlalias; import com.alibaba.qlexpress4.annotation.QLAlias; @QLAlias("订单") public class Order { @QLAlias("订单号") private String orderNum; @QLAlias("金额") private int amount; public String getOrderNum() { return orderNum; } public void setOrderNum(String orderNum) { this.orderNum = orderNum; } public int getAmount() { return amount; } public void setAmount(int amount) { this.amount = amount; } }
通过 QLExpress 脚本规则计算最终订单金额:
Order order = new Order(); order.setOrderNum("OR123455"); order.setAmount(100); User user = new User(); user.setName("jack"); user.setVip(true); // Calculate the Final Order Amount Express4Runner express4Runner = new Express4Runner(InitOptions.builder().securityStrategy(QLSecurityStrategy.open()).build()); Number result = (Number)express4Runner .executeWithAliasObjects("用户.是vip? 订单.金额 * 0.8 : 订单.金额", QLOptions.DEFAULT_OPTIONS, order, user) .getResult(); assertEquals(80, result.intValue());
为了进一步方面非技术人员编写规则,QLExpress 提供 addAlias 给原始关键字,操作符和函数增加别名。让整个脚本的表述更加贴近自然语言。
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); // add custom function zero express4Runner.addFunction("zero", (String ignore) -> 0); // keyword alias assertTrue(express4Runner.addAlias("如果", "if")); assertTrue(express4Runner.addAlias("则", "then")); assertTrue(express4Runner.addAlias("否则", "else")); assertTrue(express4Runner.addAlias("返回", "return")); // operator alias assertTrue(express4Runner.addAlias("大于", ">")); // function alias assertTrue(express4Runner.addAlias("零", "zero")); Map<String, Object> context = new HashMap<>(); context.put("语文", 90); context.put("数学", 90); context.put("英语", 90); Object result = express4Runner .execute("如果 (语文 + 数学 + 英语 大于 270) 则 {返回 1;} 否则 {返回 零();}", context, QLOptions.DEFAULT_OPTIONS) .getResult(); assertEquals(0, result);
支持设置别名的关键字有:
-
if
-
then
-
else
-
for
-
while
-
break
-
continue
-
return
-
function
-
macro
-
new
-
null
-
true
-
false
注意:部分大家熟悉的用法其实是操作符,而不是关键字,比如
in操作符。而所有的操作符和函数默认就是支持别名的
宏是QLExpress中一个强大的代码复用机制,它允许用户定义一段可重用的脚本片段,并在需要时进行调用。与简单的文本替换不同,QLExpress的宏是基于指令回放的机制实现的,具有更好的性能和语义准确性。
宏特别适用于以下场景:
-
代码复用:将常用的脚本片段封装成宏,避免重复编写相同的逻辑
-
业务规则模板:定义标准的业务规则模板,如价格计算、权限检查等
-
流程控制:封装复杂的控制流程,如条件判断、循环逻辑等
-
DSL构建:作为构建领域特定语言的基础组件
宏可以通过两种方式定义:
1. 在脚本中使用 macro 关键字定义
macro add { c = a + b; } a = 1; b = 2; add; assert(c == 3);
2. 通过Java API添加
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); express4Runner.addMacro("rename", "name='haha-'+name"); Map<String, Object> context = Collections.singletonMap("name", "wuli"); Object result = express4Runner.execute("rename", context, QLOptions.DEFAULT_OPTIONS).getResult(); assertEquals("haha-wuli", result); // replace macro express4Runner.addOrReplaceMacro("rename", "name='huhu-'+name"); Object result1 = express4Runner.execute("rename", context, QLOptions.DEFAULT_OPTIONS).getResult(); assertEquals("huhu-wuli", result1);
宏与函数的区别:
特性
宏
函数
参数传递
无参数,依赖上下文变量
支持参数传递
性能
指令直接插入,无调用开销
有函数调用开销
作用域
共享调用者作用域
独立的作用域
适用场景
代码片段复用
逻辑封装和参数化
宏特别适合那些不需要参数传递、主要依赖上下文变量的代码片段复用场景,而函数更适合需要参数化和独立作用域的场景。
QLExpress4 相比 3 版本,宏特性的变化:
-
4 的宏实现更加接近通常编程语言中宏的定义,相当于将预定义的代码片段插入到宏所在的位置,与调用点位于同一作用域,宏中的
return,contine和break等可以影响调用方的控制流。但是 3 中的实现其实更加接近无参函数调用。 -
4 的宏无法作为变量使用,只有单独作为一行语句时才能被宏替换。因为宏可以是任意脚本,不一定是有返回值的表达式,作为变量时会存在语义问题。3 的宏本质是一个无参函数调用,所以常常被作为变量使用
如果想兼容 3 中的宏特性,建议使用 动态变量
常规的 "静态变量",是 context 中和 key 关联的固定的值。而动态变量可以是一个表达式,由另外一些变量计算而得。动态变量支持嵌套,即动态变量可以依赖另一个动态变量计算得到。
示例如下:
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); Map<String, Object> staticContext = new HashMap<>(); staticContext.put("语文", 88); staticContext.put("数学", 99); staticContext.put("英语", 95); QLOptions defaultOptions = QLOptions.DEFAULT_OPTIONS; DynamicVariableContext dynamicContext = new DynamicVariableContext(express4Runner, staticContext, defaultOptions); dynamicContext.put("平均成绩", "(语文+数学+英语)/3.0"); dynamicContext.put("是否优秀", "平均成绩>90"); // dynamic var assertTrue((Boolean)express4Runner.execute("是否优秀", dynamicContext, defaultOptions).getResult()); assertEquals(94, ((Number)express4Runner.execute("平均成绩", dynamicContext, defaultOptions).getResult()).intValue()); // static var assertEquals(187, ((Number)express4Runner.execute("语文+数学", dynamicContext, defaultOptions).getResult()).intValue());
如果打开相关选项,QLExpress4 就会在返回规则脚本计算结果的同时,返回一颗表达式追踪树。表达式追踪树的结构类似语法树,不同之处在于,它会在每个节点上记录本次执行的中间结果。
比如对于表达式 !true || myTest(a, 1),表达式追踪树的结构大概如下:
|| true
/ \
! false myTest
/ / \
true a 10 1可应用于多种场景:
-
方便业务人员对规则的计算结果进行分析排查
-
对线上判断为 false 的规则进行采样归类
-
AI 自动诊断和修复规则
节点计算结果会被放置到 ExpressionTrace 对象的 value 字段中。如果中间发生短路导致部分表达式未被计算,则 ExpressionTrace 对象的 evaluated 字段会被设置为 false。代码示例如下:
Express4Runner express4Runner = new Express4Runner(InitOptions.builder().traceExpression(true).build()); express4Runner.addFunction("myTest", (Predicate<Integer>)i -> i > 10); Map<String, Object> context = new HashMap<>(); context.put("a", true); QLResult result = express4Runner .execute("a && (!myTest(11) || false)", context, QLOptions.builder().traceExpression(true).build()); Assert.assertFalse((Boolean)result.getResult()); List<ExpressionTrace> expressionTraces = result.getExpressionTraces(); Assert.assertEquals(1, expressionTraces.size()); ExpressionTrace expressionTrace = expressionTraces.get(0); Assert.assertEquals("OPERATOR && false\n" + " | VARIABLE a true\n" + " | OPERATOR || false\n" + " | OPERATOR ! false\n" + " | FUNCTION myTest true\n" + " | VALUE 11 11\n" + " | VALUE false false\n", expressionTrace.toPrettyString(0)); // short circuit context.put("a", false); QLResult resultShortCircuit = express4Runner.execute("(a && true) && (!myTest(11) || false)", context, QLOptions.builder().traceExpression(true).build()); Assert.assertFalse((Boolean)resultShortCircuit.getResult()); ExpressionTrace expressionTraceShortCircuit = resultShortCircuit.getExpressionTraces().get(0); Assert.assertEquals( "OPERATOR && false\n" + " | OPERATOR && false\n" + " | VARIABLE a false\n" + " | VALUE true \n" + " | OPERATOR || \n" + " | OPERATOR ! \n" + " | FUNCTION myTest \n" + " | VALUE 11 \n" + " | VALUE false \n", expressionTraceShortCircuit.toPrettyString(0)); Assert.assertTrue(expressionTraceShortCircuit.getChildren().get(0).isEvaluated()); Assert.assertFalse(expressionTraceShortCircuit.getChildren().get(1).isEvaluated()); // in QLResult resultIn = express4Runner .execute("'ab' in ['cc', 'dd', 'ff']", context, QLOptions.builder().traceExpression(true).build()); Assert.assertFalse((Boolean)resultIn.getResult()); ExpressionTrace expressionTraceIn = resultIn.getExpressionTraces().get(0); Assert .assertEquals( "OPERATOR in false\n" + " | VALUE 'ab' ab\n" + " | LIST [ [cc, dd, ff]\n" + " | VALUE 'cc' cc\n" + " | VALUE 'dd' dd\n" + " | VALUE 'ff' ff\n", expressionTraceIn.toPrettyString(0));
注意,必须在新建
Express4Runner时将InitOptions.traceExpression选项设置为 true,同时在执行脚本时将QLOptions.traceExpression设置为 true,该功能才能生效。
也可以在不执行脚本的情况下获得所有表达式追踪点:
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); TracePointTree tracePointTree = express4Runner.getExpressionTracePoints("1+3+5*ab+9").get(0); Assert.assertEquals("OPERATOR +\n" + " | OPERATOR +\n" + " | OPERATOR +\n" + " | VALUE 1\n" + " | VALUE 3\n" + " | OPERATOR *\n" + " | VALUE 5\n" + " | VARIABLE ab\n" + " | VALUE 9\n", tracePointTree.toPrettyString(0));
支持的表达式追踪点类型以及对应子节点的含义如下:
节点类型
节点含义
子节点含义
OPERATOR
操作符
两侧操作数
FUNCTION
函数
函数参数
METHOD
方法
方法参数
FIELD
字段
取字段的目标对象
LIST
列表
列表元素
MAP
字段
无
IF
条件分支
condition表达式,then逻辑块和else逻辑块
RETURN
返回语句
返回表达式
VARIABLE
变量
无
VALUE
字面值
无
DEFINE_FUNCTION
定义函数
无
DEFINE_MACRO
定义宏
无
PRIMARY
暂时未继续下钻的其他复合值(比如字典,if等等)
无
STATEMENT
暂未继续下钻的其他复合语句(比如 while, for 等等)
无
QLExpress 并不需要专门与 Spring 集成,只需要一个 Express4Runner 单例,即可使用。
这里提供的 "集成" 示例,可以在 QLExpress 脚本中直接引用任意 Spring Bean。
这种方式虽然很方便,但是脚本权限过大,自由度太高。不再推荐使用,还是建议在 context 只放入允许用户访问的对象。
核心集成组件:
-
QLSpringContext: 实现了
ExpressContext接口,提供了对 Spring 容器的访问能力。它会优先从传入的 context 中查找变量,如果找不到则尝试从 Spring 容器中获取同名的 Bean。 -
QLExecuteService: 封装了 QLExpress 的执行逻辑,集成了 Spring 容器,方便在 Spring 应用中使用。
假设存在一个 Spring Bean, 名为 helloService:
package com.alibaba.qlexpress4.spring; import org.springframework.stereotype.Service; /** * Spring Bean example service class */ @Service public class HelloService { /** * Hello method that returns a greeting string * @return greeting string */ public String hello(String name) { return "Hello, " + name + "!"; } }
在脚本中调用该 Bean:
package com.alibaba.qlexpress4.spring; import org.junit.Assert; import org.junit.Test; import org.junit.runner.RunWith; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.test.context.ContextConfiguration; import org.springframework.test.context.junit4.SpringJUnit4ClassRunner; import java.util.HashMap; import java.util.Map; /** * HelloService unit test class */ @RunWith(SpringJUnit4ClassRunner.class) @ContextConfiguration(classes = SpringTestConfig.class) public class SpringDemoTest { @Autowired private QLExecuteService qlExecuteService; @Test public void qlExecuteWithSpringContextTest() { Map<String, Object> context = new HashMap<>(); context.put("name", "Wang"); String result = (String)qlExecuteService.execute("helloService.hello(name)", context); Assert.assertEquals("Hello, Wang!", result); } }
QLExpress4 兼容 Java8 语法的同时,也提供了很多更加灵活宽松的语法模式,帮助用户更快捷地编写表达式。
基于表达式优先的语法设计,复杂的条件判断语句也可以直接当作表达式使用。
在本章节中出现的代码片段都是 qlexpress 脚本,
assert 是测试框架往引擎中注入的断言方法,会确保其参数为 true。
assertErrCode 会确保其 lambda 参数表达式的执行一定会抛出含第二个参数 error code 的 QLException。
同时支持静态类型和动态类型:
-
变量声明时不写类型,则变量是动态类型,也同时是一个赋值表达式
-
变量声明如果写类型,则是静态类型,此时是一个变量声明语句
// Dynamic Typeing a = 1; a = "1"; // Static Typing int b = 2; // throw QLException with error code INCOMPATIBLE_ASSIGNMENT_TYPE when assign with incompatible type String assertErrorCode(() -> b = "1", "INCOMPATIBLE_ASSIGNMENT_TYPE")
列表(List),映射(Map)等常用语法元素在 QLExpress 中都有非常方便的构造语法糖:
// list l = [1,2,3] assert(l[0]==1) assert(l[-1]==3) // Underlying data type of list is ArrayList in Java assert(l instanceof ArrayList) // map m = { "aa": 10, "bb": { "cc": "cc1", "dd": "dd1" } } assert(m['aa']==10) // Underlying data type of map is LinkedHashMap in Java assert(m instanceof LinkedHashMap) // empty map emMap = {:} emMap['haha']='huhu' assert(emMap['haha']=='huhu')
通过 *. 操作符,可以快捷地对列表和映射进行处理,比如对列表元素进行取属性,或者获得映射的 key 列表和 value 列表:
list = [ { "name": "Li", "age": 10 }, { "name": "Wang", "age": 15 } ] // get field from list assert(list*.age==[10,15]) mm = { "aaa": 1, "bbb": 2 } // get map key value list assert(mm*.key==["aaa", "bbb"]) assert(mm*.value==[1, 2])
在映射中通过 @class key 指定类型的全限定名,就可以直接使用 JSON 创建复杂Java对象。比如下面的 MyHome , 是一个含有复杂嵌套类型 Java 类:
package com.alibaba.qlexpress4.inport; /** * Author: DQinYuan */ public class MyHome { private String sofa; private String chair; private MyDesk myDesk; private String bed; public String getSofa() { return sofa; } public void setSofa(String sofa) { this.sofa = sofa; } public String getChair() { return chair; } public MyDesk getMyDesk() { return myDesk; } public void setMyDesk(MyDesk myDesk) { this.myDesk = myDesk; } public void setChair(String chair) { this.chair = chair; } public String getBed() { return bed; } }
可以通过下面的 QLExpress 脚本,便捷创建:
注意,该特性需要参考 安全策略 打开安全选项,才能正常执行。
myHome = { '@class': 'com.alibaba.qlexpress4.inport.MyHome', 'sofa': 'a-sofa', 'chair': 'b-chair', 'myDesk': { 'book1': 'Then Moon and Sixpence', '@class': 'com.alibaba.qlexpress4.inport.MyDesk' }, // ignore field that don't exist 'notexist': 1234 } assert(myHome.getSofa()=='a-sofa') assert(myHome instanceof com.alibaba.qlexpress4.inport.MyHome) assert(myHome.getMyDesk().getBook1()=='Then Moon and Sixpence') assert(myHome.getMyDesk() instanceof com.alibaba.qlexpress4.inport.MyDesk)
对于未声明类型的数字, QLExpress会根据其所属范围自动从 int, long, BigInteger, double, BigDecimal 等数据类型中选择一个最合适的:
assert(2147483647 instanceof Integer); assert(9223372036854775807 instanceof Long); assert(18446744073709552000 instanceof BigInteger); // 0.25 can be precisely presented with double assert(0.25 instanceof Double); assert(2.7976931348623157E308 instanceof BigDecimal);
因此在自定义函数或者操作符时,建议使用 Number 类型进行接收,因为数字类型是无法事先确定的。
动态字符串是 QLExpress 为了增强字符串处理能力,在 4 版本新引入的能力。
支持 ${expression} 的格式在字符串中插入表达式计算:
如果想在字符串中原样保持
${expression},可以使用\$对$进行转义
a = 123 assert("hello,${a-1}" == "hello,122") // escape $ with \$ assert("hello,\${a-1}" == "hello,\${a-1}") b = "test" assert("m xx ${ if (b like 't%') { 'YYY' } }" == "m xx YYY")
如果还想让 QLExpress4 的字符串和 3 保持兼容性,不对插值表达式进行处理,可以在新建 Express4Runner 时直接关闭该特性:
Express4Runner express4RunnerDisable = new Express4Runner( // disable string interpolation InitOptions.builder().interpolationMode(InterpolationMode.DISABLE).build()); Assert.assertEquals("Hello,${ a + 1 }", express4RunnerDisable.execute("\"Hello,${ a + 1 }\"", context, QLOptions.DEFAULT_OPTIONS).getResult()); Assert.assertEquals("Hello,${lll", express4RunnerDisable.execute("\"Hello,${lll\"", context, QLOptions.DEFAULT_OPTIONS).getResult()); Assert.assertEquals("Hello,aaa $ lll\"\n\b", express4RunnerDisable.execute("\"Hello,aaa $ lll\\\"\n\b\"", context, QLOptions.DEFAULT_OPTIONS) .getResult());
利用动态字符串能力,QLExpress4 也可以作为一个轻量级模板引擎使用。
无需在脚本中手动添加字符串引号,直接调用 executeTemplate 渲染模板字符串:
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); Map<String, Object> context = new HashMap<>(); context.put("a", 1); context.put("b", 2); context.put("c", "test"); QLResult simpleTemplate = express4Runner.executeTemplate("a ${a};b ${b+2}", context, QLOptions.DEFAULT_OPTIONS); Assert.assertEquals("a 1;b 4", simpleTemplate.getResult()); QLResult conditionTemplate = express4Runner.executeTemplate("m xx ${\n" + " if (c like 't%') {\n" + " 'YYY'\n" + " }\n" + "}", context, QLOptions.DEFAULT_OPTIONS); Assert.assertEquals("m xx YYY", conditionTemplate.getResult()); QLResult multiLineTemplate = express4Runner.executeTemplate("m\n ${a}\n c", context, QLOptions.DEFAULT_OPTIONS); Assert.assertEquals("m\n 1\n c", multiLineTemplate.getResult()); QLResult escapeStringTemplate = express4Runner.executeTemplate("m \n\"haha\" d\"", context, QLOptions.DEFAULT_OPTIONS); Assert.assertEquals("m \n\"haha\" d\"", escapeStringTemplate.getResult());
占位符用于从 context 中提取任意 key 的值。
全局变量也可以从 context 中提取值,但是收到 QLExpress 关键词和语法的限制,能提取的 key 有限。
比如 context 中 "0" key 对应的值就无法通过变量提取,因为 0 不是 QLExpress 中的合法变量,而是一个数字常量。
此时可以用默认占位符 ${0} 来提取。
注意和动态字符串中插值区分,占位符是写在字符串之外。动态字符串插值是
${expression},其中默认写的是表达式,"${0}"的运行结果是"0"。而占位符是${placeholder},其中默认写的是 context 中的 key,${0}的运行结果是 context 中 "0" key 对应的值。
QLExpress 默认使用 ${placeholder} 格式的占位符,其中:
-
${是起始标记 -
}是结束标记 -
placeholder是占位符内容,对应 cotext 中的 key
除了默认的占位符外,QLExpress 还支持自定义占位符的起始和结束标记:
Express4Runner express4Runner = new Express4Runner(InitOptions.builder().selectorStart("#[").selectorEnd("]").build()); Map<String, Object> context = new HashMap<>(); context.put("0", "World"); QLResult result = express4Runner.execute("'Hello ' + #[0]", context, QLOptions.DEFAULT_OPTIONS); assertEquals("Hello World", result.getResult());
自定义占位符并不是任意的,限制条件如下:
-
起始标记限制:
selectorStart必须是以下四种格式之一:-
${(默认) -
$[ -
#{ -
#[
-
-
结束标记限制:
selectorEnd必须是 1 个或更多字符的字符串
表达式语句可以省略结尾的分号,整个脚本的返回值就是最后一个表达式的计算结果。
以下脚本的返回值为 2:
a = 1 b = 2 // last express 1+1
等价于以下写法:
a = 1 b = 2 // return statment return 1+1;
因为分号可以省略,QLExpress4 对于换行的处理相比 3 或者 Java 语言更加严格。如果想要将单行表达式拆成多行,建议将操作符保留在当前行,而将右操作数换到下一行。
以下多行表达式会报语法错误(反例):
// syntax error a + b
以下是正确的换行示例(正例):
a + b
其他的语法习惯保持和 Java 一致即可。
QLExpress 采用表达式优先的设计,其中 除了 import, return 和循环等结构外,几乎都是表达式。
if 语句也是一个表达式:
assert(if (11 == 11) { 10 } else { 20 + 2 } + 1 == 11)
try catch 结构也是一个表达式:
assert(1 + try { 100 + 1/0 } catch(e) { // Throw a zero-division exception 11 } == 12)
和 Java 类似,&& 和 || 逻辑运算都是短路运算的。
比如表达式 false && (1/0) 不会发生除 0 错误,因为 && 短路在了最开始的 false 处。
短路计算默认是开启的,引擎也提供了选项,可以在某次执行时将短路关闭:
关闭短路的一个场景是保证表达式的充分预热
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); // execute when enable short circuit (default) // `1/0` is short-circuited by the preceding `false`, so it won't throw an error. assertFalse((Boolean)express4Runner.execute("false && (1/0)", Collections.emptyMap(), QLOptions.DEFAULT_OPTIONS) .getResult()); try { // execute when disable short circuit express4Runner.execute("false && (1/0)", Collections.emptyMap(), QLOptions.builder().shortCircuitDisable(true).build()); fail(); } catch (QLException e) { Assert.assertEquals("INVALID_ARITHMETIC", e.getErrorCode()); Assert.assertEquals("Division by zero", e.getReason()); }
除了完全兼容 Java 中的 if 写法,还支持类似规则引擎的 if ... then ... else ... 的写法,其中 then 可以当成一个可以省略的关键字:
a = 11; // if ... else ... assert(if (a >= 0 && a < 5) { true } else if (a >= 5 && a < 10) { false } else if (a >= 10 && a < 15) { true } == true) // if ... then ... else ... r = if (a == 11) then true else false assert(r == true)
QLExpress4 中,Lambda 表达式作为一等公民,可以作为变量进行传递或者返回。
add = (a, b) -> { return a + b; } assert(add(1,2)==3)
支持通过 filter, map 方法直接对列表类型进行函数式过滤和映射。
底层通过在列表类型添加 扩展函数 实现,注意和 Stream API 中同名方法区分。
相比 Stream Api,它可以直接对列表进行操作,返回值也直接就是列表,更加方便。
l = ["a-111", "a-222", "b-333", "c-888"] assert(l.filter(i -> i.startsWith("a-")) .map(i -> i.split("-")[1]) == ["111", "222"])
QLExpress 可以兼容 Java8 的常见语法。
比如 for each循环, Stream API, 函数式接口等等。
可以直接使用 Java 集合中的 stream api 对集合进行操作。
因为此时的 stream api 都是来自 Java 中的方法,参考 安全策略 打开安全选项,以下脚本才能正常执行。
l = ["a-111", "a-222", "b-333", "c-888"] l2 = l.stream() .filter(i -> i.startsWith("a-")) .map(i -> i.split("-")[1]) .collect(Collectors.toList()); assert(l2 == ["111", "222"]);
Java8 中引入了 Function, Consumer, Predicate 等函数式接口,QLExpress 中的 Lambda表达式 可以赋值给这些接口,或者作为接收这些接口的方法参数:
Runnable r = () -> a = 8; r.run(); assert(a == 8); Supplier s = () -> "test"; assert(s.get() == 'test'); Consumer c = (a) -> b = a + "-te"; c.accept("ccc"); assert(b == 'ccc-te'); Function f = a -> a + 3; assert(f.apply(1) == 4); Function f1 = (a, b) -> a + b; assert(f1.apply("test-") == "test-null");
QLExpress 的上一版本因为多年的迭代停滞,在各项特性上和业界产生了较大差距。
QLExpress4 的目标之一就是一次性弥补这些差距,因此选择进行了大刀阔斧的升级,而有意放弃了部分兼容性。当然,基础的功能和体验还是和上一版本保持了对齐。
如果系统已经使用老版本的 QLExpress,升级之前务必要进行一次全面的回归测试,确保这些脚本都能在新版中正常执行,再进行升级。
如果没有时间或者方法对它们一一验证,那么不建议进行升级。
如果是新系统,建议直接采用 QLExpress4,未来 QLExpress4 的生态建设会越来越完善,而 3 会被逐渐抛弃。
下面将列表新版和旧版的主要不同,方便用户对已有脚本进行升级。如有遗漏,欢迎反馈:
如果完全使用默认选项,获取 Java 对象的字段(o.field),或者调用成员方法(o.method()),则会分别抛出 FIELD_NOT_FOUND 和 METHOD_NOT_FOUND 错误。
这是因为 3 可以没有限制地通过反射访问 Java 应用系统中的任意字段和方法,这在嵌入式脚本中被认为是不安全的。
如果想兼容 3 的行为,则在新建 Express4Runner 时, 要将安全策略设置为 "开放",参考代码如下:
// open security strategy Express4Runner express4RunnerOpen = new Express4Runner(InitOptions.builder().securityStrategy(QLSecurityStrategy.open()).build()); Assert.assertEquals("Thinking in Java", express4RunnerOpen.execute("desk.book1", context, QLOptions.DEFAULT_OPTIONS).getResult()); Assert.assertEquals("Effective Java", express4RunnerOpen.execute("desk.getBook2()", context, QLOptions.DEFAULT_OPTIONS).getResult());
详细参考 安全策略 章节。
QLExpress 老版本支持通过 NewMap(key:value) 的方式快速创建映射,虽然在文档中没有详细讨论,但是很多用户通过单元测试和询问的方式,知晓并使用了这个语法。
不过这种语法过于定制,也和业界的规范相差很大,因此在新版中将其移除。
新版原生支持 JSON 语法,直接采用 JSON 字典的格式({key:value})即可快速创建映射,更加直观。
详细参考 方便语法元素
QLExpress 支持在执行脚本时传入一个全局的上下文,即 context 参数。
在老版本中,如果脚本中定义了全局变量,则这些变量也会写入到 context。在脚本执行结束后,可以通过 context 获取到脚本中定义的全局变量的值。
一个老版本的列子如下:
// only for QLExpress 3.x String express = "a=3;a+1"; ExpressRunner runner = new ExpressRunner(false, true); DefaultContext<String, Object> context = new DefaultContext<>(); Object res = runner.execute(express, context, null, true, true); // The result of the script execution should be 4 (a+1) Assert.assertEquals(4, res); // The variable 'a' defined in the script is also stored in the context Assert.assertEquals(3, context.get("a"));
根据调研和反馈,我们认为这会导致全局上下文被脚本 "污染",存在安全性问题。
因此在 QLExpress4 中,全局变量默认不会写入到 context 中。
如果想要兼容 3 的特性,需要将 polluteUserContext 选项设置为 true,参考代码如下:
Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS); QLOptions populateOption = QLOptions.builder().polluteUserContext(true).build(); Map<String, Object> populatedMap = new HashMap<>(); populatedMap.put("b", 10); express4Runner.execute("a = 11;b = a", populatedMap, populateOption); assertEquals(11, populatedMap.get("a")); assertEquals(11, populatedMap.get("b")); // no population Map<String, Object> noPopulatedMap1 = new HashMap<>(); express4Runner.execute("a = 11", noPopulatedMap1, QLOptions.DEFAULT_OPTIONS); assertFalse(noPopulatedMap1.containsKey("a")); Map<String, Object> noPopulatedMap2 = new HashMap<>(); noPopulatedMap2.put("a", 10); assertEquals(19, express4Runner.execute("a = 19;a", noPopulatedMap2, QLOptions.DEFAULT_OPTIONS).getResult()); assertEquals(10, noPopulatedMap2.get("a"));
由于 QLExpress4 支持分号可省略,解释器需要通过换行符来判断语句是否结束。因此,QLExpress4 对换行的要求比 QLExpress3 更加严格。
下面的脚本在 QLExpress3 中是合法的,但在 QLExpress4 中不是:
// 在 QLExpress3 中合法的脚本,但在 QLExpress4 中不是 商家应收= 价格 - 饭卡商家承担 + 平台补贴
在 QLExpress4 中,上述脚本会被解析为两个独立的语句:
1. 商家应收 = 价格
2. - 饭卡商家承担 + 平台补贴(第二个语句会报语法错误)
如果要在 QLExpress4 中实现同样的效果,需要将操作符放在行尾,而不是行首:
// QLExpress4 中正确的写法 商家应收= 价格 - 饭卡商家承担 + 平台补贴
这样解释器就知道当前行的表达式还未结束,会继续读取下一行。
如果您需要兼容 QLExpress3 的换行特性,可以设置 strictNewLines 选项为 false:
Express4Runner express4Runner = new Express4Runner(InitOptions.builder().strictNewLines(false).build()); String script = "商家应收=\n 价格\n - 饭卡商家承担\n + 平台补贴"; Map<String, Object> context = new HashMap<>(); context.put("价格", 10); context.put("饭卡商家承担", 3); context.put("平台补贴", 5); QLResult result = express4Runner.execute(script, context, QLOptions.DEFAULT_OPTIONS); Assert.assertEquals(12, ((Number)result.getResult()).intValue());
注意:非严格换行模式会让解释器忽略所有换行符,可能会影响代码的可读性和错误提示的准确性。建议仅在需要兼容旧代码时使用。
在 QLExpress 3 中,单引号包裹的单个字符会被解析为 char 类型,而不是 String。
这个给用户带来了不少困惑,比如 "a"=='a' 的判断结果是 false。
所以后来 QLExpress 3 中新增了 ExpressRunner.setIgnoreConstChar 选项,设置为 true 后,所有的单引号和双引号包裹的字符都会被解析为 String 类型。但是这个选项默认是关闭的,需要用户手动开启。
考虑到脚本用户很少会使用到 char 这种底层类型,我们在 QLExpress 4 中直接取消了这个选项,所有的单引号和双引号包裹的字符都会被解析为 String 类型。
如果您在脚本还是需要使用 char 类型,可以通过两种方法获得:
-
类型强转:
(char) 'a' -
类型声明:
char a = 'a'
QLExpress 对社区的更改完全开放,任何建议和修改,都会受到欢迎,讨论后合理最后会被接纳到主干中。
首先需要将代码 clone 到本地,在正式修改代码前,需要先进行如下准备:
-
项目根目录执行
mvn compile:项目刚刚下载到本地时,会有大量的类找不到,需要先生成 Antlr4 的运行时代码 -
配置代码格式化:QLExpress 项目有统一的代码格式规范,开发前需要配置在 git 提交前的自动格式化
在项目目录下新建文件 .git/hooks/pre-commit,内容如下:
#!/bin/sh mvn spotless:apply git add -u exit 0
这样在每次 git commit 之前,就会自动执行 maven 的 spotless 插件执行代码格式化,具体代码格式配置见 spotless_eclipse_formatter.xml
-
执行单元测试:在开发完成代码之后,先在本地全量执行单元测试,确保代码质量
-
JDK 8 环境:执行
mvn test -
JDK 9 及以上环境:执行
mvn test -DargLine="--add-opens java.base/java.util.stream=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED"
-
总结:常见场景下,无编译缓存时,QLExpress4能比3有接近10倍性能提升;有编译缓存,也有一倍性能提升。
-
Email:
-
WeChat:
-
xuanheng: dqy932087612
-
binggou: pymbupt
-
linxiang: tkk33362
-
-
DingTalk Support Group
