maven 配置代码检查插件，生成检查报告

## 前言

代码风格包含了变量的命名，缩进，注释等内容，在团队开发中，多人协同开发要避免各种风格混合带来的混乱，统一的代码风格是必须的。在开发过程中，我们可以使用一些工具来改进这一状况，比如 checkStyle 工具。

## 开始

> Checkstyle 是一种用于检查 Java 源代码是否遵守代码标准或验证规则集（最佳实践）的工具。

它由这些组成：

- 执行程序：即 checkStyle 的执行程序，它可以再 IDEA 编辑器中启动，也可以在 Maven 插件方式启动，也可以二进制方式启动。
- 代码风格描述规则：以 XML 方式描述的代码风格的规则，比如sun_checks.xml 这个文件。
- 相关的配置文件：比如在使用Maven插件时，插件的配置文件需要配置。

checkStyle 可以通过多种方式使用：

- (1) Maven 插件使用
- (2) Idea 编辑器中使用，请参考：https://www.jianshu.com/p/5f082a91e411
- (3) 二进制应用启动(本文略）

这里推荐[作者blinkfox](https://github.com/blinkfox/java-style)修改的代码风格规则文件，作者很用心，根据[google](https://github.com/checkstyle/checkstyle)的风格进行了修改，比如缩进（谷歌是2个空格缩进，而大众一般是4个空格缩进），同时编写了中文的风格说明，非常赞。
详细规则请参考： [blinkfox-java-style-guide.md](https://github.com/blinkfox/java-style/blob/master/docs/guide/blinkfox-java-style-guide.md)

### Maven 插件方式使用CheckStyle

#### 准备规则文件

推荐使用：https://github.com/blinkfox/java-style

> 当然也可以使用Google最新的：https://github.com/checkstyle/checkstyle
> 但是最新版本的规则由于maven插件不支持，可能会有bug。

下载好[规则文件](https://github.com/blinkfox/java-style/blob/master/docs/checks/blinkfox-checks.xml)后，放到项目根目录下，重命名为`checkstyle.xml`

![](/media/202303/2023-03-22_162017_9774900.7478800278394004.png)

#### 配置maven插件

以聚合项目为例，根pom文件中添加配置和插件（子模块不需要添加）：
```xml

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-checkstyle-plugin</artifactId>
	<version>3.1.2</version>
	<dependencies>
		<dependency>
			<groupId>com.puppycrawl.tools</groupId>
			<artifactId>checkstyle</artifactId>
			<version>9.3</version>
		</dependency>
	</dependencies>
	<configuration>
		<skip>${checkstyle.skip}</skip>
		<encoding>UTF-8</encoding>
		<consoleOutput>true</consoleOutput>
		<failsOnError>true</failsOnError>
		<violationSeverity>warning</violationSeverity>
		<configLocation>checkstyle.xml</configLocation>
		<suppressionsLocation>checkstyle-suppressions.xml</suppressionsLocation>
		<linkXRef>false</linkXRef>
	</configuration>
</plugin>
```

若想在每次构建时自动执行，可以添加如下配置：
```xml
<properties>
	
	<checkstyle.skip>true</checkstyle.skip>
</properties>

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-checkstyle-plugin</artifactId>
	<version>3.1.2</version>
	<dependencies>
		<dependency>
			<groupId>com.puppycrawl.tools</groupId>
			<artifactId>checkstyle</artifactId>
			<version>9.3</version>
		</dependency>
	</dependencies>
	<configuration>
		<skip>${checkstyle.skip}</skip>
		<encoding>UTF-8</encoding>
		<consoleOutput>true</consoleOutput>
		<failsOnError>true</failsOnError>
		<violationSeverity>warning</violationSeverity>
		<configLocation>checkstyle.xml</configLocation>
		<suppressionsLocation>checkstyle-suppressions.xml</suppressionsLocation>
		<linkXRef>false</linkXRef>
	</configuration>
	<executions>
		<execution>
			<id>validate</id>
			<phase>validate</phase>
			<goals>
				<goal>check</goal>
			</goals>
		</execution>
	</executions>
</plugin>
```

疑问：这里添加了属性 `checkstyle.skip`（实际上该属性是`maven-checkstyle-plugin`插件的内置属性，默认值为false，不跳过，这里定义是为了覆盖默认属性值），为什么呢？
解答：配置了checkstyle后，它会在 maven 构建的验证阶段执行，如果失败，会导致编译失败。这里不想让它默认执行，仅在希望执行的时候执行，因此默认是不执行的，只有 ${checkstyle.skip} 是 true 的时候执行，通过 `-Dcheckstyle.skip=false` 进行传参。

#### 添加排除扫描配置

在根目录下添加`checkstyle-suppressions.xml`文件，这个给出示例配置内容：
```xml
<?xml version="1.0"?>

<!DOCTYPE suppressions PUBLIC
    "-//Checkstyle//DTD SuppressionFilter Configuration 1.0//EN"
    "https://checkstyle.org/dtds/suppressions_1_0.dtd">

<suppressions>
    
    <suppress checks="SummaryJavadoc"
              files=".java"/>
    
    <suppress checks="CustomImportOrder"
              files=".java"/>
    
    <suppress checks="MissingJavadocMethod"
              files=".java"/>
    
    <suppress checks=".*"
              files="prepaycard-extend[/\\]"/>
</suppressions>
```

#### 执行maven命令生成xml报告

```
聚合项目需要使用checkstyle:checkstyle-aggregate命令：
mvn checkstyle:checkstyle-aggregate

若配置了checkstyle.skip属性则需要执行如下命令：
mvn checkstyle:checkstyle-aggregate  -Dcheckstyle.skip=false

非聚合项目使用checkstyle:check命令即可：
mvn checkstyle:check
```

- 若聚合项目使用`checkstyle:checkstyle-aggregate`命令，命令执行完毕后，会在根目录下的target中生成`checkstyle-result.xml`问题报告文件。
- 若聚合项目使用`checkstyle:check`命令，将会对每个子模块顺序进行规则检查，一旦检查的模块发现违规就不会继续检查后续的子模块。
- 非聚合项目一般推荐使用`checkstyle:check`命令。

#### 拓展

##### 生成Gitlab的JSON格式报告

由于CheckStyle插件生成的结果为xml格式，Gitlab无法直接使用该文件，需要对xml结果转换，操作如下：

依然以聚合项目为例，根pom文件中添加配置和插件（子模块不需要添加）：

```xml

<plugin>
	<groupId>se.bjurr.violations</groupId>
	<artifactId>violations-maven-plugin</artifactId>
	<version>1.50.7</version>
	<configuration>
		
		
		<maxReporterColumnWidth>0</maxReporterColumnWidth>
		<maxRuleColumnWidth>0</maxRuleColumnWidth>
		<maxSeverityColumnWidth>0</maxSeverityColumnWidth>
		<maxLineColumnWidth>0</maxLineColumnWidth>
		<maxMessageColumnWidth>30</maxMessageColumnWidth>
		
		<codeClimateFile>gl-code-quality-report.json</codeClimateFile>

<minSeverity>INFO</minSeverity>
		
		<detailLevel>VERBOSE</detailLevel>
		
		<maxViolations>99999999</maxViolations>
		
		<printViolations>true</printViolations>

<diffFrom></diffFrom>
		
		<diffTo></diffTo>
		
		<diffMinSeverity>INFO</diffMinSeverity>
		
		<diffDetailLevel>VERBOSE</diffDetailLevel>
		
		<diffMaxViolations>99</diffMaxViolations>
		
		<diffPrintViolations>true</diffPrintViolations>
		
		<gitRepo>.</gitRepo>

<violations>
			<violation>
				<parser>CHECKSTYLE</parser>
				<reporter>Checkstyle</reporter>
				<folder>.</folder>
				<pattern>.*/target/checkstyle-result\.xml$</pattern>
			</violation>
		</violations>
	</configuration>
</plugin>
```

执行maven命令生成json报告：
```Bash
mvn violations-maven-plugin:violations --non-recursive
```

- `--non-recursive`表示不递归子模块中的`/target/checkstyle-result.xml`文件，只需要转换根目录下`/target/checkstyle-result.xml`即可
- 执行完毕后将在根目录下生成`gl-code-quality-report.json`文件

## 参考

- [Maven插件方式执行CheckStyle并自定义风格文件](http://events.jianshu.io/p/4f7333869b9f)
- [maven-checkstyle-plugin官方文档](https://maven.apache.org/plugins/maven-checkstyle-plugin/index.html)
- [Google checkstyle](https://github.com/checkstyle/checkstyle)
- [Blinkfox Google汉化版 checkstyle](https://github.com/blinkfox/java-style)
- [Blinkfox Java 编程风格指南以及风格配置文件](https://blinkfox.github.io/java-style/#/)
- [IDEA 中使用 blinkfox-idea-java-style.xml](https://blinkfox.github.io/java-style/#/README?id=idea-java-style)