Checker Framework添加的注解为何需要在运行时保留？

云上老周

2026-7-30

问题

我通过maven-compiler-plugin使用Checker Framework时发现：生成的字节码中存在源代码里未定义的字段注解，例如org.checkerframework.checker.nullness.qual.NonNull、org.checkerframework.checker.nullness.qual.UnknownKeyFor。这些qual注解的保留策略为@Retention(RetentionPolicy.RUNTIME)。

我一直以为Checker Framework是编译期工具，那为什么这些注解会被写入字节码并在运行时保留？把这类注解留在生产制品里是标准做法吗？这要求我必须把qual包加入运行时类路径，但它明明只用于编译期检查，这么做徒增不必要的成本和风险。要是缺了这个qual jar包，像hibernate-validator这类会反射检查字段注解的库就会抛出NPE，报错如下：

Caused by: java.lang.NullPointerException
at sun.reflect.annotation.TypeAnnotationParser.mapTypeAnnotations(TypeAnnotationParser.java:356)
at sun.reflect.annotation.AnnotatedTypeFactory$AnnotatedTypeBaseImpl.(AnnotatedTypeFactory.java:139)
at sun.reflect.annotation.AnnotatedTypeFactory.buildAnnotatedType(AnnotatedTypeFactory.java:65)
at sun.reflect.annotation.TypeAnnotationParser.buildAnnotatedType(TypeAnnotationParser.java:79)
at java.lang.reflect.Field.getAnnotatedType(Field.java:1177)

解答

注解被写入字节码的原因
Checker Framework虽然主打编译期静态检查，但它生成运行时注解是为了两个核心场景：一是跨模块编译检查时，让工具能读取已编译类的注解信息，保证多模块检查的一致性；二是部分Checker扩展（比如Nullness Checker的运行时断言功能）需要依赖这些注解做运行时约束验证。
是否属于标准做法？
这是Checker Framework的默认行为，属于其设计的一部分——官方认为保留运行时注解能最大化工具的兼容性和扩展能力。但并非所有静态检查工具都采用这种方式，是否保留注解取决于工具的定位和设计目标。
解决运行时依赖问题的方案
如果不需要运行时的注解支持，有两种可靠的解决方式：
1. 禁用运行时注解生成：在maven-compiler-plugin的配置中添加-AuseRuntimeRetention=false参数，让Checker Framework不生成带运行时保留策略的注解。配置示例：
```
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.8.1</version>
  <configuration>
    <annotationProcessors>
      <annotationProcessor>org.checkerframework.checker.nullness.NullnessChecker</annotationProcessor>
    </annotationProcessors>
    <compilerArgs>
      <arg>-AuseRuntimeRetention=false</arg>
    </compilerArgs>
  </configuration>
</plugin>
```
2. 标记为provided依赖：将Checker Framework的qual包设置为provided范围，这样Maven不会将其打包到生产制品中，但要确保编译环境能正常访问该依赖。不过这种方式仍可能遇到反射工具读取注解时的类加载问题，因此更推荐第一种方案。
关于NPE的说明
出现这个空指针异常是因为JVM反射读取字节码中的注解时，找不到对应的注解类（qual包不在类路径）。这是JDK反射机制的固有问题，直接禁用运行时注解生成就能从根源解决这个问题。

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