写点什么

案例研究之聊聊 QLExpress 源码 (一)

发布于: 2021 年 01 月 09 日
案例研究之聊聊 QLExpress 源码 (一)

QLExpress 是动态脚本引擎解析工具,由于工作环境中经常会遇到一些规则,但是不想硬编码到系统中!这样便会用类似规则引擎模块来将这些规则从业务剥离出去,而我们系统中的底层因为使用了 QLExpress,所以希望从源码中一窥究竟。

本次希望从以下几个模块来剥离出 QLExpress 的面纱:

一、官网解读

二、架构图

三、配置模块(config)

四、异常模块(Exception)

五、匹配模块(match)

六、解析模块(parse)

七、规则模块(rule)

八、指令模块(instruction)

九、其他

十、小结


一、官网解读


QLExpress 基本语法


1.1、背景介绍


由阿里的电商业务规则、表达式(布尔组合)、特殊数学公式计算(高精度)、语法分析、脚本二次定制等强需求而设计的一门动态脚本引擎解析工具。 在阿里集团有很强的影响力,同时为了自身不断优化、发扬开源贡献精神,于 2012 年开源。


QLExpress 脚本引擎被广泛应用在阿里的电商业务场景,具有以下的一些特性:


  • 1、线程安全,引擎运算过程中的产生的临时变量都是 threadlocal 类型。

  • 2、高效执行,比较耗时的脚本编译过程可以缓存在本地机器,运行时的临时变量创建采用了缓冲池的技术,和 groovy 性能相当。

  • 3、弱类型脚本语言,和 groovy,javascript 语法类似,虽然比强类型脚本语言要慢一些,但是使业务的灵活度大大增强。

  • 4、安全控制,可以通过设置相关运行参数,预防死循环、高危系统 api 调用等情况。

  • 5、代码精简,依赖最小,250k 的 jar 包适合所有 java 的运行环境,在 android 系统的低端 pos 机也得到广泛运用。

1.2、依赖和调用说明


maven 引入依赖 jar 包

<dependency>  <groupId>com.alibaba</groupId>  <artifactId>QLExpress</artifactId>  <version>3.2.0</version></dependency>
复制代码


ExpressRunner runner = new ExpressRunner();DefaultContext<String, Object> context = new DefaultContext<String, Object>();context.put("a",1);context.put("b",2);context.put("c",3);String express = "a+b*c";Object r = runner.execute(express, context, null, true, false);System.out.println(r);
复制代码


1.3、语法介绍

1.3.1、操作符和 java 对象操作

普通 java 语法

//支持 +,-,*,/,<,>,<=,>=,==,!=,<>【等同于!=】,%,mod【取模等同于%】,++,--,//in【类似sql】,like【sql语法】,&&,||,!,等操作符//支持for,break、continue、if then else 等标准的程序控制逻辑n=10;for(sum=0,i=0;i<n;i++){sum=sum+i;}return sum;
//逻辑三元操作a=1;b=2;maxnum = a>b?a:b;
复制代码

和 java 语法相比,要避免的一些 ql 写法错误

  • 不支持 try{}catch{}

  • 不支持 java8 的 lambda 表达式

  • 不支持 for 循环集合操作 for (GRCRouteLineResultDTO item : list)

  • 弱类型语言,请不要定义类型声明,更不要用 Templete(Map<String,List>之类的)

  • array 的声明不一样

  • min,max,round,print,println,like,in 都是系统默认函数的关键字,请不要作为变量名

弱类型和不使用范型以及关键字
//java语法:使用泛型来提醒开发者检查类型keys = new ArrayList<String>();deviceName2Value = new HashMap<String,String>(7);String[] deviceNames = {"ng","si","umid","ut","mac","imsi","imei"};int[] mins = {5,30};
//ql写法:keys = new ArrayList();deviceName2Value = new HashMap();deviceNames = ["ng","si","umid","ut","mac","imsi","imei"];mins = [5,30];
复制代码
对象和数组以及 map 的遍历
//java语法:对象类型声明FocFulfillDecisionReqDTO reqDTO = param.getReqDTO();//ql写法:reqDTO = param.getReqDTO();
//java语法:数组遍历for(GRCRouteLineResultDTO item : list) {}//ql写法:for(i=0;i<list.size();i++){item = list.get(i);}
//java语法:map遍历for(String key : map.keySet()) { System.out.println(map.get(key));}//ql写法: keySet = map.keySet(); objArr = keySet.toArray(); for (i=0;i<objArr.length;i++) { key = objArr[i]; System.out.println(map.get(key)); }
复制代码

1.3.2、脚本中定义 function

function add(int a,int b){  return a+b;};
function sub(int a,int b){ return a - b;};
a=10;return add(a,4) + sub(a,9);
复制代码

1.3.3、扩展操作符:Operator

替换 if then else 等关键字

runner.addOperatorWithAlias("如果", "if",null);runner.addOperatorWithAlias("则", "then",null);runner.addOperatorWithAlias("否则", "else",null);
exp = "如果 (语文+数学+英语>270) 则 {return 1;} 否则 {return 0;}";DefaultContext<String, Object> context = new DefaultContext<String, Object>();runner.execute(exp,context,null,false,false,null);
复制代码

如何自定义 Operator

//定义一个继承自com.ql.util.express.Operator的操作符public class JoinOperator extends Operator{	public Object executeInner(Object[] list) throws Exception {		Object opdata1 = list[0];		Object opdata2 = list[1];		if(opdata1 instanceof java.util.List){			((java.util.List)opdata1).add(opdata2);			return opdata1;		}else{			java.util.List result = new java.util.ArrayList();			result.add(opdata1);			result.add(opdata2);			return result;						}	}}

复制代码

如何使用 Operator

//(1)addOperatorExpressRunner runner = new ExpressRunner();DefaultContext<String, Object> context = new DefaultContext<String, Object>();runner.addOperator("join",new JoinOperator());Object r = runner.execute("1 join 2 join 3", context, null, false, false);System.out.println(r);//返回结果  [1, 2, 3]
//(2)replaceOperatorExpressRunner runner = new ExpressRunner();DefaultContext<String, Object> context = new DefaultContext<String, Object>();runner.replaceOperator("+",new JoinOperator());Object r = runner.execute("1 + 2 + 3", context, null, false, false);System.out.println(r);//返回结果 [1, 2, 3]
//(3)addFunctionExpressRunner runner = new ExpressRunner();DefaultContext<String, Object> context = new DefaultContext<String, Object>();runner.addFunction("join",new JoinOperator());Object r = runner.execute("join(1,2,3)", context, null, false, false);System.out.println(r);//返回结果 [1, 2, 3]
复制代码

1.3.4、绑定 Java 类或者对象的 method

addFunctionOfClassMethod+addFunctionOfServiceMethod

public class BeanExample {	public static String upper(String abc) {		return abc.toUpperCase();	}	public boolean anyContains(String str, String searchStr) {
char[] s = str.toCharArray(); for (char c : s) { if (searchStr.contains(c+"")) { return true; } } return false; }}
runner.addFunctionOfClassMethod("取绝对值", Math.class.getName(), "abs", new String[] { "double" }, null);runner.addFunctionOfClassMethod("转换为大写", BeanExample.class.getName(), "upper", new String[] { "String" }, null);
runner.addFunctionOfServiceMethod("打印", System.out, "println",new String[] { "String" }, null);runner.addFunctionOfServiceMethod("contains", new BeanExample(), "anyContains", new Class[] { String.class, String.class }, null);
String exp = “取绝对值(-100);转换为大写(\"hello world\");打印(\"你好吗?\");contains("helloworld",\"aeiou\")”;runner.execute(exp, context, null, false, false);
复制代码

1.3.5、macro 宏定义

runner.addMacro("计算平均成绩", "(语文+数学+英语)/3.0");runner.addMacro("是否优秀", "计算平均成绩>90");IExpressContext<String, Object> context =new DefaultContext<String, Object>();context.put("语文", 88);context.put("数学", 99);context.put("英语", 95);Object result = runner.execute("是否优秀", context, null, false, false);System.out.println(r);//返回结果true
复制代码

1.3.6、编译脚本,查询外部需要定义的变量和函数

注意以下脚本 int 和没有 int 的区别

String express = "int 平均分 = (语文+数学+英语+综合考试.科目2)/4.0;return 平均分";ExpressRunner runner = new ExpressRunner(true,true);String[] names = runner.getOutVarNames(express);for(String s:names){ System.out.println("var : " + s);}
//输出结果:
var : 数学var : 综合考试var : 英语var : 语文
复制代码

1.3.7、关于不定参数的使用

@Test    public void testMethodReplace() throws Exception {        ExpressRunner runner = new ExpressRunner();        IExpressContext<String,Object> expressContext = new DefaultContext<String,Object>();        runner.addFunctionOfServiceMethod("getTemplate", this, "getTemplate", new Class[]{Object[].class}, null);
//(1)默认的不定参数可以使用数组来代替 Object r = runner.execute("getTemplate([11,'22',33L,true])", expressContext, null,false, false); System.out.println(r); //(2)像java一样,支持函数动态参数调用,需要打开以下全局开关,否则以下调用会失败 DynamicParamsUtil.supportDynamicParams = true; r = runner.execute("getTemplate(11,'22',33L,true)", expressContext, null,false, false); System.out.println(r); } //等价于getTemplate(Object[] params) public Object getTemplate(Object... params) throws Exception{ String result = ""; for(Object obj:params){ result = result+obj+","; } return result; }
复制代码

1.3.8、关于集合的快捷写法

@Test    public void testSet() throws Exception {        ExpressRunner runner = new ExpressRunner(false,false);        DefaultContext<String, Object> context = new DefaultContext<String, Object>();        String express = "abc = NewMap(1:1,2:2); return abc.get(1) + abc.get(2);";        Object r = runner.execute(express, context, null, false, false);        System.out.println(r);        express = "abc = NewList(1,2,3); return abc.get(1)+abc.get(2)";        r = runner.execute(express, context, null, false, false);        System.out.println(r);        express = "abc = [1,2,3]; return abc[1]+abc[2];";        r = runner.execute(express, context, null, false, false);        System.out.println(r);    }
复制代码

1.3.9、集合的遍历

其实类似 java 的语法,只是 ql 不支持 for(obj:list){}的语法,只能通过下标访问。

//遍历map  map = new HashMap();  map.put("a", "a_value");  map.put("b", "b_value");  keySet = map.keySet();  objArr = keySet.toArray();  for (i=0;i<objArr.length;i++) {  key = objArr[i];   System.out.println(map.get(key));  }
复制代码

1.4、运行参数和 API 列表介绍

QLExpressRunner 如下图所示,从语法树分析、上下文、执行过程三个方面提供二次定制的功能扩展。

1.4.1、属性开关

isPrecise

/**	 * 是否需要高精度计算	 */	private boolean isPrecise = false;
复制代码

高精度计算在会计财务中非常重要,java 的 float、double、int、long 存在很多隐式转换,做四则运算和比较的时候其实存在非常多的安全隐患。 所以类似汇金的系统中,会有很多 BigDecimal 转换代码。而使用 QLExpress,你只要关注数学公式本身 订单总价 = 单价 * 数量 + 首重价格 + ( 总重量 - 首重) * 续重单价 ,然后设置这个属性即可,所有的中间运算过程都会保证不丢失精度。

isShortCircuit

/**	 * 是否使用逻辑短路特性	 */	private boolean isShortCircuit = true;
复制代码

在很多业务决策系统中,往往需要对布尔条件表达式进行分析输出,普通的 java 运算一般会通过逻辑短路来减少性能的消耗。例如规则公式: star>10000 and shoptype in('tmall','juhuasuan') and price between (100,900) 假设第一个条件 star>10000 不满足就停止运算。但业务系统却还是希望把后面的逻辑都能够运算一遍,并且输出中间过程,保证更快更好的做出决策。

isTrace

/**	 * 是否输出所有的跟踪信息,同时还需要log级别是DEBUG级别	 */	private boolean isTrace = false;
复制代码


这个主要是是否输出脚本的编译解析过程,一般对于业务系统来说关闭之后会提高性能。

1.4.2、调用入参

/** * 执行一段文本 * @param expressString 程序文本 * @param context 执行上下文,可以扩展为包含ApplicationContext * @param errorList 输出的错误信息List * @param isCache 是否使用Cache中的指令集,建议为true * @param isTrace 是否输出详细的执行指令信息,建议为false * @param aLog 输出的log * @return * @throws Exception */	Object execute(String expressString, IExpressContext<String,Object> context,List<String> errorList, boolean isCache, boolean isTrace, Log aLog);
复制代码

1.4.3、功能扩展 API 列表

QLExpress 主要通过子类实现 Operator.java 提供的以下方法来最简单的操作符定义,然后可以被通过 addFunction 或者 addOperator 的方式注入到 ExpressRunner 中。

public abstract Object executeInner(Object[] list) throws Exception;
复制代码

比如我们几行代码就可以实现一个功能超级强大、非常好用的 join 操作符:

list = 1 join 2 join 3; -> [1,2,3] list = join(list,4,5,6); -> [1,2,3,4,5,6]

public class JoinOperator extends Operator{	public Object executeInner(Object[] list) throws Exception {        java.util.List result = new java.util.ArrayList();        Object opdata1 = list[0];        if(opdata1 instanceof java.util.List){           result.addAll((java.util.List)opdata1);        }else{            result.add(opdata1);        }        for(int i=1;i<list.length;i++){           result.add(list[i]);        }        return result;	}}
复制代码

如果你使用 Operator 的基类 OperatorBase.java 将获得更强大的能力,基本能够满足所有的要求。

(1)function 相关 API

//通过name获取function的定义OperatorBase getFunciton(String name);
//通过自定义的Operator来实现类似:fun(a,b,c)void addFunction(String name, OperatorBase op);//fun(a,b,c) 绑定 object.function(a,b,c)对象方法void addFunctionOfServiceMethod(String name, Object aServiceObject, String aFunctionName, Class<?>[] aParameterClassTypes, String errorInfo);//fun(a,b,c) 绑定 Class.function(a,b,c)类方法void addFunctionOfClassMethod(String name, String aClassName, String aFunctionName, Class<?>[] aParameterClassTypes, String errorInfo);//给Class增加或者替换method,同时 支持a.fun(b) ,fun(a,b) 两种方法调用//比如扩展String.class的isBlank方法:“abc”.isBlank()和isBlank("abc")都可以调用void addFunctionAndClassMethod(String name,Class<?>bindingClass, OperatorBase op);
复制代码

(2)Operator 相关 API

提到脚本语言的操作符,优先级、运算的目数、覆盖原始的操作符(+,-,*,/等等)都是需要考虑的问题,QLExpress 统统帮你搞定了。

//添加操作符号,可以设置优先级void addOperator(String name,Operator op);void addOperator(String name,String aRefOpername,Operator op);		//替换操作符处理OperatorBase replaceOperator(String name,OperatorBase op);      //添加操作符和关键字的别名,比如 if..then..else -> 如果。。那么。。否则。。void addOperatorWithAlias(String keyWordName, String realKeyWordName,			String errorInfo);
复制代码

(3)宏定义相关 API

QLExpress 的宏定义比较简单,就是简单的用一个变量替换一段文本,和传统的函数替换有所区别。

//比如addMacro("天猫卖家","userDO.userTag &1024 ==1024")void addMacro(String macroName,String express) 
复制代码

(4)java class 的相关 api

QLExpress 可以通过给 java 类增加或者改写一些 method 和 field,比如 链式调用:"list.join("1").join("2")",比如中文属性:"list.长度"。

//添加类的属性字段void addClassField(String field,Class<?>bindingClass,Class<?>returnType,Operator op);
//添加类的方法void addClassMethod(String name,Class<?>bindingClass,OperatorBase op);
复制代码

注意,这些类的字段和方法是执行器通过解析语法执行的,而不是通过字节码增强等技术,所以只在脚本运行期间生效,不会对 jvm 整体的运行产生任何影响,所以是绝对安全的。

(5)语法树解析变量、函数的 API

这些接口主要是对一个脚本内容的静态分析,可以作为上下文创建的依据,也可以用于系统的业务处理。 比如:计算 “a+fun1(a)+fun2(a+b)+c.getName()” 包含的变量:a,b,c 包含的函数:fun1,fun2

(6)语法解析校验 api

脚本语法是否正确,可以通过 ExpressRunner 编译指令集的接口来完成。

String expressString = "for(i=0;i<10;i++){sum=i+1}return sum;";InstructionSet instructionSet = expressRunner.parseInstructionSet(expressString);//如果调用过程不出现异常,指令集instructionSet就是可以被加载运行(execute)了!
复制代码

(7)指令集缓存相关的 api

因为 QLExpress 对文本到指令集做了一个本地 HashMap 缓存,通常情况下一个设计合理的应用脚本数量应该是有限的,缓存是安全稳定的,但是也提供了一些接口进行管理。

	//优先从本地指令集缓存获取指令集,没有的话生成并且缓存在本地	InstructionSet getInstructionSetFromLocalCache(String expressString);	//清除缓存	void clearExpressCache();
复制代码

(8)安全风险控制

8.1 防止死循环
try {    	express = "sum=0;for(i=0;i<1000000000;i++){sum=sum+i;}return sum;";	//可通过timeoutMillis参数设置脚本的运行超时时间:1000ms	Object r = runner.execute(express, context, null, true, false, 1000);	System.out.println(r);	throw new Exception("没有捕获到超时异常");    } catch (QLTimeOutException e) {	System.out.println(e);    }
复制代码
8.2 防止调用不安全的系统 api
 ExpressRunner runner = new ExpressRunner();    QLExpressRunStrategy.setForbiddenInvokeSecurityRiskMethods(true);        DefaultContext<String, Object> context = new DefaultContext<String, Object>();    try {    	express = "System.exit(1);";	Object r = runner.execute(express, context, null, true, false);	System.out.println(r);	throw new Exception("没有捕获到不安全的方法");    } catch (QLException e) {	System.out.println(e);    }
复制代码

(9)增强上下文参数 Context 相关的 api

9.1 与 spring 框架的无缝集成

上下文参数 IExpressContext context 非常有用,它允许 put 任何变量,然后在脚本中识别出来。

在实际中我们很希望能够无缝的集成到 spring 框架中,可以仿照下面的例子使用一个子类。

public class QLExpressContext extends HashMap<String, Object> implements		IExpressContext<String, Object> {
private ApplicationContext context;
//构造函数,传入context和 ApplicationContext public QLExpressContext(Map<String, Object> map, ApplicationContext aContext) { super(map); this.context = aContext; }
/** * 抽象方法:根据名称从属性列表中提取属性值 */ public Object get(Object name) { Object result = null; result = super.get(name); try { if (result == null && this.context != null && this.context.containsBean((String) name)) { // 如果在Spring容器中包含bean,则返回String的Bean result = this.context.getBean((String) name); } } catch (Exception e) { throw new RuntimeException(e); } return result; }
public Object put(String name, Object object) { return super.put(name, object); }
}
复制代码

完整的 demo 参照 SpringDemoTest.java

9.2 自定义函数操作符获取原始的 context 控制上下文

自定义的 Operator 需要直接继承 OperatorBase,获取到 parent 即可,可以用于在运行一组脚本的时候,直接编辑上下文信息,业务逻辑处理上也非常有用。

public class ContextMessagePutTest {            class OperatorContextPut extends OperatorBase {                public OperatorContextPut(String aName) {            this.name = aName;        }            @Override        public OperateData executeInner(InstructionSetContext parent, ArraySwap list) throws Exception {            String key = list.get(0).toString();            Object value = list.get(1);            parent.put(key,value);            return null;        }    }        @Test    public void test() throws Exception{        ExpressRunner runner = new ExpressRunner();        OperatorBase op = new OperatorContextPut("contextPut");        runner.addFunction("contextPut",op);        String exp = "contextPut('success','false');contextPut('error','错误信息');contextPut('warning','提醒信息')";        IExpressContext<String, Object> context = new DefaultContext<String, Object>();        context.put("success","true");        Object result = runner.execute(exp,context,null,false,true);        System.out.println(result);        System.out.println(context);    }}
复制代码


参考资料:https://yq.aliyun.com/album/130https://github.com/alibaba/QLExpress


本篇主要是根据官网和 github 上的信息进行概览了解,对于基本特性功能有所掌握!


发布于: 2021 年 01 月 09 日阅读数: 779
用户头像

小胜靠智,大胜靠德 2019.06.27 加入

历经创业、京东、腾讯、滴滴公司,希望能够有些东西一起分享。公众号:小诚信驿站,微信/CSDN搜索:wolf_love666

评论

发布
暂无评论
案例研究之聊聊 QLExpress 源码 (一)