package com.dsl;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.util.List;

/**
 * 检查问题：生产环境中不应该有调试代码。
 * 问题检查条件：
 * - 查找所有函数声明；
 * - 并且(And)：函数名以"debug"开头；
 * - 并且(And)：函数只有一个参数；
 * - 并且(And)：参数类型为"java.util.List"。
 */
public class CheckDebug {
    private static final Logger LOG = LogManager.getLogger(CheckDebug.class);

    // 应检查出的问题函数
    public void debugFunction(List<String> msgs) {
        for (String msg : msgs) {
            LOG.error("print debug info: {}", msg);
        }
    }
}

/**
 * 检查问题：生产环境中不应该有调试代码。
 * 问题检查条件：
 * - 查找所有函数声明；
 * - 并且(And)：函数名以"debug"开头；
 * - 并且(And)：函数只有一个参数；
 * - 并且(And)：参数类型为"java.util.List"。
 */

functionDeclaration fd where
	and(
		fd.name startWith "debug",
		fd.parameters.size() == 1,
		fd.parameters[0].type.name == "java.util.List"
	);

规则语句是以分号 (;) 结尾, 作为规则的终止符。

2.2. 语句结构

结构图

 

语法说明

节点(node)： 为待检测代码节点（token）；

as 别名：给要查找的节点一个别名，便于后面的使用。as 可以省略。别名的命名规则如下：

• 只能包含大小写英文字母和数字；
• 数字只能出现在末尾；
• 不能和规则内置的节点或属性同名。
• 例如：va1、fd、Field1都是合法的别名，1fc、v2a是非法别名。

查询条件（condition）：筛选节点的条件；

2.3. 节点和节点属性

结构图

语法说明

• 节点（node）：是代码对应语法树的节点或子节点；
• 属性（attribute）：是代码对应语法树的节点或子节点的属性；
• . : 节点、子节点、属性之间的连接符；

2.4. 条件表达式结构

结构图

语法说明

• where: 条件表达式的标识；
• and：括号内的查询条件必须都为真；
• or：括号内的查询条件至少有一个为真；
• not：括号内的查询条件为假；

逻辑的连接祠是一种作用于查询条件的关键词。规则支持and、or 和 not 三个关联词。

逻辑的连接词需要和括号一同使用，括号中为具体的查询条件。其中，and 和 or 可以作用于多个查询条件（即括号中可以包含多个查询条件，以逗号分隔开），not 只能作用于一个查询条件。

逻辑连接词是一类作用于查询条件的特殊运算符（普通的运算符作用于节点或属性）

逻辑的连接词作用的查询条件也可以包含逻辑连接词。

示例

/*
 * 问题检查条件：
 * - 查找函数名为 debug 或 foo；
 * - 并且(And)： 参数数量为 1 或 3。  
*/
functionDeclaration fd where
    and(or(fd.name == "debug", fd.name == "foo"),
        or(fd.parameters.size() == 1, fd.parameters.size() == 3));

2.5. 条件判断(condition)

结构图

2.5.1. 运算符

查询条件通过运算符作用于具体的节点或属性从而完成节点筛选。

根据运算符作用的属性类别，我们可以将运算符分为:

• 通用运算符
• 算术运算符
• 字符串运算符
• 布尔运算符
• 节点运算符

运算符的左值为：节点或节点的属性。

2.5.1.1. 通用运算符(==, contain)

等于（==）、不等于（!=）

• 数字
  • 运算符右值为：整数或小数。
  • 例如：arguments.size() == 3
• 字符串
  • 运算符右值为：字符串常量。
  • 例如：name == “foo”
• 布尔
  • 运算符右值为：布尔常量: true 或 false。
  • 例如：isPublic == true
• 节点
  • 运算符右值为：空常量null。
  • 例如：initializer == null

包含（contain）、不包含（notContain）

• 字符串
  • 运算符右值为：字符串，且包含时，返回真。
  • 例如：recordDeclaration where name contain "debug";，返回函数名中包含"debug" 时，返回真。
• 节点
  • 运算符右值为：子查询条件，当子查询返回的节点满足时，返回真。
  • 例如：functionDeclaration where parameters contain param where param.name == "i1";，返回包含名为i1参数的方法声明。

2.5.1.2. 算术运算符(>, <)

算术运算符操作数字。

大于（>）、小于（<）、大于等于（>=）、小于等于（<=）

数字

运算符右值为：数字，且满足时，返回真。

2.5.1.3. 字符串运算符(startWith, endWith, match)

字符串运算符操作字符串。

字符串的开始字符串（ startWith）

• 左值开始字符串等于右值字符串时，返回真。
• 例如：functionDeclartion where name startWith "debug";，筛选出名字以debug开头的方法声明。

字符串的结束字符串（ endWith）

• 左值结束字符串等于右值字符串时，返回真。
• 例如：functionDeclartion where name endWith "hello"，筛选出名字以hello结尾的方法声明。

字符串匹配（ match）

• 左值符合右值的正则表达式时，返回真。
• 例如：functionDeclaration where name match ".*(login).*"，筛选出名字匹配正则表达式.*(login).*的方法声明。

2.5.1.4. 布尔运算符(!)

逻辑运算符操作布尔值。

非（ !）

• 操作符位于布尔属性的左侧，表示布尔值为false时，返回真。
• 例如：recordDeclaration where !isPublic 等价于 recordDelaration where isPublic == false。

2.5.1.5. 节点运算符(contain,in,is)

节点运算符的左侧可以是节点属性 或 别名。

包含( contain)

• 用于查询语法树结构上的子节点。
• 例如: 筛选出方法体内调用了名为foo的无参方法的方法声明。

functionDeclaration fd where
    fd contain functionCall where
        and(name == "foo",
            arguments.size() == 0));

存在于( in)

• 查询语法树结构上的父节点。
• 例如: 筛选出位于赋值表达式中的数据成员访问节点。

fieldAccess fa1 where
    fa1 in assignStatement;

是( is)

• 右侧节点属性或别名相同时，返回真。
• 例如：筛选出出现在赋值表达式左侧的变量访问节点，且赋值表达式的右侧为方法调用节点。规则中的va是节点variableAccess的别名。

variableAccess va where
    va in assignStatement where
        and(lhs is va,
            rhs is functionCall);

2.5.2. 值类型

2.5.2.1. 布尔值

布尔值为布尔常量true或false。

布尔属性可以单独使用。单独使用时，布尔属性隐式等价于一个包含==的通用条件表达式。

例如，recordDeclaration where isPublic;等价于recordDeclaration where isPublic == true;

2.5.2.2. 数值

规则中的数值可以为整数或小数。

2.5.2.3. 字符串

字符串支持大小写英文字母、数字、以及正则表达式特殊字符。

2.5.2.4. 空值(null)

空值指的是源码中的null。

在使用时,空值往往和== 或 != 一同出现。

例如：

// private String field = null
fieldDeclaration fd where fd.initializer == null;

// str = null
assignStatement as1 where as1.rhs == null;

3. CodeNavi插件

在Vscode 的插件中，查询:codenavi，并安装。

 

点击关注，第一时间了解华为云新鲜技术~