Maven Spotless Plugin 在 Java 项目中的应用

1. 概述

本文将介绍 Maven Spotless Plugin 的使用方法，通过它来统一项目代码风格。首先我们会用最小配置分析源码并修复格式问题，然后逐步扩展配置实现自定义规则，最后将检查绑定到特定 Maven 构建阶段。

2. 快速上手

Maven Spotless Plugin 是一个在构建过程中自动格式化代码并强制执行代码规范的工具。使用 Spotless 非常简单，只需在 spotless-maven-plugin 中指定你偏好的代码格式即可。

在 pom.xml 中添加插件并配置使用 Google Java Style：

<plugin>
    <groupId>com.diffplug.spotless</groupId>
    <artifactId>spotless-maven-plugin</artifactId>
    <version>2.43.0</version>
    <configuration>
        <java>
            <googleJavaFormat/>
        </java>
    </configuration>
</plugin>

搞定！现在运行 mvn spotless:check，插件会自动扫描 Java 文件并检查格式是否符合规范。控制台会显示扫描文件数和违规数量：

注意：只要发现一处格式违规，构建就会失败。向下滚动日志能看到具体问题，比如这里代码用了制表符，而 Google 规范要求使用两个空格缩进：

执行 mvn spotless:apply 可自动修复所有违规。修复后对比远程分支的代码差异：

可以看到源码已被正确格式化，符合 Google Java 标准。

3. 自定义格式规则

前面我们用最小配置实现了基础格式检查，但通过 Eclipse Formatter Profile 可以定义更灵活的格式规则。这种 XML 配置文件兼容多种 IDE 和格式化插件。

在项目根目录创建 baeldung-style.xml：

<profiles version="21">
    <profile kind="CodeFormatterProfile" name="baeldung-style" version="21">
        <setting id="org.eclipse.jdt.core.formatter.tabulation.char" value="space"/>
        <setting id="org.eclipse.jdt.core.formatter.use_tabs_only_for_leading_indentations" value="true"/>
        <setting id="org.eclipse.jdt.core.formatter.indentation.size" value="4"/>
        <!--   其他配置...   -->
        <setting id="org.eclipse.jdt.core.formatter.enabling_tag" value="@formatter:on"/>
        <setting id="org.eclipse.jdt.core.formatter.disabling_tag" value="@formatter:off"/>
    </profile>
</profiles>

更新 pom.xml 使用自定义配置（移除替换为 **）：

<plugin>
    <groupId>com.diffplug.spotless</groupId>
    <artifactId>spotless-maven-plugin</artifactId>
    <version>2.43.0</version>
    <configuration>
        <java>
            <eclipse>
                <file>${project.basedir}/baeldung-style.xml</file>
            </eclipse>
        </java>
    </configuration>
</plugin>

现在运行 mvn spotless:check 即可验证代码是否符合自定义规范。

4. 扩展功能

除了格式检查，Spotless 还能执行静态分析并自动优化代码。在指定代码风格后，可添加以下扩展步骤：

<java>
    <eclipse>
        <file>${project.basedir}/baeldung-style.xml</file>
    </eclipse>

    <licenseHeader>
        <content>/* (C)$YEAR */</content>
    </licenseHeader>

    <importOrder/>
    <removeUnusedImports />
    <formatAnnotations />
</java>

执行 spotless:apply 时，每个步骤会处理特定规则：

✅ 检查文件是否包含正确的版权头
✅ 和确保导入语句有序且无冗余
✅ 强制类型注解与字段声明同行

运行命令后，所有优化会自动应用：

spotless static analysis

5. 绑定 Maven 构建阶段

目前我们都是手动执行 spotless:check 和 spotless:apply，**其实可以将这些目标绑定到特定 Maven 阶段**。Maven 阶段是构建生命周期的预定义节点，按顺序执行任务。

例如将 spotless:check 绑定到 package 阶段（打包阶段）：

<plugin>
    <groupId>com.diffplug.spotless</groupId>
    <artifactId>spotless-maven-plugin</artifactId>
    <version>2.43.0</version>
    
    <configuration>
        <java>
            <!--  格式化规则和扩展步骤  -->
        </java>
    </configuration>
    
    <executions>
        <execution>
            <goals>
                <goal>check</goal>
            </goals>
            <phase>package</phase>
        </execution>
    </executions>
</plugin>

这样每次执行 mvn package 时会自动触发代码检查。如果代码不符合规范，构建会直接失败，强制团队保持代码风格一致。

6. 总结

本文介绍了 Maven Spotless Plugin 的核心功能：从基础的 Google Java 格式检查，到自定义 Eclipse 格式规则，再到扩展的静态分析优化，最后通过绑定 Maven 阶段实现自动化检查。合理使用这些功能，能有效提升团队代码质量和一致性。

完整代码示例可在 GitHub 获取。

Persistence

REST

Security