概述

CheckStyle检查代码是否符合制定的规范。CheckStyle检查是基于源码的,无需编译,执行速度快。

CheckStyle的主要流程是:

  1. 对Java文件进行词法语法分析,生成语法树。
  2. 载入配置文件(checkstyle-metadata.xml以及自定义的配置文件)register check事件。
  3. 按照深度优先遍历对语法树进行解析,按照注册的事件,在到达某些节点(AST)时进行style检查。AST,A child-Sibling Tree,是语法树中的某个节点,其类型在TokenTypes类中定义。
  4. 自定义Style的检查,就是在第二步设定的。实现com.puppycrawl.tools.checkstyle.api.Check类,重载其中的两个方法:public int[] getDefaultTokens()public void visitToken(DetailAST ast)。这两个方法的含义为,在遍历语法树的过程中,每当到达getDefaultTokens函数所返回的AST类型,程序就进入visitToken进行具体的检查和分析,即真正的分析检查过程是在visitToken中实现的。

CheckStyle有针对不同IDE和构建工具的各种插件,如 maven-checkstyle-plugin 插件,配置很简单:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.3.1</version>
    <configuration>
    	<!--内置4种规范:config/sun_checks.xml、config/maven_checks.xml、config/turbine_checks.xml、config/avalon_checks.xml、其中sun_checks.xml为默认值。修改默认配置-->
    	<configLocation>google_checkstyle.xml</configLocation>
    </configuration>
    <executions>
        <execution>
            <id>checkstyle</id>
            <phase>validate</phase>
            <goals>
                <goal>check</goal>
            </goals>
            <configuration>
                <failOnViolation>true</failOnViolation>
            </configuration>
        </execution>
    </executions>
</plugin>

定义在maven lifecycle的validate阶段执行check task,并且如果发现有违反标准的情况就会fail当前的build。运行checkstyle检查:mvn checkstyle:checkstyle

跳过对指定文件的某些检查

  • suppression:忽略指定文件的问题检查,不推荐;
  • 新增checkstyle-suppressions.xml文件suppressions配置项:
<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
        "-//Puppy Crawl//DTD Suppressions 1.0//EN"
        "http://www.puppycrawl.com/dtds/suppressions_1_0.dtd">
<suppressions>
    <suppress checks="LineLengthCheck"
              files="SessionMessageSource.java"/>
</suppressions>

<suppressionsLocation>${basedir}/src/config/checkstyle-suppressions.xml</suppressionsLocation> 然后在配置文件里面可以定义一系列可用的模块,每一个模块提供严格程度(强制的,可选的…)可配置的检查规则。规则可以触发通知(notification),警告(warning)和错误(error)。
附:google-checkstyle

特点:

  1. 它可以有效的帮助我们检视代码以便更好的遵循代码编写标准,特别适用于小组开发时彼此间的样式规范和统一。
  2. Checkstyle提供高可配置性,以便适用于各种代码规范,所以除了使用它提供的几种常见标准之外,你也可以定制自己的标准。
  3. Checkstyle提供支持大多数常见IDE的插件,大部分插件中就含有最新的Checkstyle。
  4. Checkstyle可以检查代码的很多方面,从传统观点看,它主要是用来检查代码层面的,自从第三版以后,它的内部架构作了重大改变,很多其它意图的检测加了进来,现在Checkstyle可以检查像类设计的问题,重复代码,如锁的双重检查的bug模式。

报错

Token “METHOD_REF” was not found in Acceptable tokens list in check SeparatorWrapCheck

在IDEA的Terminal执行mvn clean compile报错:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-checkstyle-plugin:3.0.0:check (checkstyle) on project test: Failed during checkstyle configuration: cannot initialize module TreeWalker - Token "METHOD_REF" was not found in Acceptable tokens list in check com.puppycrawl.tools.checkstyle.checks.whitespace.SeparatorWrapCheck.

参考stackoverflow问答java-google-checkstyle-maven

You are trying to use a newer configuration with an old version of Checkstyle.

上面的报错信息提示,使用的Maven插件版本为3.0.0,升级到当前最新版3.3.1解决问题。

TreeWalker is not allowed as a parent of LineLength Please review ‘Parent Module’ section for this Check in web documentation if Check is standard.

继续执行mvn clean compile报错:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-checkstyle-plugin:3.3.1:check (checkstyle) on project test: Failed during checkstyle configuration: cannot initialize module TreeWalker - TreeWalker is not allowed as a parent of LineLength Please review 'Parent Module' section for this Check in web documentation if Check is standard.

参考GitHub issue,LineLength本来在TreeWalker module下面,提升到与TreeWalker同级的module,解决问题。

Google checkstyle实战_配置文件


虽然解决问题,但是这样下去感觉问题会无穷无尽。

升级配置文件

考虑到上面升级过maven插件,即maven-checkstyle-plugin到最新版,那配置文件是不是也得一起升级下?打开托管在GitHub的官方配置文件google_checks,借助于diffchecker这类在线文本对比工具,好家伙。本地配置文件和GitHub里的配置文件相差也太大了吧。是该更新一下了!!

至于为何不直接使用存放在GitHub上的配置文件?这样的话,可以保证一直使用最新的配置文件。而要使用一个下载到本地的必定会过期的备份配置文件?主要是两点考量:

  1. The Wall的存在,访问GitHub速度不是很快很稳定;
  2. 一份可用的配置文件可以保证团队成员使用尽可能相同的编码规范。

Token “LITERAL_SWITCH” was not found in Acceptable tokens list in check RightCurlyCheck.

继续执行mvn clean compile依旧报错:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-checkstyle-plugin:3.3.1:check (checkstyle) on project test: Failed during checkstyle configuration: cannot initialize module TreeWalker - Token "LITERAL_SWITCH" was not found in Acceptable tokens list in check com.puppycrawl.tools.checkstyle.checks.blocks.RightCurlyCheck.

不会吧。插件和配置文件都是最新的,配置文件是官方提供的,没有任何修改。

搜索google_checkstyle.xml文件,可以找到LITERAL_SWITCH及RightCurly。分析此最新版配置文件,不难得出结论:

  • checkstyle有若干个module组成,表示各个不同检查环节
  • LineLength不再是TreeWalker module下的子module,而是和TreeWalker同级,这也正好印证上面一个问题
  • TreeWalker下有若干个module,一个module对应一个方法,如com.puppycrawl.tools.checkstyle.checks.blocks.RightCurlyCheck
  • 那token是什么呢?进阶章节会继续研究

回到问题本身。分析报错,大意是在RightCurly这个module里有个tokens属性字段里不能出现LITERAL_SWITCH?

抱着试一试的想法,修改官方提供的配置文件,删除RightCurly module下LITERAL_SWITCH这个token。

再次执行mvn clean compile,上面这个报错消失。出现新的报错,不过其形式和上面的报错一模一样。那就依样画瓢,找到报错的module和token,删除。最后执行mvn clean compile成功。

进阶

源码分析

上面留下一个疑问:token是什么?

看到完整包路径com.puppycrawl.tools.checkstyle.checks.blocks.RightCurlyCheck,不难找到maven依赖:

<dependency>
    <groupId>com.puppycrawl.tools</groupId>
    <artifactId>checkstyle</artifactId>
    <version>10.13.0</version>
</dependency>

包结构如下:

Google checkstyle实战_maven_02


配置文件google_checkstyle.xml里的module对应的**Check类全部位于com.puppycrawl.tools.checkstyle.checks包下面。并且Check也模块化,有一下几种类型:

Google checkstyle实战_maven_03


与此同时,在目录com.puppycrawl.tools.checkstyle.meta.blocks.blocks下面有一个xml文件RightCurlyCheck.xml,和Check方法一一对应。配置文件里的module对应一个继承AbstractCheck的Check方法,对应一个**Check.xml配置文件。

NoLineWrapCheck.xml文件内容如下:

<?xml version="1.0" encoding="UTF-8"?>
<checkstyle-metadata>
   <module>
      <check fully-qualified-name="com.puppycrawl.tools.checkstyle.checks.whitespace.NoLineWrapCheck"
             name="NoLineWrap"
             parent="com.puppycrawl.tools.checkstyle.TreeWalker">
         <description>Checks that chosen statements are not line-wrapped. By default, this Check restricts wrapping import and package statements, but it's possible to check any statement.</description>
         <properties>
            <property default-value="PACKAGE_DEF,IMPORT,STATIC_IMPORT"
                      name="tokens"
                      type="java.lang.String[]"
                      validation-type="tokenSet">
               <description>tokens to check</description>
            </property>
         </properties>
         <message-keys>
            <message-key key="no.line.wrap"/>
         </message-keys>
      </check>
   </module>
</checkstyle-metadata>

check下的name和配置文件google_checkstyle.xml的module name正好对应,parent指向TreeWalker,fully-qualified-name指向Java类文件。properties定义检查的token。

token是什么,回到文章开头,提到AST语法树及TokenTypes类。

借助于IDEA Double Shift快捷键以及左侧的项目视图,不难快速找到com.puppycrawl.tools.checkstyle.api.TokenTypes类文件,定义194个静态常量。以及tokentypes.properties配置文件,里面正好也是194行。经过对比,是一一对应的。

tokentypes.properties文件样例:

OBJBLOCK=An object block.

message-keys

参考