Maven插件—代码规范格式化spotless-maven-plugin

前言

博主介绍：✌目前全网粉丝3W+，csdn博客专家、Java领域优质创作者，博客之星、阿里云平台优质作者、专注于Java后端技术领域。

涵盖技术内容：Java后端、大数据、算法、分布式微服务、中间件、前端、运维等。

博主所有博客文件目录索引：博客目录索引(持续更新)

CSDN搜索：长路

视频平台：b站-Coder长路

一、认识spotless-maven-plugin插件

spotless-maven-plugin插件介绍

Spotless 是一个通用格式插件 ，可用于在 Java 项目中强制执行代码样式和格式规则。它对于在整个团队中强制执行一致的风格以及确保您的代码满足某些质量标准特别有用。

Spotless是一个强大的工具，可以帮助确保你的代码具有一致性、可读性和高质量。通过将其集成到Maven构建过程中，您可以轻松检查代码中的任何样式和格式问题，并自动修复，从而节省时间和精力。

spotless-maven-plugin 是一个用于在 Maven 项目中强制执行代码风格和格式化规则的插件。它支持多种编程语言，包括 Java、JavaScript、XML 等。

为什么需要 spotless-maven-plugin？

在大型项目或开源项目中，由于开发人员众多，代码格式往往不统一，这会影响代码的可读性和维护性。spotless-maven-plugin 是一个强大的工具，可以自动格式化代码并强制执行一致的代码风格。

二、如何使用spotless-maven-plugin插件

2.1、自定义spotless-maven-plugin插件配置（maven插件）

通用模板与需要修改点

功能：该插件主要用于自动格式化 Java 代码和 pom.xml 文件，同时清理未使用的导入。

配置要点：

• 使用 google-java-format 的 AOSP 样式进行格式化。
• 移除未使用的 import。
• 自定义 import 的顺序。
• 对 pom.xml 文件进行 4 空格缩进的格式化。
• 在 process-sources 阶段执行 apply 和 check 目标，确保代码符合格式化规则。

通用模板：

<!--   自动格式化代码强制工具  -->
<plugin>
    <groupId>com.diffplug.spotless</groupId>
    <artifactId>spotless-maven-plugin</artifactId>
    <version>2.22.8</version>
    <configuration>
        <java>
            <!-- 配置格式化规则
                不建议GOOGLE：默认缩进两格，AOSP是四格
             -->
            <googleJavaFormat>
                <version>1.7</version>
                <style>AOSP</style>
            </googleJavaFormat>
            <!-- license顶部声明 -->
<!--                        <licenseHeader>-->
<!--                            <content>/* (C)$YEAR */</content>-->
<!--                        </licenseHeader>-->
            <!--  移除未使用的引用import  -->
            <removeUnusedImports />
            <!--  import 导入的顺序 空白（,,）：表示多加一个空行。
                  默认是都带上一个空行的，这里是为了区分自己模块代码和其他引用模块代码
              -->
            <importOrder>
                <order>com.changlu,,javax,java,scala,\#</order>
            </importOrder>
        </java>
        <!--   单独针对pom.xml来进行格式化，指定缩进的空格数，这里是 4。这意味着 POM 文件中的每个缩进级别将使用 4 个空格。  -->
        <pom>
            <includes>
                <include>pom.xml</include>
            </includes>
            <sortPom>
                <nrOfIndentSpace>4</nrOfIndentSpace>
            </sortPom>
        </pom>
    </configuration>
    <!--   定义插件的执行配置
        <executions> ：配置插件的执行方式和时机
        定义了插件在 Maven 生命周期的哪个阶段（phase）执行哪些目标（goals）
     -->
    <executions>
        <execution>
            <!--   定义操作的唯一标识   -->
            <id>format</id>
            <goals>
                <!--  执行应用代码格式化规则，根据<configuration> 中定义的规则去进行格式化
   								 这里我们注释掉，打包项目的时候并不直接进行代码格式化，而是需要用户自己去主动格式化
									-->
<!--                <goal>apply</goal>-->
                <!--  代码格式化检查：如果代码不符合规则，Spotless 插件会抛出构建错误，确保代码风格一致   -->
                <goal>check</goal>
            </goals>
            <!--  Maven 的生命周期阶段之一：在 compile 阶段之前执行，用于处理源代码   -->
            <phase>process-sources</phase>
        </execution>
    </executions>
</plugin>

**需要修改的仅仅只有如下importOrder配置：**将你自己的业务代码开头替换com.changlu即可

<importOrder>
    <order>com.changlu,,javax,java,scala,\#</order>
</importOrder>

执行命令

1、自动执行（推荐）

通用模板中已经将 spotless:check 绑定到了 process-sources 阶段，你可以直接运行以下命令来触发格式化和检查：

mvn clean install

• mvn clean install：
  • clean：清理项目的 target 目录。
  • install：构建项目并安装到本地 Maven 仓库。

在执行 install 时，Maven 会自动执行 process-sources 阶段，从而触发 spotless:check。

2、手动执行

如果你只想单独运行 spotless:apply 或 spotless:check，可以使用以下命令：

mvn spotless:apply

这个命令会根据 pom.xml 中定义的规则自动格式化代码。

mvn spotless:check

这个命令会检查代码是否符合格式化规则。如果代码不符合规则，构建将失败，并显示具体的错误信息。

3、仅运行 spotless:apply 或 spotless:check

如果你只想运行 spotless:apply 或 spotless:check，而不执行其他 Maven 生命周期阶段，可以使用以下命令：

mvn spotless:apply -Dspotless.apply

mvn spotless:check -Dspotless.check

实际应用场景（打包项目进行限制）

我们通常会对项目进行打包，如果打包的时候出现了如下的报错，则就说明，代码未进行格式化，有格式问题：

往下翻提示说，让我们去执行命令来进行格式化：

此时就需要我们去进行代码格式化命令：

mvn spotless:apply

格式化后，我们再去执行打包命令就没有问题了：

拆解通用自定义模板插件配置说明

第一部分：插件基本信息

<plugin>
    <groupId>com.diffplug.spotless</groupId>
    <artifactId>spotless-maven-plugin</artifactId>
    <version>2.22.8</version>

• <groupId>：插件的组 ID，这里是 com.diffplug.spotless。
• <artifactId>：插件的 artifact ID，这里是 spotless-maven-plugin。
• <version>：插件的版本号，这里是 2.22.8，表示使用该插件的特定版本。

第二部分：配置部分（）

java代码格式化配置：

<java>
    <!-- 配置格式化规则 -->
    <googleJavaFormat>
        <version>1.7</version>
        <style>AOSP</style>
    </googleJavaFormat>
    <!-- 移除未使用的引用import -->
    <removeUnusedImports></removeUnusedImports>
    <!-- import 导入的顺序 -->
    <importOrder>
        <order>com.changlu,,javax,java,scala,\#</order>
    </importOrder>
</java>

• <googleJavaFormat>：使用 Google 提供的 Java 格式化工具 google-java-format。
  • <version>：指定使用的版本，这里是 1.7。
  • <style>：指定格式化风格，这里是 AOSP，表示采用 Android 开源项目的代码风格（默认缩进为 4 格）。
• <removeUnusedImports>：自动移除未使用的 import 引用。
• <importOrder>：
  • 配置 import 的顺序。
  • <order>：定义了 import 的顺序，内容是 com.changlu,,javax,java,scala,\#。
    • com.changlu：自定义模块的 import。
    • ,,：表示两个空格分隔符之间插入一个空行。
    • javax、java、scala：标准库和第三方库的导入顺序。
    • \#：表示注释部分。

pom文件格式化配置：

<pom>
    <includes>
        <include>pom.xml</include>
    </includes>
    <sortPom>
        <nrOfIndentSpace>4</nrOfIndentSpace>
    </sortPom>
</pom>

• <pom>：针对 pom.xml 文件的格式化配置。
• <includes>：指定需要处理的文件，这里是 pom.xml。
• <sortPom>：对 pom.xml 文件进行排序和格式化。
  • <nrOfIndentSpace>：设置缩进的空格数，这里是 4，表示每个缩进级别使用 4 个空格。

第三部分：插件执行配置（）

<executions>
    <execution>
        <id>format</id>
        <goals>
            <goal>apply</goal>
            <goal>check</goal>
        </goals>
        <phase>process-sources</phase>
    </execution>
</executions>

• <executions>：定义插件的执行配置。
• <execution>：一个独立的执行配置。
• <id>：执行的唯一标识符，这里是 format，用于区分不同的执行配置。
• <goals>：指定插件执行的目标。
  • <goal>apply</goal>：应用配置的格式化规则，对代码进行格式化。
  • <goal>check</goal>：检查代码是否符合格式化规则，如果不符，构建会失败。
• <phase>：指定插件目标绑定到 Maven 生命周期的哪个阶段。
  • 这里是 process-sources，表示在 process-sources 阶段执行格式化操作。

2.2、配合git钩子，实现代码提交时的格式化校验

配置方式

在.git目录下的hooks文件中，创建脚本名为：pre-commit文件

配置文件内容如下：

#!/bin/sh
mvn spotless:check
if [ $? -ne 0 ]; then
    echo "代码格式化检查未通过，请运行 'mvn spotless:apply' 修复代码格式。"
    exit 1
fi

这段脚本会在提交之前运行 mvn spotless:check 命令，如果检查未通过，则阻止提交。

接着我们给这个文件来设置可执行权限：

chmod +x .git/hooks/pre-commit

实际应用场景（commit代码进行限制）

当我们去提交一个未格式化的代码时，会出现这个报错：

点击查看详情：

此时，则需要我们手动去执行命令来进行代码格式化。

配置参数知识补充

pom中phase配置对应匹配的Maven 生命周期分类

Maven 有一个清晰的生命周期（Lifecycle）概念，它定义了一系列的阶段（Phases）。每个阶段都有特定的执行顺序，并且每个阶段可以绑定一个或多个插件目标（Goals）。以下是 Maven 的生命周期阶段：

Maven 有三个主要的生命周期（Lifecycles）：

1. Clean Lifecycle：用于清理项目。
2. Default Lifecycle：用于构建项目的核心部分，从清理到部署。
3. Site Lifecycle：用于生成项目文档和报告。

阶段一：Clean 生命周期

Clean 生命周期主要负责清理项目，包括删除输出目录（如 target 目录）。它的主要阶段包括：

• pre-clean：在执行清理操作之前执行。
• clean：删除输出目录（通常是 target 目录）。
• post-clean：在执行清理操作之后执行。

阶段二：Default 生命周期

Default 生命周期是 Maven 最核心的生命周期，包含了项目从清理到部署的完整流程。它的主要阶段如下：

验证和初始化阶段

• validate：验证项目的配置是否正确，所有必要的信息是否可用。
• initialize：初始化项目，如设置构建环境。

依赖、资源和编译阶段

• generate-sources：生成额外的源代码，如自动生成的代码。
• process-sources：处理源代码，例如进行代码格式化。
• generate-resources：生成额外的资源文件。
• process-resources：将资源文件（如配置文件）从源目录复制到输出目录，并进行过滤（如变量替换）。
• compile：编译项目的主源代码。
• process-classes：处理编译后的类文件，例如进行字节码增强。

测试阶段

• generate-test-sources：生成额外的测试源代码。
• process-test-sources：处理测试源代码。
• generate-test-resources：生成额外的测试资源文件。
• process-test-resources：将测试资源文件从源目录复制到输出目录，并进行过滤。
• test-compile：编译测试代码。
• process-test-classes：处理编译后的测试类文件。
• test：运行测试，但不会打包或部署测试结果。

包裝和集成阶段

• prepare-package：在打包之前进行一些准备工作。
• package：将编译后的代码打包成可分发的格式（如 JAR、WAR）。
• pre-integration-test：在执行集成测试之前进行一些准备工作，例如启动服务器。
• integration-test：运行集成测试，通常涉及外部系统（如数据库）。
• post-integration-test：在集成测试完成之后进行一些清理工作，例如停止服务器。

验证和部署阶段

• verify：运行任何检查以验证包是否有效且达到质量标准。
• install：将包安装到本地仓库，供其他项目依赖。
• deploy：将最终的包部署到远程仓库（如公司的 Maven 仓库）。

阶段三：Site 生命周期

Site 生命周期主要用于生成项目文档和报告。它的主要阶段包括：

• pre-site：在生成站点之前执行。
• site：生成项目文档和站点。
• post-site：在生成站点之后执行。
• site-deploy：将生成的站点部署到服务器。

参考文章

[1]. Maven Spotless Plugin for Java | Baeldung：https://www.baeldung-cn.com/java-maven-spotless-plugin

[2]. 在 Maven 中使用 Spotless：https://www.jdon.com/64533.html

整理者：长路 时间：2025.26

资料获取

大家点赞、收藏、关注、评论啦~

精彩专栏推荐订阅：在下方专栏👇🏻

• 长路-文章目录汇总（算法、后端Java、前端、运维技术导航）：博主所有博客导航索引汇总
• 开源项目Studio-Vue—校园工作室管理系统(含前后台，SpringBoot+Vue)：博主个人独立项目，包含详细部署上线视频，已开源
• 学习与生活-专栏：可以了解博主的学习历程
• 算法专栏：算法收录

更多博客与资料可查看👇🏻获取联系方式👇🏻，🍅文末获取开发资源及更多资源博客获取🍅