如何配置Spotless Maven插件实现所有Kotlin源文件格式化

现有配置的适配缺漏 #

你当前编写的插件绑定逻辑、ktlint规则启用的方向是可行的，但实际运行时很容易出现漏扫文件、执行时机不合理的问题，要稳定覆盖全量Kotlin源文件格式化，需要补齐必要的配置项，最终可直接落地的完整配置如下：

<plugin>
    <groupId>com.diffplug.spotless</groupId>
    <artifactId>spotless-maven-plugin</artifactId>
    <version>2.43.0</version> <!-- 显式指定稳定版本，避免不同构建环境拉取的插件版本不一致 -->
    <executions>
        <execution>
            <id>spotless-apply</id>
            <phase>process-sources</phase> <!-- 调整为早于编译的执行阶段，避免先编译不合规代码再格式化的冗余流程 -->
            <goals>
                <goal>apply</goal>
            </goals>
            <configuration>
                <kotlin>
                    <!-- 显式声明全量扫描范围，覆盖所有标准Kotlin源码目录 -->
                    <includes>
                        <include>src/main/kotlin/**/*.kt</include>
                        <include>src/test/kotlin/**/*.kt</include>
                        <include>src/main/kotlin/**/*.kts</include>
                        <include>src/test/kotlin/**/*.kts</include>
                    </includes>
                    <ktlint/>
                    <!-- 可选配置：大项目可开启增量格式化，只处理相对主分支有变更的文件，减少全量扫描耗时 -->
                    <ratchetFrom>origin/main</ratchetFrom>
                </kotlin>
            </configuration>
        </execution>
    </executions>
</plugin>

落地核心要点 #

• 执行阶段选择process-sources：该阶段早于Java/Kotlin编译动作，格式化完成后再进入编译流程，不会出现无效编译的问题；如果保留原有compile阶段绑定，需要等所有源码编译完成后才触发格式化，会浪费构建时间。
• 显式配置扫描范围：如果你的项目Kotlin源码没有放在插件默认识别的约定目录（比如多模块自定义了源码路径、Kotlin代码放在src/main/java目录下），插件不会自动覆盖扫描目标，显式写includes可以保证所有需要格式化的Kotlin文件都被处理。
• 多模块项目适配：如果是多模块Maven项目，把上述插件配置放在根项目的pluginManagement节点下，所有子模块可以自动继承配置，不需要每个模块单独编写重复代码。
• 常用操作命令：
  • 手动触发全量格式化直接运行mvn spotless:apply，不需要走完整编译流程
  • 做格式校验时运行mvn spotless:check，该命令只会校验格式是否合规、不会自动修改文件，适合接入CI流水线做提交卡口

内容的提问来源于stack exchange，提问作者ahoffer