Google checkstyle实战

概述

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，解决问题。

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

升级配置文件

考虑到上面升级过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.xml里的module对应的**Check类全部位于com.puppycrawl.tools.checkstyle.checks包下面。并且Check也模块化，有一下几种类型：

与此同时，在目录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

参考