Checkstyle简介
Checkstyle是SourceForge下的一个项目,官网:
https://checkstyle.sourceforge.io/
在官网有详细的说明。
Checkstyle是一个开发工具,可以帮助开发者自动检查java代码是否遵循编程规范,将开发者从枯燥繁琐的手工检查中解脱出来。
Checkstyle是可以配置的,方便应用自己定制化的编程规范。
Google Java代码样式指南:
https://checkstyle.sourceforge.io/styleguides/google-java-style-20180523/javaguide.html
Sun Java代码样式规范:
https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConvTOC.doc.html
使用checkstyle有几种方式,这几种方式互相独立,可以根据自己的需要来选择。用eclipse checkstyle插件的方式可以在编码的过程中实时看到违反规则的项
- 在maven工程中,通过maven checkstyle插件来运行checkstyle
- 在eclipse中,使用eclipse checkstyle插件来运行checkstyle
checkstyle不同版本对JRE 和 JDK的版本要求
方式一:用Maven下载安装、运行checkstyle
在Maven 的pom.xml文件中配置下载安装checkstyle
备注:其实这个步骤可以省略。因为在maven工程中第一次运行checkstyle:checkstyle这个goal的时候,会自动将maven插件版本下载下来,而maven插件的pom文件中已经指明了对checkstyle版本的依赖,所以也会将Checkstyle下载下来。对于maven-checkstyle-plugin 3.3.0这个插件版本,里边默认指定的checkstyle版本就是9.3版本。当然,如果自己想用其它的checkstyle版本,那么需要这一步骤。
例如,要安装9.3版本,将下面的代码片段放在Maven工程pom.xml文件的dependencies段落里面:
<!-- https://mvnrepository.com/artifact/com.puppycrawl.tools/checkstyle -->
<dependency>
<groupId>com.puppycrawl.tools</groupId>
<artifactId>checkstyle</artifactId>
<version>9.3</version>
</dependency>
过一会儿,就下载到Maven本地仓库了:
checkstyle版本中预先定义的两个规则检查文件
在下载下来的checkstyle版本中,有预先定义的两个规则检查文件,分别是sun_checks.xml 和google_checks.xml。如果要看内容,可以打开checkstyle-9.3.jar文件:
打开checkstyle-9.3.pom这个文件,观察一下内容片段,其中将sun_checks.xml 和google_checks.xml包含了进来:
Maven的checkstyle插件
备注:Maven的checkstyle插件和checkstyle不是一回事。Maven checkstyle插件调用了checkstyle进行检查。
有关Maven Checkstyle插件的详细介绍,可以参考官网:https://maven.apache.org/plugins/maven-checkstyle-plugin/
如果不想明确指定maven的插件版本的话,那么在maven工程中第一次运行checkstyle:checkstyle这个goal的时候,会自动将maven插件版本下载下来。例如,我的maven版本是3.8.8版本,自动下载的Maven checkstyle插件版本是3.3.0:
Checkstyle插件版本maven-checkstyle-plugin 3.3.0默认使用Checkstyle 9.3版本,需要Java 8及以上。
打开maven-checkstyle-plugin-3.3.0.pom这个文件,看下内容片段:
当然也可以配置另外的版本:
https://maven.apache.org/plugins/maven-checkstyle-plugin/examples/upgrading-checkstyle.html
用maven运行checkstyle的方式
maven checkstyle插件有三个goals:
- checkstyle:checkstyle 运行Checkstyle检查并生成一个html形式的报告(html格式和xml文件格式)。
- checkstyle:checkstyle-aggregate 当有多个模块时,运行checkstyle检查并生成一个聚合形式的报告(html格式和xml文件格式)。
- checkstyle:check 运行Checkstyle检查并将违反规则的地方显示在控制台;如果有违反规则的地方,build失败。
goal:checkstyle:checkstyle
这个goal的详细介绍:https://maven.apache.org/plugins/maven-checkstyle-plugin/checkstyle-mojo.html
执行这个goal,可以运行Checkstyle检查,并生成一个html形式的报告。
有很多参数可以进行控制,goal的详细介绍页有对每个参数的说明。
例如,这个参数可以配置规则集文件的路径,默认执行的是sun_checks.xml。
在eclipse中运行maven goal:checkstyle:checkstyle
运行输出:
到maven工程的target/site目录下查看,生成了checkstyle.html结果文件:
打开这个文件,看看具体内容:
其实,在target目录下面,还有规则集文件、结果的xml文件形式(这个截图是后来执行截取的):
在cmd窗口中运行maven goal:checkstyle:checkstyle
在cmd窗口,到maven工程的目录(即含有pom.xml文件的目录)下,执行命令
mvn checkstyle:checkstyle
到target目录下查看,生成了如下内容:
其中checkstyle-checker.xml是使用的规则集文件(应该是从checkstyle发布包中拷贝过来的)。
checkstyle-result.xml是生成结果的xml文件形式。
到target/site目录下查看:
这个是结果的html文件形式。
goal:checkstyle:checkstyle-aggregate
这个goal的详细介绍请参考:https://maven.apache.org/plugins/maven-checkstyle-plugin/checkstyle-aggregate-mojo.html
当有多个模块时,运行checkstyle检查并生成一个聚合形式的报告(html格式和xml文件格式)。
有很多参数可以控制。
在eclipse中运行maven goal:checkstyle:checkstyle-aggregate
下面一个工程中有三个模块。
在clipse中运行maven goal:checkstyle-aggregate:
运行结果:
到target目录下查看,生成了xml形式的结果报告:
到target/site目录下查看,生成了html形式的结果报告:
在cmd窗口执行maven goal:checkstyle-aggregate
下面一个工程中有三个模块,到cmd窗口输入如下命令:
mvn checkstyle:checkstyle-aggregate
到target目录下查看,生成了xml文件的结果:
到target/site目录下查看,生成了html形式的报告:
goal:checkstyle:check
这个goal的详细介绍:https://maven.apache.org/plugins/maven-checkstyle-plugin/check-mojo.html
执行这个goal,可以运行checkstyle检查并将违反规则的地方显示在控制台;如果有违反规则的地方,build失败。
有很多参数可以进行控制,goal的详细介绍页有对每个参数的说明。
在cmd窗口执行maven goal:checkstyle:check
到cmd窗口输入如下命令:
mvn checkstyle:check
运行输出:
到target目录下查看,也生成了xml文件保存的结果:
打开这个xml文件,看看内容:
在eclipse中执行maven goal:checkstyle:check
到target目录下查看,也生成了xml形式的结果报告:
用maven运行checkstyle检查后,可以查看实际使用的规则集文件
无论是cmd窗口下,还是在Eclipse中,只要运行maven checkstyle插件的三个goal中任何一个:
- checkstyle:checkstyle
- checkstyle:checkstyle-aggregate
- checkstyle:check
在输出目录(默认是target目录)下面,都会将检查中实际使用的checkstyle规则集文件拷贝过来,命名为checkstyle-checker.xml:
可以打开maven下载包中的sun_checks.xml文件,和target目录下生成的checkstyle-checker.xml文件,对比下,其实内容是相同的(默认使用的是sun_checks.xml文件,而不是google_checks.xml):
maven下载包中的sun_checks.xml文件:
target目录下生成的checkstyle-checker.xml文件:
在maven工程的pom文件中指定checkstyle规则集文件的路径
说明
checkstyle发布版本预置了sun_checks.xml和google_checks.xml两个规则集文件,默认使用sun_checks.xml。但可以定制自己的规则集文件,例如,可以在sun_checks.xml的基础上定制自己的规则集文件。
定制好自己的规则集文件,可以放在合适的地方,以便引用。例如,可以在工程的根目录下创建一个config目录,在config目录下再创建checkstyle子目录,将定制的规则集文件放在该目录下:
maven checkstyle插件有个配置参数configLocation,可以配置规则集文件的路径:
<configuration>
<configLocation>config/checkstyle/checkstyle.xml</configLocation>
</configuration>
想让定制的规则集文件生效,根据不同的需要,可以将maven checkstyle插件的信息放在pom文件的不同段落内:
- 如果放在build下面的plugins段落内,那么执行maven checkstyle的三个goal的时候都可以执行到。但执行maven site阶段的时候无法执行到。
- 如果放置在reporting下面的plugins段落内,那么执行maven的site 这个阶段的时候会执行到。但执行maven checkstyle的三个goal的时候执行不到。
- 如果既想在maven checkstyle的三个goal的时候执行到,也想在执行maven site阶段的时候执行到,那么就两个地方都放。
在pom文件build下面的pluginManagement段落内的plugins小节增加maven checkstyle插件信息
在这个地方增加maven checkstyle插件信息,方便在build下面的plugins段落内、或者reporting下面的plugins段落内引用。
备注:如果这个地方不增加maven checkstyle插件信息,那么在reporting下面的plugins段落内直接使用maven checkstyle插件,会提醒artifactId找不到。
例如:
在pom文件build下面的plugins段落内增加checkstyle的规则集文件路径
例如:
下面可以在cmd窗口下执行checkstyle:checkstyle这个goal试试,看看是否生效:
target目录下面,自动将定制化的规则集的内容拷贝了过来,就是checkstyle-checker.xml这个文件(只是将内容拷贝了过来,文件的名字修改了)。
也生成了检测结果的xml形式的文件checkstyle-result.xml:
target/site目录下面,生成了html形式的结果文件:
注意,因为我们没有在reporting下面的plugins段落内增加maven checkstyle插件信息,所以执行maven的site这个goal的是,没有生成checkstyle检查结果。
在cmd窗口下先执行mvn clean命令清除以前的输出,然后执行mvn site命令,看看结果:
从输出信息中没有看到checkstyle检查结果。
到target目录下面和target/site目录下面查看,确实没有checkstyle检查结果:
在pom文件reporting下面的plugins段落内增加checkstyle的规则集文件路径
例如:
在cmd窗口下先执行mvn clean命令清除以前的输出,然后执行mvn site命令,看看结果:
从输出信息可以看到,生成了checkstyle检查结果,用的就是我们制定的规则集文件。
在pom文件reporting下面的plugins段落内增加checkstyle的规则集文件路径,但在build下面的plugins段落内没有指定
<build>
<pluginManagement>
<plugins>
<plugin>
<artifactId>maven-site-plugin</artifactId>
<version>3.7</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>3.3.0</version>
</plugin>
</plugins>
</pluginManagement>
<plugins>
<plugin>
<artifactId>maven-site-plugin</artifactId>
</plugin>
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.0.0</version>
</plugin>
<plugin>
<artifactId>maven-failsafe-plugin</artifactId>
<version>3.0.0</version>
</plugin>
</plugins>
</build>
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<configuration>
<configLocation>config/checkstyle/checkstyle.xml</configLocation>
</configuration>
</plugin>
</plugins>
</reporting>
在cmd窗口下执行mvn clean命令清空输出:
然在cmd窗口下执行mvn checkstyle:checkstyle命令:
从上面输出信息可以看到,此时调用的是默认的规则集文件sun_checks.xml。
下面在cmd窗口下执行mvn clean命令清空输出:
下面在cmd窗口下执行mvn site命令:
从上面输出可以看到,执行执行site这个goal引用的是我们定制的规则集文件,这是因为在reporting下面的plugins段落内进行了指定。
方式二:安装eclipse checkstyle插件,用eclipse checkstyle插件运行checkstyle
说明
eclipse checkstyle插件官网:https://checkstyle.org/eclipse-cs/#!/
安装eclipse checkstyle插件
三种安装方式简介
安装方式:
https://checkstyle.org/eclipse-cs/#!/install
有三种安装方式:
- 用安装页面的install按钮拖拉方式安装(eclipse的版本是2021-06及以上)
- 用Eclipse Marketplace client安装
- 从更新网站安装。
用安装页面的install按钮拖拉方式安装
用上面页面中的install按钮拖拉方式安装的前提条件:**
1)已经启动了eclipse(eclipse的版本是2021-06及以上)。
2)eclipse中安装了Eclipse Marketplace Client
- 打开页面https://marketplace.eclipse.org/marketplace-client-intro?mpc_install=150
- 找到Install按钮
- 鼠标按住网页中的Install按钮不要松开,拖到eclipse中的workspace中,自动弹出下面窗口:
过一段时间,搜索完成,出现如下界面:
- 点击下面的Confirm按钮:
- 勾选“I accept the terms of the licence agreement”,并单击下面的Finish按钮:
查看进展:
备注:由于网络原因,可能一次某个进度的时候就失败了,那就重新开始上面的过程,会接着上次失败的地方继续安装,多试几次就成功了。
- 到了一定的进展,弹出窗口,手动勾选Always trust all content:,点击Trust Selected,继续安装进程:
- 过了一会儿,安装完成,点击Restart Now,重启Eclipse:
- Eclipse重启后,点击Window->Preferences :
左侧出现Checkstyle,单击上去,右面出现内容框,说明eclipse Checkstyle插件已经安装成功了。
设置eclipse Checkstyle默认使用的规则集
点击Window->Preferences :
左侧出现Checkstyle,单击上去,右面出现内容框:
复选框中的内容根据自己的需要勾选就行了。
假设要将Sun Checks作为默认的话,鼠标点击到这行上,点击右侧的“Set as Default”按钮,然后点击下面的“Apply and Close”按钮,在弹出框中,根据自己需要选择Yes或者No,修改就生效了:
在某个项目中启动Checkstyle
方法一:在项目的Properties中设置激活Checkstyle
鼠标右键单击要启动Checkstyle的项目,在弹出菜单中选择Properties:
在属性窗口中,点击左侧的Checkstyle,在右侧界面勾选“Checkstyle active for this project”,然后单击下方的Apply and Close:
回到程序界面,点击下面的Problems,可以看到检测出了6个不满足项:
在违反了规则的代码左侧,也显示了图标:
鼠标放上去,可以显示违反规则的具体提示:
方法二:在popup菜单中选择用Checkstyle立即检查代码
在项目上右键单击,在出现的弹出菜单中选择Checkstyle->Check Code with Checkstyle:
出现了检查结果:
方法三:在popup菜单中选择激活Checkstyle
在项目上右键单击,在出现的弹出菜单中选择Checkstyle->Activate Checkstyle:
项目下次编译的时候,就会检查代码的违反项。我们可以输入一个空行,然后保存,就触发了检查:
设置使用定制的外部规则集文件
点击Window->Preferences:
单击左侧的Checkstyle,然后单击右侧的New按钮:
出现配置窗口:
在下拉列表中选择External Configuration File:
输入一个名字,在Location中选择外部的规则集文件:
点击OK按钮,回到Checkstyle窗口,看到外部的规则集文件已经增加进来了。可以设置为默认,或者在单个项目中选择。