jzhlin

一些基本概念

在开始独立研发公司自己的代码规范检查规则之前,先介绍一些相关的基本概念。阿里巴巴代码规范很多规则其实都是基于开源框架PMD进行的研发。PMD用官方的话语介绍来说:PMD是一个源代码分析器。它可以发现常见的编程缺陷,如未使用的变量、空catch块、不必要的对象创建等。它支持多种语言。它可以用自定义规则进行扩展。它使用JavaCC和Antlr将源文件解析为抽象语法树(AST),并对其运行规则以查找冲突。规则可以用Java编写,也可以使用XPath查询。开源代码库:https://github.com/pmd/pmd

这里涉及到一个很关键的概念——AST 抽象语法树(Abstract Syntax Tree)。AST运用场景其实非常多,日常我们研发过程中错误提示、代码高亮、代码格式化、代码转译等等实现的基础都基于AST。简单说,会通过词法分析和语法分析将代码转化成一种类似树样层次结构来进行描述,当然这种描述可以用XML格式。文字描述比较抽象,不妨看一个“Hello world”的具体AST语法树(Java 1.8),这样就很容易进行理解了。

image

另外一个概念XPath 是一门在XML 文档中查找信息的语言。本身和代码解析没有关系,但当AST通过XML格式描述时,XPath能够很好完成对相关节点进行查找。两者的结合就能进行违规代码的检查,这就是XPath规则代码规范检查基本原理。此外,与其配套的PMD-Designer规则可视化工具也很好用。

例如阿里巴巴代码规范中 PackageNamingRule 就是非常典型的XPath规则。包名只能由小写字母、数字来组成,具体的XPath:

private static final String XPATH = "//PackageDeclaration/Name"
    + "[not (matches(@Image, '^[a-z0-9]+(\\.[a-z][a-z0-9]*)*$'))]";

下面先写个规则的例子来感受下自定义规则具体的操作;从检查代码中System.out 类似的日志输出开始。

Example :检查代码中System.out 类似的日志输出。

步骤一,运用PMD-Designer 来辅助编写具体XPath的检查规则;这个工具也可以验证各种代码写法下,规则是否都能起到很好的作用。最终XPath 具体规则如下:

//Name[starts-with(@Image, 'System.out.print') or starts-with(@Image, 'System.err.print')]

步骤二,新建一个具体的规则类,继承AbstractXpathRule ;其中AbstractXpathRule 本身是继承 PMD 中 XPathRule,主要扩展了多语言的设计。详细如下:

package com.alibaba.p3c.pmd.lang.java.rule.emo;  
...

import static net.sourceforge.pmd.lang.rule.xpath.XPathRuleQuery.XPATH_2_0;  
  
public class VoidSystemPrintRule extends AbstractXpathRule {  
    private static final String XPATH =  
            "//Name[starts-with(@Image, 'System.out.print') or starts-with(@Image, 'System.err.print')]";  
  
    public VoidSystemPrintRule() {  
        setXPath(XPATH);  
        setVersion(XPATH_2_0);  
    }  
  
    @Override  
    public void addViolation(Object data, Node node, String arg) {  
        ViolationUtils.addViolationWithPrecisePosition(this, node, data,  
                I18nResources.getMessage("java.naming.VoidSystemPrintRule.violation.msg", node.getImage()));  
    }  
}  

步骤三:在messages.xml 和 messages_en.xml 分别添加检查出错后给出相关中英文提示。

<entry key="java.naming.VoidSystemPrintRule.violation.msg">
    <![CDATA[程序中避免直接使用 System 对相关日志信息输出]]>
</entry>
——
<entry key="java.naming.VoidSystemPrintRule.violation.msg">
    <![CDATA[Avoid using system print]]>
</entry>

步骤四:新建emo-common.xml 的规则集合,并将实现的规则配置进去。

<ruleset name="AlibabaJavaNaming" xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">
    <description>EmoJavaCommonRule</description>
    <rule name="VoidSystemPrintRule"
          language="java"
          since="1.6"
          message="java.naming.VoidSystemPrintRule.violation.msg"
          class="com.alibaba.p3c.pmd.lang.java.rule.emo.VoidSystemPrintRule">
        <priority>3</priority>
        <example>
            <![CDATA[
                System.out.println(message);
            ]]>
        </example>
    </rule>
</ruleset>

步骤五:在ali-pmd.xml 中引入我们新加的规则集合 emo-common.xml。

<rule ref="rulesets/java/emo-common.xml"/>

最后运行下修改完的代码程序,效果如下:

image
image

综述下关键点,代码规范检查基本原理可以基于AST语法树来进行实现;AST结合Xpath可以方便进行相关规范规则的编写;通过 PMD-Designer 能可视化的帮助我们实现 XPath 的相关代码规范规则以及验证相关规则;给出了一个例子,基于阿里开源代码规范插件源码,编写适用自己公司的代码规范的方式。

附上相关代码github链接:https://github.com/ariesfly/emo-coding-guardian
如有遇到问题欢迎公众号私信留言

分类:

java

技术点:

相关文章: