代码质量护航：结合Checkstyle、SpringBoot与Git的最佳实践

散一世繁华，颠半世琉璃

已于 2024-09-14 16:28:53 修改

阅读量768

点赞数 10

分类专栏： java 文章标签： spring boot git elasticsearch

于 2024-09-14 16:26:19 首次发布

本文链接：https://blog.csdn.net/qq_51447436/article/details/142256708

版权

java 专栏收录该内容

73 篇文章 5 订阅

订阅专栏

在团队开发中，保持一致的代码风格和高质量的代码至关重要。为了提升团队的整体代码质量，防止低质量代码的提交，使用工具对代码进行自动化检查是非常有效的手段之一。在这篇博客中，我将介绍如何通过结合 Checkstyle、Spring Boot 和 Git 来实现代码在提交前的自动化检查，确保团队成员遵循统一的代码规范，并避免常见的代码错误。

通过在 Git 提交（commit）前引入 Checkstyle 进行代码检查，可以有效防止不符合代码规范的代码进入仓库。以下是这种做法带来的几大好处：

提升代码质量：自动化的代码检查可以捕捉许多常见的编码错误，如未使用的导入、不规范的命名等。
保持代码一致性：团队成员遵循统一的编码规范，减少代码审查时对风格问题的讨论。
减少潜在问题：在代码提交前及时发现问题，避免将低质量代码推送到代码库中。

接下来我们将按照以下步骤来实现这个自动化代码检查过程。

1. 配置 Checkstyle 插件

首先，我们需要为 Spring Boot 项目引入 Checkstyle 插件，以便能够对代码进行静态分析并检查代码规范。
步骤：

在 pom.xml 中添加 Maven Checkstyle 插件的依赖：

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-checkstyle-plugin</artifactId>
				<version>3.3.1</version>
				<dependencies>
					<dependency>
						<groupId>com.puppycrawl.tools</groupId>
						<artifactId>checkstyle</artifactId>
						<version>8.44</version>
					</dependency>
				</dependencies>
				<executions>
					<execution>
						<id>validate</id>
						<phase>validate</phase>
						<goals>
							<goal>check</goal>
						</goals>
					</execution>
				</executions>
				<configuration>
					<configLocation>checkstyle.xml</configLocation>
					<consoleOutput>true</consoleOutput>
					<!-- 随机返回非零的数 -->
					<failsOnError>true</failsOnError>
					<!-- 警告阻塞 -->
					<failOnViolation>true</failOnViolation>
				</configuration>
</plugin>

注意：我在 <configLocation> 标签中指定了 checkstyle.xml，因此需要将该文件放在项目的顶级目录下。你也可以根据项目的实际情况修改 <configLocation> 标签中的路径，确保它指向你自定义的 checkstyle.xml 文件所在的位置。

这个插件会在构建过程的 validate 阶段运行，并使用指定的 checkstyle.xml 文件来检查代码。如果发现不符合规定的代码，将终止构建并输出错误信息。

2. 创建 pre-commit 钩子脚本

为了确保代码在提交到 Git 仓库之前通过 Checkstyle 检查，我们可以编写一个 Git 的 pre-commit 钩子脚本。这个脚本会在提交代码时自动运行 Maven Checkstyle 检查，确保每次提交的代码符合规范。

步骤：

在项目的 .git/hooks 目录中创建 pre-commit 文件：

#!/bin/sh
# pre-commit hook to run Maven Checkstyle and show details about issues

echo "正在运行 Maven Checkstyle..."

# 获取项目根目录
PROJECT_ROOT=$(git rev-parse --show-toplevel)

# 切换到包含 pom.xml 的 test 目录
cd "$PROJECT_ROOT" || exit 1

# 获取即将提交的 Java 文件差异
changed_files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.java$')

if [ -z "$changed_files" ]; then
    echo "没有 Java 文件发生变化，跳过 Checkstyle 检查。"
    exit 0
fi

# 运行 Maven Checkstyle 插件，并将输出重定向到变量
output=$(mvn checkstyle:check 2>&1)

# 检查 Checkstyle 执行状态
if [ $? -ne 0 ]; then
    echo "Checkstyle 检查失败。提交已被中止。"

    # 输出 Checkstyle 错误信息，并翻译为中文提示
    echo "$output" | grep -E "\[ERROR\]" | sed -e 's/^\[ERROR\] /错误: /' | \
        sed -e 's/UnusedImports/未使用的导入/; s/MethodName/方法名/; s/RedundantImport/重复导入/'
    # 获取出错的文件和行号
    echo "以下文件中发现问题："
    for file in $changed_files; do
        echo "$file:"
        git diff --cached "$file"
    done

    echo "请根据错误信息修正代码后重新提交。"
    exit 1
fi

echo "Checkstyle 检查通过。继续提交。"
exit 0

注意：执行 mvn 命令时，需确保当前路径与 pom.xml 文件在同一目录级别，否则将无法正常执行。在上述脚本中，PROJECT_ROOT 表示 .git 的根目录。如果 pom.xml 文件不与 .git 处于同一级目录，则需要通过 cd 切换到包含 pom.xml 的正确目录。
在这里插入图片描述
这个脚本会在每次提交之前检查 .java 文件是否符合 Checkstyle 规范。如果有问题，提交将被阻止，提示开发者修复问题后再提交。

3. 编写 Checkstyle 配置文件（checkstyle.xml）

checkstyle.xml 是用于定义代码检查规则的配置文件。可以根据团队的编码规范，逐步增加和自定义规则。以下是一个示例的 checkstyle.xml 文件，包含了几项常见的代码检查规则。

<module name="TreeWalker">
    <!-- 检查未使用以及重复导入的语句 -->
    <module name="UnusedImports"/>
    <module name="RedundantImport"/>
</module>

<module name="TreeWalker">
    <!-- 检查方法名命名规范，确保方法名以小写字母开头 -->
    <module name="MethodName"/>
</module>

<module name="TreeWalker">
    <!-- 检查 switch 语句是否有 default 分支 -->
    <module name="MissingSwitchDefault"/>
</module>

各模块说明：

UnusedImports：检查未使用的导入语句，确保代码中没有多余的 import 语句。
RedundantImport：检查重复的导入语句，确保没有多次导入相同的类。
MethodName：检查方法名的命名规范，确保所有方法名以小写字母开头并遵循命名约定。
MissingSwitchDefault：检查 switch 语句是否包含 default 分支，以确保所有可能的分支都被处理。

这些模块是可以扩展和定制的，随着项目的发展，可以根据需要逐步增加新的检查规则。

4. CheckStyle检查规则

Checkstyle 提供了多种基础的代码格式检查规则，涵盖了代码风格、命名约定、缩进、空格使用、导入语句等多个方面。以下是一些常见的基础代码格式检查规则，你可以根据需求添加到你的 checkstyle.xml 中：

1. 命名规范 (Naming Conventions)

ClassTypeParameterName：类的泛型参数命名规范。
ConstantName：常量必须使用全大写加下划线命名。
MethodName：方法名称必须以小写字母开头。
PackageName：包名称必须是全小写。
ParameterName：方法参数命名规范。
VariableName：变量命名规范。

<module name="TreeWalker">
    <module name="ClassTypeParameterName"/>
    <module name="ConstantName"/>
    <module name="MethodName"/>
    <module name="PackageName"/>
    <module name="ParameterName"/>
    <module name="VariableName"/>
</module>

2. 代码风格 (Code Style)

WhitespaceAfter：要求在某些标点符号（如逗号、分号等）后必须有空格。
WhitespaceAround：要求在某些运算符（如 =, +, -, == 等）两边必须有空格。
EmptyLineSeparator：在某些元素之间必须有空行分隔。
NoLineWrap：禁止换行。
LineLength：限制一行的最大字符数（通常 80 或 120）。
Indentation：检查代码缩进，默认是 4 个空格。
LeftCurly：大括号 { 的位置检查，可以配置为换行还是同一行。

<module name="TreeWalker">
    <module name="WhitespaceAfter"/>
    <module name="WhitespaceAround"/>
    <module name="EmptyLineSeparator"/>
    <module name="NoLineWrap"/>
    <module name="LineLength">
        <property name="max" value="120"/>
    </module>
    <module name="Indentation">
        <property name="basicOffset" value="4"/>
    </module>
    <module name="LeftCurly"/>
</module>

3. 导入语句检查 (Import Statements)

UnusedImports：检查未使用的导入语句。
AvoidStarImport：禁止使用 * 通配符导入。
RedundantImport：检查重复的导入语句。

<module name="TreeWalker">
    <module name="UnusedImports"/>
    <module name="AvoidStarImport"/>
    <module name="RedundantImport"/>
</module>

4. 注释规范 (Comments)

JavadocMethod：检查每个方法是否有完整的 Javadoc 注释。
JavadocType：检查每个类、接口或枚举是否有 Javadoc 注释。
JavadocVariable：检查每个类变量是否有 Javadoc 注释。
TodoComment：检查是否有 TODO 注释。
CommentSize：检查注释的最小/最大长度。

<module name="TreeWalker">
    <module name="JavadocMethod"/>
    <module name="JavadocType"/>
    <module name="JavadocVariable"/>
    <module name="TodoComment"/>
    <module name="CommentSize"/>
</module>

5. 控制结构 (Control Structures)

NeedBraces：要求 if, else, for, while 等控制语句必须使用大括号。
SimplifyBooleanExpression：简化布尔表达式检查。
SimplifyBooleanReturn：简化布尔返回值（如 return x == true 改为 return x）。
AvoidNestedBlocks：避免嵌套代码块。
EmptyBlock：禁止空的代码块。
AvoidInlineConditionals：禁止使用内联三元操作符（?:）。

<module name="TreeWalker">
    <module name="NeedBraces"/>
    <module name="SimplifyBooleanExpression"/>
    <module name="SimplifyBooleanReturn"/>
    <module name="AvoidNestedBlocks"/>
    <module name="EmptyBlock"/>
    <module name="AvoidInlineConditionals"/>
</module>

6. 其他常用检查

FinalParameters：方法参数必须声明为 final。
FinalLocalVariable：局部变量必须声明为 final。
MissingSwitchDefault：检查 switch 语句是否有 default 分支。
EqualsHashCode：检查 equals 和 hashCode 方法是否同时存在。
IllegalTokenText：禁止使用某些标识符或文本（如 ==、!=）。
MagicNumber：禁止直接使用魔法数字，要求使用常量。

<module name="TreeWalker">
    <module name="FinalParameters"/>
    <module name="FinalLocalVariable"/>
    <module name="MissingSwitchDefault"/>
    <module name="EqualsHashCode"/>
    <module name="IllegalTokenText"/>
    <module name="MagicNumber"/>
</module>

以上是一些常见的基础 Checkstyle 代码检查规则，你可以根据项目需求选择合适的规则，并将它们添加到你的 checkstyle.xml 配置文件中。通过使用这些规则，能够确保代码风格一致性、提高代码质量、减少不必要的错误和维护成本。

5. 效果检验

按照上述步骤配置完毕后，每当开发者提交代码时，Git 的 pre-commit 钩子会触发 Maven Checkstyle 插件进行代码检查。提交的代码必须符合预定的代码规范，否则提交将被阻止，并在终端显示相应的错误提示。

效果示例：

当代码中存在未使用的导入或方法命名不规范时，提交将被拦截，并显示类似如下的错误信息：

在这里插入图片描述

这不仅能有效地提高团队代码的一致性和规范性，还能在提交阶段及时发现问题，减少后期的代码审查负担。
通过结合 Checkstyle 插件、Git 钩子和 Spring Boot 项目，我们能够实现提交前的自动代码检查，确保团队成员提交的代码符合规范，保持项目代码库的高质量和一致性。
随着项目的迭代和需求的变化，团队还可以根据具体情况不断扩展 Checkstyle 的规则，进一步提升代码的可维护性和可读性。