Checkstyle 入门指南 | Baeldung中文网

1. 概述

Checkstyle 是一款开源工具，用于检查代码是否符合可配置的规则集。

本文将介绍如何通过 Maven 和 IDE 插件将 Checkstyle 集成到 Java 项目中。

下文提到的插件相互独立，可单独集成到构建环境或 IDE 中。例如，在 Eclipse 中运行检查时，并不需要在 pom.xml 中配置 Maven 插件。

2. Checkstyle Maven 插件

2.1. Maven 配置

在项目中添加 Checkstyle，需在 pom.xml 的 reporting 部分添加插件：

<reporting>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-checkstyle-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <configLocation>checkstyle.xml</configLocation>
            </configuration>
        </plugin>
    </plugins>
</reporting>

该插件内置两种预定义检查：Sun 风格和 Google 风格。项目默认使用 sun_checks.xml。

要使用自定义配置，可按上述示例指定配置文件路径。此时插件将读取自定义配置而非默认配置。

最新插件版本可在 Maven Central 查找。

2.2. 报告生成

配置好 Maven 插件后，运行 mvn site 命令即可生成代码检查报告。构建完成后，报告将保存在 target/site 目录下的 checkstyle.html 文件中。

Checkstyle 报告包含三个核心部分：

文件列表：
报告此部分展示发生违规的文件列表，并按严重级别统计违规数量。以下是文件列表部分的示例：

规则概览：
此部分提供用于检测违规的规则概览，展示规则类别、违规数量及严重级别。以下是规则部分的示例：

违规详情：
最后，详情部分提供违规的具体信息，精确到代码行号。以下是详情部分的示例：

2.3. 构建集成

若需强制执行代码规范，可配置插件在代码不符合标准时直接中断构建。

通过在插件定义中添加执行目标实现：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>${checkstyle-maven-plugin.version}</version>
    <configuration>
        <configLocation>checkstyle.xml</configLocation>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

configLocation 属性指定验证所用的配置文件（此处为 checkstyle.xml）。执行部分中的 check 目标使插件在构建的 verify 阶段运行，并在发现违规时强制中断构建。

现在运行 mvn clean install 命令，插件将扫描文件违规情况，发现违规时构建失败。

也可直接运行 mvn checkstyle:check（无需配置执行目标），存在验证错误时同样会导致构建失败。

3. Eclipse 插件

3.1. 配置方式

与 Maven 集成类似，Eclipse 允许使用自定义配置。

导入配置步骤：

进入 Window -> Preferences -> Checkstyle
在 Global Check Configurations 部分点击 New
在弹出的对话框中指定自定义配置文件路径

3.2. 报告查看

配置完成后，即可用插件分析代码。

检查项目代码规范：

右键点击 Eclipse Project Explorer 中的项目
选择 CheckStyle -> Check Code with Checkstyle

插件会在 Eclipse 文本编辑器中直接反馈 Java 代码问题，同时生成可在 Eclipse 中查看的违规报告。

查看报告步骤：

进入 Window -> Show View -> Other
搜索 Checkstyle，选择 Violations 或 Violations Chart 视图

任一视图都会按类型分组展示违规情况。以下是示例项目的违规饼图：

点击饼图区域可跳转到代码中的具体违规列表。

也可直接打开 Eclipse 的 Problem 视图查看插件报告的问题。以下是 Eclipse 的 Problem 视图示例：

点击任何警告将跳转到发生违规的代码位置。

4. IntelliJ IDEA 插件

4.1. 配置方式

与 Eclipse 类似，IntelliJ IDEA 也支持项目级自定义配置。

配置步骤：

打开 Settings 并搜索 Checkstyle
点击 + 按钮添加配置
指定配置 XML 文件路径
选择新配置并点击 OK 启用

4.2. 报告查看

配置完成后，即可检查代码违规。检查项目违规步骤：

进入 Analyze -> Inspect Code
在 Checkstyle 部分查看违规结果

检查结果视图将展示 Checkstyle 部分的违规情况。以下是示例报告：

点击违规项将跳转到文件中的具体违规行。

5. 自定义 Checkstyle 配置

在 Maven 报告生成部分（第 2.2 节），我们使用自定义配置文件执行代码规范检查。

若不想使用内置的 Google 或 Sun 规则，可创建自定义配置 XML 文件。

以下是用于上述检查的自定义配置文件：

<!DOCTYPE module PUBLIC
  "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
  "http://www.puppycrawl.com/dtds/configuration_1_3.dtd">
<module name="Checker">
    <module name="TreeWalker">
        <module name="AvoidStarImport">
            <property name="severity" value="warning" />
        </module>
    </module>
</module>

5.1. DOCTYPE 定义

文件首行的 DOCTYPE 定义至关重要，它指定了 DTD 下载地址，使系统能正确解析配置。

若省略此定义，配置文件将无效。

5.2. 模块结构

配置文件主要由模块组成。每个模块通过 name 属性定义其功能，该属性值对应插件中实际执行的类。

5.3. 模块详解

Checker：模块树结构的根节点，定义所有子模块继承的属性
TreeWalker：检查单个 Java 源文件，定义适用于文件检查的属性
AvoidStarImport：禁止在 Java 代码中使用星号导入（*），并通过 severity 属性将此类问题标记为警告级别

更多自定义配置说明可参考官方文档。

6. Spring-Rest 项目报告分析

本节以 GitHub 上的 spring-rest 项目为例，使用第 5 节创建的自定义配置进行 Checkstyle 分析。

6.1. 违规报告生成

将配置导入 Eclipse IDE 后，生成的项目违规报告如下：

报告警告应避免使用通配符导入（*）。有两个文件不符合此标准。点击警告将跳转到包含违规的 Java 文件。

以下是 HeavyResourceController.java 文件显示的警告：

6.2. 问题解决

使用星号导入通常是不良实践，当两个或多个包包含同名类时会导致冲突。

例如，List 类同时存在于 java.util 和 java.awt 包中。若同时导入 java.util. 和 *java.awt.*，编译器将因 List 冲突而失败。

解决上述问题：整理两个文件的导入语句并保存。重新运行插件后，违规消失，代码符合自定义配置中的规范。

7. 总结

本文介绍了在 Java 项目中集成 Checkstyle 的基础知识。

我们了解到 Checkstyle 是一款简单而强大的工具，可确保开发者遵循组织制定的代码规范。

本文用于静态分析的示例代码可在 GitHub 获取。

Persistence

REST

Security