Google-Java-Format

← 返回目录 > ← 返回总览

工具	说明
Checkstyle	Java 代码风格与规范检查企业级标准
Spotless	Maven/Gradle 生态多语言格式化插件，内置 google-java-format 支持
PMD	Java 代码坏味道检测，含 CPD 复制粘贴检测
SpotBugs	Java 潜在 Bug 检测（FindBugs 继任者）

1. 简介

google-java-format 是由 Google 开发并维护的 Java 代码格式化工具，能够将 Java 源代码自动重新格式化为符合 Google Java Style Guide 的统一风格。该工具使用 JDK 内部编译器 API（javac）对 Java 源代码进行精确解析，然后按照 Google Java Style 规范进行格式化输出。

主要检查语言：Java
主要检查能力：Java 代码格式化，支持 Google Style 和 AOSP Style 两种风格预设；涵盖代码格式化（自动修复型）
核心检查原理：使用 jdk.compiler 模块解析 Java 源代码生成 AST，零配置设计确保格式一致性
检查规则/选项：刻意不提供格式化算法的可配置项，仅暴露少量 CLI flag（如 --aosp、--fix-imports-only、--skip-sorting-imports 等），选项说明
GitHub 仓库：https://github.com/google/google-java-format（6,144 stars）
开源协议：Apache-2.0
最新稳定版本：v1.25.2
运行环境要求：需 JRE 11+
误报率：无

2. 官方文档

资源	链接
GitHub 仓库	https://github.com/google/google-java-format
README 文档	https://github.com/google/google-java-format/blob/master/README.md
Google Java Style Guide	https://google.github.io/styleguide/javaguide.html
Releases 下载页	https://github.com/google/google-java-format/releases
Maven Central	https://central.sonatype.com/artifact/com.google.googlejavaformat/google-java-format
IntelliJ 插件（JetBrains Marketplace）	https://plugins.jetbrains.com/plugin/8527
IntelliJ 插件源码	https://github.com/google/google-java-format/tree/master/idea_plugin
Eclipse 插件源码	https://github.com/google/google-java-format/tree/master/eclipse_plugin
官方 diff 脚本	https://github.com/google/google-java-format/blob/master/scripts/google-java-format-diff.py
贡献指南	https://github.com/google/google-java-format/blob/master/CONTRIBUTING.md

第三方集成文档：

资源	链接
Spotless Maven 插件（google-java-format 段）	https://github.com/diffplug/spotless/tree/main/plugin-maven#google-java-format
Spotless Gradle 插件（google-java-format 段）	https://github.com/diffplug/spotless/tree/main/plugin-gradle#google-java-format
spotify/fmt-maven-plugin	https://github.com/spotify/fmt-maven-plugin
googlejavaformat-action（GitHub Action）	https://github.com/axel-op/googlejavaformat-action
VS Code 扩展	https://marketplace.visualstudio.com/items?itemName=JoseVSeb.google-java-format-for-vs-code

3. 社区优秀实践

3.1 Google Guava

Google Guava 是 Google 核心基础库，是 Java 生态中使用最广泛的工具库之一。作为 Google 自家项目，Guava 的代码风格直接代表了 Google Java Style 的最佳实践。

仓库：https://github.com/google/guava
说明：Guava 是 google-java-format 的典型用户，其代码风格完全遵循 Google Java Style Guide。作为 Google 内部广泛使用的 Java 核心工具库，Guava 是学习 Google Java Style 格式化效果的最佳参考项目。

3.2 Android Open Source Project (AOSP)

Android 开源项目在系统框架层使用 AOSP 风格（4 空格缩进）的 google-java-format。

仓库：https://android.googlesource.com/platform/frameworks/base
说明：Android 生态中大量项目采用 --aosp 参数进行格式化，确保与 Android 源码风格一致。google-java-format 的 AOSP Style 即源自 Android 开源项目的代码风格规范。

3.3 Spring Boot（通过 Spotless 集成）

Spring Boot 是 Java 生态中最具影响力的开源框架之一，其项目本身通过 Spotless 集成 google-java-format 进行代码格式化。

仓库：https://github.com/spring-projects/spring-boot
说明：Spring Boot 在构建流程中集成 Spotless，使用 googleJavaFormat() 格式化 Java 代码，并绑定到构建生命周期中，确保每次构建都验证代码格式。这是 Java 生态中通过构建工具集成 google-java-format 的典型实践。

4. 工具配置说明

4.1 配置文件说明

google-java-format 采用零配置设计，不提供格式化规则的配置文件。这是有意为之的设计决策，目的是确保所有使用该工具的项目遵循完全相同的代码风格。所有可调控行为均通过命令行选项或宿主插件（如 Spotless）参数传入。

配置方式	形式	用途
命令行选项	CLI 参数	控制代码风格（`AOSP`）、import 处理、Javadoc 格式化等
`.editorconfig`	INI	跨 IDE 基础格式统一（缩进、换行符等），由 IDE 读取，google-java-format 不直接解析

4.2 命令行选项详解

google-java-format 的可配置选项仅限于以下命令行参数：

选项	类型	说明
`--aosp`	flag	使用 AOSP 代码风格（4 空格缩进），默认为 GOOGLE 风格（2 空格缩进）
`--fix-imports-only`	flag	仅修复 import 顺序和未使用 import，不进行其他格式化
`--skip-sorting-imports`	flag	跳过 import 排序
`--skip-removing-unused-imports`	flag	跳过移除未使用 import
`--skip-reflowing-long-strings`	flag	跳过超长字符串重排
`--skip-javadoc-formatting`	flag	跳过 Javadoc 格式化
`--skip-removing-trailing-whitespace`	flag	跳过移除行尾空白
`--dry-run` / `-n`	flag	仅打印需修改的文件，不实际修改
`--set-exit-if-changed`	flag	若有文件被修改则返回非零退出码（CI 门禁用）
`--replace` / `-r`	flag	原地修改文件
`--lines` / `-l`	string	仅格式化指定行范围（格式 `start:end`）
`--offset`	int	仅格式化从指定偏移开始的内容
`--length`	int	仅格式化指定长度的内容

参考：google-java-format README

推荐配置示例：

以下为 CI 门禁中常见的命令行用法，强制执行 GOOGLE 风格并在有改动时返回非零退出码：

# 检查模式：仅打印需修改的文件，有改动则 CI 失败
google-java-format --dry-run --set-exit-if-changed $(find src -name '*.java')

# 原地修复模式
google-java-format --replace $(find src -name '*.java')

# Android 项目使用 AOSP 风格
google-java-format --aosp --replace $(find src -name '*.java')

4.3 EditorConfig 基础配置

在项目根目录创建 .editorconfig 文件，确保跨 IDE 的基础格式一致：

# https://editorconfig.org
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.java]
indent_style = space
indent_size = 2
# Android 项目使用 4 空格
# indent_size = 4

[*.xml]
indent_style = space
indent_size = 4

[*.md]
trim_trailing_whitespace = false

5. 主流集成方式

5.1 Maven 集成（生态主流，优先）

方式一：通过 Spotless Maven 插件（推荐）

Spotless 是 Java 生态中最主流的格式化统一管理工具，内置对 google-java-format 的一等支持。

<build>
    <plugins>
        <plugin>
            <groupId>com.diffplug.spotless</groupId>
            <artifactId>spotless-maven-plugin</artifactId>
            <version>2.43.0</version>
            <configuration>
                <java>
                    <!-- 使用 google-java-format，默认 Google Style（2 空格） -->
                    <googleJavaFormat>
                        <version>1.27.0</version>
                        <style>GOOGLE</style>
                        <reflowLongStrings>true</reflowLongStrings>
                        <formatJavadoc>false</formatJavadoc>
                    </googleJavaFormat>
                    <!-- 移除未使用的 import -->
                    <removeUnusedImports/>
                    <!-- 清理行尾空白 -->
                    <trimTrailingWhitespace/>
                    <!-- 文件末尾添加换行 -->
                    <endWithNewline/>
                </java>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>check</goal>
                    </goals>
                    <phase>compile</phase>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

常用命令：

mvn spotless:check    # 检查格式（不修改文件）
mvn spotless:apply    # 自动格式化并修复

方式二：通过 spotify/fmt-maven-plugin

spotify/fmt-maven-plugin 是 Spotify 维护的专用 Maven 插件，直接封装 google-java-format，被 1,700+ 项目使用。

<build>
    <plugins>
        <plugin>
            <groupId>com.spotify.fmt</groupId>
            <artifactId>fmt-maven-plugin</artifactId>
            <version>2.27.0</version>
            <executions>
                <execution>
                    <goals>
                        <goal>format</goal>
                    </goals>
                </execution>
            </executions>
            <dependencies>
                <dependency>
                    <groupId>com.google.googlejavaformat</groupId>
                    <artifactId>google-java-format</artifactId>
                    <version>1.27.0</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

说明：显式指定 google-java-format 依赖版本可确保与 IDE 插件、pre-commit 钩子使用完全一致的版本，避免格式化结果不一致。如不指定，则使用 fmt-maven-plugin 自带的默认版本。

常用命令：

mvn com.spotify.fmt:fmt-maven-plugin:format    # 格式化代码
mvn com.spotify.fmt:fmt-maven-plugin:check     # 检查格式

fmt-maven-plugin 还支持以下配置选项：

选项	说明	默认值
`style`	`google` 或 `aosp`	`google`
`verbose`	是否打印每个格式化文件	`false`
`skipSortingImports`	跳过 import 排序	`false`
`skipRemovingUnusedImports`	跳过移除未使用 import	`false`
`skipReflowingLongStrings`	跳过长字符串重排	`true`
`filesNamePattern`	文件名匹配模式	`.*\.java`

增量检查：Spotless 默认仅处理有变更的文件，无需额外配置即可实现增量检查。

mvn spotless:check    # 自动跳过未修改的文件

通过 Spotless Ratchet 模式（渐进式格式化），可从指定基准开始仅检查新增或变更的代码格式，适合在已有项目中渐进式引入格式化：

<configuration>
    <!-- 仅检查相对于 origin/main 分支变更的文件 -->
    <ratchetFrom>origin/main</ratchetFrom>
    <java>
        <googleJavaFormat>
            <version>1.27.0</version>
        </googleJavaFormat>
    </java>
</configuration>

mvn spotless:check    # 仅检查基准之后的变更

通过 fmt-maven-plugin，format goal 默认绑定到 process-sources 阶段，check goal 默认绑定到 verify 阶段：

mvn com.spotify.fmt:fmt-maven-plugin:check    # 检查格式

5.2 IDE 集成

IntelliJ IDEA / Android Studio

安装插件：打开 File -> Settings -> Plugins，在 Marketplace 搜索 google-java-format，点击 Install，重启 IDE。
启用插件：进入 File -> Settings -> Other Settings -> google-java-format Settings，勾选 Enable google-java-format。
选择风格：选择 Google Style（2 空格）或 AOSP Style（4 空格）。
配置 JVM 参数（JDK 16+ 必需）：进入 Help -> Edit Custom VM Options...，添加以下内容并重启 IDE：

--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED

使用方式：安装启用后，插件会替换 IDE 默认的 Reformat Code（Ctrl+Alt+L / Cmd+Option+L）和 Optimize Imports（Ctrl+Alt+O / Cmd+Option+O）操作。

官方插件源码：https://github.com/google/google-java-format/tree/master/idea_plugin

VS Code

在 VS Code 扩展市场搜索并安装 google-java-format-for-vs-code：

扩展 ID：JoseVSeb.google-java-format-for-vs-code
Marketplace：https://marketplace.visualstudio.com/items?itemName=JoseVSeb.google-java-format-for-vs-code

配置 settings.json：

{
  "[java]": {
    "editor.defaultFormatter": "JoseVSeb.google-java-format-for-vs-code"
  },
  "editor.formatOnSave": true
}

Eclipse

从 Releases 页面下载 Eclipse 插件 JAR 文件（如 google-java-format-eclipse-plugin-1.27.0.jar）。
将插件文件放入 Eclipse 的 dropins 目录。
编辑 eclipse.ini，在 -vmargs 之后添加以下 JVM 参数并重启 Eclipse：

--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED

进入 Window -> Preferences -> Java -> Code Style -> Formatter，选择 google-java-format（2 空格）或 aosp-java-format（4 空格）。

官方插件源码：https://github.com/google/google-java-format/tree/master/eclipse_plugin

5.3 命令行使用方式

从 GitHub Releases 下载 JAR 文件或 GraalVM 原生二进制文件。

使用 JAR 文件：

# 基本格式化（输出到标准输出）
java -jar google-java-format-1.27.0-all-deps.jar MyClass.java

# 原地替换文件
java -jar google-java-format-1.27.0-all-deps.jar --replace MyClass.java

# 格式化多个文件
java -jar google-java-format-1.27.0-all-deps.jar --replace src/main/java/**/*.java

# 使用 AOSP 风格（4 空格缩进）
java -jar google-java-format-1.27.0-all-deps.jar --aosp --replace MyClass.java

# 仅格式化指定行范围（增量格式化）
java -jar google-java-format-1.27.0-all-deps.jar --lines 10:30 MyClass.java

# 仅修复 import 语句（排序 + 移除未使用）
java -jar google-java-format-1.27.0-all-deps.jar --fix-imports-only MyClass.java

# 跳过 import 排序
java -jar google-java-format-1.27.0-all-deps.jar --skip-sorting-imports MyClass.java

# 跳过移除未使用的 import
java -jar google-java-format-1.27.0-all-deps.jar --skip-removing-unused-import MyClass.java

# 跳过长字符串重排
java -jar google-java-format-1.27.0-all-deps.jar --skip-reflowing-long-strings MyClass.java

# 跳过 Javadoc 格式化
java -jar google-java-format-1.27.0-all-deps.jar --skip-javadoc-formatting MyClass.java

# 检查模式（不修改文件，格式不符时返回非零退出码）
java -jar google-java-format-1.27.0-all-deps.jar --set-exit-if-changed MyClass.java

# 干运行（打印会变更的文件路径）
java -jar google-java-format-1.27.0-all-deps.jar --dry-run MyClass.java

# 从文件读取选项和文件名
java -jar google-java-format-1.27.0-all-deps.jar @options.txt

# 查看帮助
java -jar google-java-format-1.27.0-all-deps.jar --help

# 查看版本
java -jar google-java-format-1.27.0-all-deps.jar --version

使用 GraalVM 原生二进制文件（无需安装 JDK）：

Releases 页面提供 Linux（x86-64/arm64）、macOS（arm64）和 Windows（x86-64）的原生二进制文件，可直接运行而无需安装 JDK。

增量检查：google-java-format 提供多种原生增量参数，支持行范围格式化、字符偏移量格式化和干运行检查。

--lines 参数（行范围格式化）：

# 仅格式化第 10 到 30 行
java -jar google-java-format-1.27.0-all-deps.jar --lines 10:30 MyClass.java

# 格式化多个不连续的行范围
java -jar google-java-format-1.27.0-all-deps.jar --lines 1:10 --lines 20:30 MyClass.java

--offset / --length 参数（字符偏移量格式化）：

# 从第 100 个字符开始，格式化 50 个字符的范围
java -jar google-java-format-1.27.0-all-deps.jar --offset 100 --length 50 MyClass.java

--dry-run 参数（干运行检查）：

# 打印会变更的文件路径，不修改文件
java -jar google-java-format-1.27.0-all-deps.jar --dry-run --replace src/main/java/**/*.java

使用官方 diff 脚本检查变更行

google-java-format 提供了 google-java-format-diff.py 脚本，可仅检查 Git diff 中变更行的格式：

# 检查暂存区的变更（pre-commit 场景）
git diff -U0 --cached -- '*.java' | python3 scripts/google-java-format-diff.py -p1

# 检查工作区中未暂存的变更
git diff -U0 -- '*.java' | python3 scripts/google-java-format-diff.py -p1

# 检查最近一次提交的变更
git diff -U0 HEAD^ -- '*.java' | python3 scripts/google-java-format-diff.py -p1

# 检查两个 commit 之间的变更
git diff -U0 commit1..commit2 -- '*.java' | python3 scripts/google-java-format-diff.py -p1

脚本地址：https://github.com/google/google-java-format/blob/master/scripts/google-java-format-diff.py

基于 Git 的命令行增量方案

# 获取变更的 Java 文件列表并格式化
git diff --name-only --diff-filter=ACMR -- '*.java' | xargs java -jar google-java-format-1.27.0-all-deps.jar --replace

# 仅检查暂存区的 Java 文件
git diff --name-only --cached -- '*.java' | xargs java -jar google-java-format-1.27.0-all-deps.jar --set-exit-if-changed

pre-commit 增量方案

google-java-format 本身不直接作为 pre-commit hook 使用，而是通过 Spotless 间接集成。pre-commit 的增量能力由 Spotless 的集成方式决定，参见 Spotless 的 pre-commit 增量方案。

如果需要直接通过 pre-commit local hook 调用 google-java-format CLI：

- repo: local
  hooks:
    - id: google-java-format
      name: Google Java Format
      entry: java -jar google-java-format-all-deps.jar --replace
      language: system
      files: \.java$

--replace 参数会原地修改文件（修复模式），pre-commit 默认只传暂存区变更文件，天然实现增量。修改文件后 pre-commit 会终止提交，需重新 git add。但推荐通过 Spotless 集成以获得更好的 Maven/Gradle 生态支持。

CI 脚本调用：

GitHub Actions（通过 Spotless Maven）

name: Java Format Check
on: [push, pull_request]

jobs:
  formatting:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: "21"
          distribution: "temurin"
      - name: Check formatting
        run: mvn spotless:check

GitLab CI

# .gitlab-ci.yml
format-check:
  image: maven:3.9-eclipse-temurin-21
  script:
    - mvn spotless:check
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

增量检查：CI/CD 场景下需获取完整 Git 历史以支持增量检查。

GitHub Actions（增量：通过 googlejavaformat-action）

name: Format Check
on: [push, pull_request]

jobs:
  formatting:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 获取完整历史以支持增量检查
      - uses: axel-op/googlejavaformat-action@v4
        with:
          args: "--set-exit-if-changed"
          skip-commit: true

GitHub Actions（增量：通过 Maven + Spotless）

name: Format Check
on: [push, pull_request]

jobs:
  formatting:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: "21"
          distribution: "temurin"
      - name: Check formatting
        run: mvn spotless:check

GitLab CI（增量）

# .gitlab-ci.yml
format-check:
  image: maven:3.9-eclipse-temurin-21
  script:
    - mvn spotless:check
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

5.4 GitHub Action 插件

使用社区维护的 axel-op/googlejavaformat-action，被 1,300+ 项目使用：

检查格式（推荐用于 PR 门禁）：

# .github/workflows/format-check.yml
name: Java Format Check
on: [push, pull_request]

jobs:
  formatting:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: axel-op/googlejavaformat-action@v4
        with:
          args: "--set-exit-if-changed"

自动格式化并提交：

name: Auto Format
on:
  push:
    branches: [main]

jobs:
  formatting:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: axel-op/googlejavaformat-action@v4
        with:
          args: "--replace"

打印 diff 并失败（不提交）：

name: Format Check
on: [push, pull_request]

jobs:
  formatting:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: axel-op/googlejavaformat-action@v4
        with:
          args: "--replace"
          skip-commit: true
      - name: Print diffs
        run: git --no-pager diff --exit-code

googlejavaformat-action 支持的输入参数：

参数	说明	默认值
`args`	传递给 google-java-format 的命令行参数	`--replace`
`release-name`	指定 google-java-format 版本（如 `v1.27.0`）	自动选择兼容版本
`files`	文件匹配模式	`*/.java`
`files-excluded`	排除文件模式	-
`skip-commit`	设为 `true` 不自动提交	`false`
`commit-message`	自定义提交消息	`Google Java Format`

5.5 Gradle 集成

通过 Spotless Gradle 插件（推荐）

// build.gradle
plugins {
    id 'com.diffplug.spotless' version '7.0.0'
}

spotless {
    java {
        // 使用 google-java-format，默认最新版本
        googleJavaFormat()
        // 或指定版本和风格
        // googleJavaFormat('1.27.0')
        // googleJavaFormat('1.27.0', 'AOSP')  // Android 项目使用 AOSP 风格

        removeUnusedImports()
        trimTrailingWhitespace()
        endWithNewline()

        // 自定义 import 排序
        importOrder('java', 'javax', 'com', 'org', '')
    }
}

// build.gradle.kts
plugins {
    id("com.diffplug.spotless") version "7.0.0"
}

spotless {
    java {
        googleJavaFormat("1.27.0")
        removeUnusedImports()
        trimTrailingWhitespace()
        endWithNewline()
        importOrder("java", "javax", "com", "org", "")
    }
}

常用命令：

./gradlew spotlessCheck    # 检查格式
./gradlew spotlessApply    # 自动格式化

增量检查：Spotless Gradle 插件自动跳过未修改的文件，同样支持 ratchetFrom 渐进式格式化。

./gradlew spotlessCheck    # Spotless 自动跳过未修改的文件

spotless {
    ratchetFrom 'origin/main'
    java {
        googleJavaFormat('1.27.0')
    }
}

6. 告警抑制（屏蔽）方法

由于 google-java-format 是格式化工具而非检查工具，其"告警抑制"的本质是跳过特定代码段或文件的格式化。

6.1 通过代码注释屏蔽（行级/块级）

使用 @formatter:off / @formatter:on 注释标记跳过特定代码段的格式化。该方法在 IntelliJ IDEA、Eclipse 以及 Spotless 中均被支持：

// @formatter:off
Map<String, String> map = ImmutableMap.of(
    "key1", "value1",
    "key2", "value2",
    "key3", "value3"
);
// @formatter:on

注意：@formatter:off / @formatter:on 是 IntelliJ IDEA 和 Eclipse 的通用格式化控制标记，Spotless 在集成 google-java-format 时也遵循此约定。google-java-format 命令行工具本身不直接识别此标记，需通过 Spotless 或 IDE 插件间接支持。

参考：IntelliJ IDEA 配置项目设置

6.2 通过 Spotless 的 `toggleOffOn` 配置屏蔽

在使用 Spotless 集成时，可以自定义格式化跳过标记：

Gradle：

spotless {
    java {
        googleJavaFormat()
        // 默认支持 @formatter:off / @formatter:on
        toggleOffOn()
        // 或自定义标记字符串
        // toggleOffOn("// @formatter:off", "// @formatter:on")
    }
}

参考：Spotless Gradle 插件文档 - toggleOffOn

Maven：

<configuration>
    <java>
        <googleJavaFormat>
            <version>1.27.0</version>
        </googleJavaFormat>
        <toggleOffOn/>
        <!-- 或自定义标记 -->
        <!-- <toggleOffOn>// @formatter:off</toggleOffOn> -->
    </java>
</configuration>

参考：Spotless Maven 插件文档 - spotless:off and spotless:on

6.3 通过集成工具配置排除文件/目录

Spotless Gradle - exclude 配置：

spotless {
    java {
        googleJavaFormat()
        target 'src/main/java/**/*.java'
        // 排除特定文件或目录
        exclude 'src/main/java/generated/**'
    }
}

参考：Spotless Gradle 插件文档

Spotless Maven - excludes 配置：

<configuration>
    <java>
        <googleJavaFormat>
            <version>1.27.0</version>
        </googleJavaFormat>
        <excludes>
            <exclude>src/main/java/generated/**/*.java</exclude>
        </excludes>
    </java>
</configuration>

参考：Spotless Maven 插件文档

fmt-maven-plugin - filesNamePattern 配置：

<configuration>
    <filesNamePattern>.*\.java</filesNamePattern>
    <additionalSourceDirectories>
        <param>src/main/java</param>
    </additionalSourceDirectories>
</configuration>

参考：spotify/fmt-maven-plugin 文档

6.4 通过命令行参数屏蔽

google-java-format 命令行工具支持以下参数控制格式化行为：

# 跳过 import 排序
java -jar google-java-format-1.27.0-all-deps.jar --skip-sorting-imports MyClass.java

# 跳过移除未使用的 import
java -jar google-java-format-1.27.0-all-deps.jar --skip-removing-unused-import MyClass.java

# 跳过长字符串重排
java -jar google-java-format-1.27.0-all-deps.jar --skip-reflowing-long-strings MyClass.java

# 跳过 Javadoc 格式化
java -jar google-java-format-1.27.0-all-deps.jar --skip-javadoc-formatting MyClass.java

# 仅修复 import（不格式化代码）
java -jar google-java-format-1.27.0-all-deps.jar --fix-imports-only MyClass.java

参考：google-java-format README - 命令行使用说明

← 返回工具总览 | 返回目录

Google-Java-Format

相关工具推荐

1. 简介

2. 官方文档

3. 社区优秀实践

3.1 Google Guava

3.2 Android Open Source Project (AOSP)

3.3 Spring Boot（通过 Spotless 集成）

4. 工具配置说明

4.1 配置文件说明

4.2 命令行选项详解

4.3 EditorConfig 基础配置

5. 主流集成方式

5.1 Maven 集成（生态主流，优先）

方式一：通过 Spotless Maven 插件（推荐）

方式二：通过 spotify/fmt-maven-plugin

5.2 IDE 集成

IntelliJ IDEA / Android Studio

VS Code

Eclipse

5.3 命令行使用方式

使用官方 diff 脚本检查变更行

基于 Git 的命令行增量方案

pre-commit 增量方案

GitHub Actions（通过 Spotless Maven）

GitLab CI

GitHub Actions（增量：通过 googlejavaformat-action）

GitHub Actions（增量：通过 Maven + Spotless）

GitLab CI（增量）

5.4 GitHub Action 插件

5.5 Gradle 集成

通过 Spotless Gradle 插件（推荐）

6. 告警抑制（屏蔽）方法

6.1 通过代码注释屏蔽（行级/块级）

6.2 通过 Spotless 的 toggleOffOn 配置屏蔽

6.3 通过集成工具配置排除文件/目录

6.4 通过命令行参数屏蔽

6.2 通过 Spotless 的 `toggleOffOn` 配置屏蔽