Sonarqube JAVA自定义规则开发-XPATH模式
1版本说明
| 名称 | 版本 | 说明 |
|---|---|---|
| PMD | 5.4.1 | designer.bat |
| SONARQUBE | 5.6 | Sonarqube平台版本 |
| pmd-plugin | 2.6 | Pmd插件版本 |
2模板介绍
2.1简述
注意：创建自定义规则需要登陆系统
Sonarqube平台提供了一些模板来快速的实现一些简单的自定义规则需求。JAVA所有的模板如下图所示（DEPRECATED表示为废弃的，不建议使用）：
image.png
点击某一个模板，就可以进入该模板的说明页，在该页选择“创建”，就可以创建自己的规则了。
image.png
下面对各个模板进行简要说明：
2.2模板Custom resources should be closed
该模版主要实现了自定义资源是否关闭的检查，防止内存泄漏。
需要提供的参数：factoryMethod****，****closingMethod****，****constructor****，****openingMethod
2.3模板Track breaches of architectural constraints
该模版主要实现了类之间引用的检查。
需要提供的参数：fromClasses****（可选），****toClasses
例如: toClass设置为java.util.**，fromClass不设置，那么在任何类中使用如下代码将会违规
MapdispatcherConfig; //违规
PS：该模板后续将会废弃，不建议使用。经测试，toClass只对JDK类有效
2.4模板Track comments matching a regularexpression
该模板主要实现了注释内容的检查。
需要提供的参数：regularExpression,message
regularExpression代表正则表达式，message表示输出的错误信息
例如：regularExpression输入.TODO.，那么所有包含TODO的注释将报违规
2.5模板Track uses of disallowed classes
该模板主要实现了不允许使用的类的检查。
需要提供的参数：className****，类名，也可用正则表达式来实现包的禁止
例如：Classname****：java.lang.String，那么String name则会报违规
PS：经测试，该模板只适合JDK的类
2.6模板Track uses of disallowed dependencies
该模板主要实现了不允许使用的依赖的检查，主要检查MAVEN的POM.xml文件。
需要提供的参数：dependencyName****，****version
例如：With a parameterof: :.log4j.*
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.17</version>
</dependency>//违规
PS：目前不支持maven的POM.XML的分析，分析XML需要XML插件的支持，并且在工程中设置sonar.import_unknown_files"to "true"。
2.7模板Track uses of disallowed methods
该模板主要实现了不允许使用的方法的检查。
需要提供的参数：methodName，className****，****argumentTypes****，****allOverloads
例如：
className:java.lang.String
methodName:replace
argumentTypes:java.lang.CharSequence, java.lang.CharSequence
String name;
name.replace("A","a"); // 违规
PS：经测试，该模板只适合JDK的类
2.8模板XPath rule template
该模板是PMD插件提供的一个模板，与之前的模板不一样，之前的模板为sonar Java插件提供。因此，该模板的使用要依赖于PMD工具。
因为代码扫描是依赖AST树形结构的，所以Xpath模式也就是通过PMD获取树的节点，再自定义规则进行匹配。
该模板主要实现了当java文件的AST树与Xpath定义的规则匹配时，就报相应的违规。
因为该模板由PMD提供，sonarqube建议使用插件开发模式，因此该模板标示为: DEPRECATED,但仍然可以使用。
下面详细介绍Xpath模式的开发过程。
2.8.1开发过程
开始开发之前可以导入PMD源码到Eclipse中，在pmd-java项目下找到rulesets文件夹，底下全部是Java对应的PMD规则，可以用来学习和参考。
image.png
以下以teller9的不允许使用GlobalCache来演示实现XPATH的完整过程。
1、规则分析：
违规使用平台内部的执行缓存
例1：
Map<String,Object>map = (Map<String,Object>)GlobalCache.getInstance().getCacheData();
例2：
GlobalCache.getInstance().setCacheData(map);
推荐的使用方式
无，不允许项目中使用GlobalCache存放数据
按照以上规则说明，可以看出，当用Xpath rule template来实现这个规则时，需要能够匹配到setCacheData方法，并且map变量名一致。
2、使用PMD工具解析java文件
打开pmd/bin/designer.bat，在Source code中输入错误样例，点击Go，AST一栏出现了PMD解析出来的java文件的AST树，该树是我们进行后续开发的基础。
image.png
3、写出XPATH规则
现在就可以写对应的Xpath查询了。Xpath要实现与违规的情景匹配，与正确的写法不匹配的基本目标。具体的Xpath方法可以查阅附录资料。
在Xpath Query输入对应的查询，点击Go，就可以进行调试。当在右下角的框中出现了ASTblock Statement at line xxx 语句，这就说明PMD表达式成功了，可以从左侧源码中匹配到了符合触发条件的代码。这时检查行数是否在应该触发违规的代码处。
当违规的情况验证后，再输入正确的source code，再次执行查询，此时右下角框中应该显示：No matching code xxxx。
image.png
4、创建自定义规则
建立成功PMD规则后，打开Sonarqube主页。点击菜单栏的代码规则，选择Java，选择模板，只显示模板，点击右侧的XPathrule template，列出Xpath模板详情。点击创建，在弹出框中依次输入名称、关键字、描述，再选择严重级别、状态，最后在xpath文本框中输入
//Block/BlockStatement[1]
[
.//PrimaryPrefix/Name[@Image='GlobalCache.getInstance']
and
(
ancestor::Block/BlockStatement[
Statement/StatementExpression/PrimaryExpression
[./PrimarySuffix[ends-with(@Image,"setCacheData")]]
]
)
]
这个PMD规则，点击创建，保存成功即可。
5、执行规则
在Sonarqube界面的质量配置中新建“Java自定义规则”的质量集合并设置为默认配置，再次进入PMD模板页面，点击“不允许使用GlobalCache”进入详情页，点击下面的活动按钮，将这个规则放到“Java自定义规则”下面。
输入cmd进入命令行模式，进入需要调试的工程目录。比如，C:\work\manage>，输入sonar-scanner进行代码扫描。待扫描结束后，可以在Sonarqube界面查看bug情况。
2.8.2 参考
相关资料：
http://pmd.sourceforge.net/pmd-5.4.1/customizing/xpathruletutorial.html
http://www.w3school.com.cn/xpath/index.asp
PMD源码主分支
