SpotBugs：从 JVM 字节码缺陷到可审计门禁

高谷深陵大约 6 分钟约 1725 字

SpotBugs 字节码分析与缺陷处置先证明 class 与依赖完整，再让 Bug Pattern、Filter、baseline 和退出码形成可复核证据。高清原图

绿色报告可能意味着没有分析对象

SpotBugs 分析 JVM .class 文件及其依赖关系。它可以从字节码与调用信息中识别空值、并发、资源、可变状态暴露等已知 Bug Pattern，却不负责源码排版。若任务在编译前运行、指向错误 class 目录，或依赖 classpath 无法解析，“零问题”可能只代表分析器没有看完整程序。

本文实验锁定 SpotBugs 4.10.3。Maven 插件、Gradle 插件和分析引擎分别版本化：示例采用 spotbugs-maven-plugin 4.10.3.0 与 Gradle 插件 6.5.10，它们都不能替代引擎版本记录。版本升级前核对 SpotBugs Release、Maven 插件和 Gradle 插件的兼容说明。

证据	正常含义	高风险异常
已编译 class 数量	分析对象与预期模块相符	`No classes found`、目录为空
aux classpath	依赖类型可解析	missing class 或依赖下载失败
Bug Pattern	缺陷类型、类、方法和位置可追踪	只有总数，没有实例身份
analysis error	分析完整性单独计数	被当作普通 warning 后继续绿灯

Maven 先编译，再检查

插件绑定到 verify 前，构建必须生成 class。显式锁定插件和引擎，可以避免插件默认依赖漂移。

<properties>
  <spotbugs.maven.plugin.version>4.10.3.0</spotbugs.maven.plugin.version>
  <spotbugs.version>4.10.3</spotbugs.version>
</properties>

<plugin>
  <groupId>com.github.spotbugs</groupId>
  <artifactId>spotbugs-maven-plugin</artifactId>
  <version>${spotbugs.maven.plugin.version}</version>
  <dependencies>
    <dependency>
      <groupId>com.github.spotbugs</groupId>
      <artifactId>spotbugs</artifactId>
      <version>${spotbugs.version}</version>
    </dependency>
  </dependencies>
  <executions>
    <execution>
      <id>spotbugs-main</id>
      <phase>verify</phase>
      <goals><goal>check</goal></goals>
      <configuration>
        <effort>Max</effort>
        <threshold>Low</threshold>
        <failOnError>true</failOnError>
        <xmlOutput>true</xmlOutput>
        <excludeFilterFile>${maven.multiModuleProjectDirectory}/config/spotbugs/exclude.xml</excludeFilterFile>
        <baselineFile>${maven.multiModuleProjectDirectory}/config/spotbugs/baseline.xml</baselineFile>
      </configuration>
    </execution>
  </executions>
</plugin>

运行 ./mvnw clean verify 时，日志必须出现编译阶段、实际分析的 class 和最终 check。单独调试可用 ./mvnw compile com.github.spotbugs:spotbugs-maven-plugin:check，但正式门禁仍回到项目声明的 execution，避免命令行默认值与 POM 不同。

Gradle 任务依赖必须可见

Gradle 插件注册 spotbugsMain 等任务。项目锁插件版本，并让 check 明确依赖所需任务。

plugins {
    id 'java'
    id 'com.github.spotbugs' version '6.5.10'
}

spotbugs {
    toolVersion = '4.10.3'
    effort = com.github.spotbugs.snom.Effort.MAX
    reportLevel = com.github.spotbugs.snom.Confidence.LOW
    excludeFilter = file("$rootDir/config/spotbugs/exclude.xml")
}

tasks.named('spotbugsMain') {
    reports {
        xml.required = true
        html.required = true
    }
}

执行 ./gradlew classes spotbugsMain --info，核对 class 目录、aux classpath、引擎版本和报告。多项目仓库不能只在根项目应用一个没有 Java source set 的任务；convention plugin 应进入每个目标子项目，根 check 再聚合它们。

用稳定坏样例验证 Bug Pattern

测试样例要触发明确且长期稳定的缺陷模式。例如直接暴露可变数组：

package lab;

public final class MutableConfig {
    private final byte[] secret;

    public MutableConfig(byte[] secret) {
        this.secret = secret;
    }

    public byte[] secret() {
        return secret;
    }
}

编译后运行 SpotBugs，预期出现 EI_EXPOSE_REP 或与构造器赋值对应的可变表示暴露问题，退出码非零，XML 中包含 Bug Pattern、类和方法。将数组在入口与出口复制后重复执行，问题应消失。坏样例未命中时，先查 class 是否存在和 filter 是否误匹配，不能立刻降低阈值或换一个更模糊样例。

SpotBugs 是模式分析器，不是形式化证明。未命中不代表对象一定不可变，也不替代测试、评审、SAST 或运行时观测。门禁只承诺本次 classpath 与规则集合没有发现达到阈值的已知模式。

FindBugsFilter 与 baseline 不是同一种东西

SpotBugs 仍使用 FindBugsFilter 作为过滤文件根元素。Filter 按包、类、方法、字段、Bug Pattern、category 等条件排除一类结果：

<FindBugsFilter>
  <Match>
    <Class name="~com\.example\.generated\..*"/>
    <Bug category="STYLE"/>
  </Match>
</FindBugsFilter>

Filter 的影响会延伸到未来新增代码。baseline 则保存现存 Bug Collection，用实例身份隔离当前债务，让新增实例仍失败。两者不能互换：用宽 Filter 做存量基线会永久吞掉同类新问题；只限制 maxAllowedViolations 也可能让一个新高风险问题替换一个旧低风险问题而总数不变。

baseline 变更要展示新增、消失和指纹漂移。源码局部抑制可用 @SuppressFBWarnings，但必须写 justification，并由规则 owner 复核影响范围。生成代码可以按明确包或注解过滤，不能用 ~.*Generated.* 之类名称猜测覆盖整个仓库。