JSR-305：供检查软件缺陷用的注解

诸如 FindBugs、IntelliJ、Checkstyle 和 PMD 这样的静态分析工具在 Java 开发中得到了广泛应用。这些工具都很强大，但是有一些共同的问题它们都很难解决。在 API 的设计中，有一些决策是不言而喻的，比如何时值可以为 null，或者何时数字值不能为负。完备的 API 会将这些设计细节记录在 JavaDoc 之中，但是分析工具却无法发现类似细节，从而有可能将其忽略或是导致错误的检测结果。

为了解决这些问题，有些静态分析工具开发人员试图使用注解来定义相关细节。比如 FindBugs 和 IntelliJ 都定义了自己的注解，以表示方法何时返回 null。不过，这两个工具使用的注解有细微不同，也因此有了标准化的需求。由 FindBugs 创建人 Bill Pugh 带领制定的 JSR-305 标准，试图创建一套标准注解供分析工具使用，同时希望允许开发人员根据自己的需要添加额外的注解。当前提案中包括供判断是否为空、正负号、开发语言和线程等方面的众多注解。

在为 Google 所做的技术报告中，Bill Pugh 从是否为空的判断开始，简要回顾了一些具体实例。他的想法是：应该允许方法的参数、返回值和用到的字段永远不能为空，而且允许方法接受null 值参数。Pugh 希望使用三个注解来解决这些问题：

@Nonnull——对象被初始化后不能为空。

@NullFeasible——代码应该注意该值可能为空。对于没有检查是否为空的取值操作（dereference），代码分析工具应该标识出来。如果将返回值加上 @NullFeasible 注解，可能其他代码就要做改变，因为这个空返回值可能被作为参数影响到其他代码。

@UnknownNullness——与不加注解效果相同，但对于支持缺省和继承的注解来说是必要的。

标准还可能包含：对正负号判断的注解，它会被用作标识一个数值是否允许使用正负号，比如 @Nonnegative、@Signed、@CheckForNegative、@Positive 和 @CheckForNonpositive；于开发语言的注解允许开发人员标识一个字符串是否属于某种特定的开发语言（SQL、正则表达式等等）；线程注解会标识方法是否必须（或者不应该）被某特定线程（或线程组）调用。在 JSR-305 所属的 Google 讨论组中，Pugh 这样说道：

“在特定情形下，由于操作需要，某些方法只能被特定线程调用，或者永远不能被某线程调用。最明显的例子就是 Java GUI 开发中的 AWT/Swing 线程问题。特定的 AWT/Swing 操作要求只能在事件线程中进行，否则就会导致各种微妙问题，而在事件线程中要用很长时间才能完成的操作，会让用户觉得应用程序反应迟钝（这也是为什么 swing 总被人认为性能太差的原因）。为解决类似问题，我提议使用 @ThreadRestrictions 注解，可以用它来说明总能调用 / 或永远不能调用本操作的线程和 / 或线程组。 为开发人员方便计，由于 Swing/AWT 问题会影响到所有的 Java 桌面应用开发，我建议使用 @EventThreadOnly 和 @NeverEventThread 注解。”

除定义了一些基础注解之外，JSR-305 还试图提供元注解（meta annotation），供类型限定符使用，以允许开发人员为 Java 的类型系统定义自己的属性。Java 5 预览版发布时没有提供枚举类型，很多 Java API 都被迫使用整形和字符串作为公共常量，如果有枚举的话，那设计起来就方便多了。这也是促使提供元注解的主要原因。一个类似于 JDBC createStatement 这样的方法，使用三个整数参数（resultSetType, resultSetConcurrency 和 resultSetHoldability），会暴露一系列公共静态整数常量供程序员使用，比如 TYPE_FORWARD_ONLY、CONCUR_READ_ONLY、HOLD_CURSOR_OVER_COMMIT 等等。编译器无法知道在调用方法时参数传递顺序是否正确，因为它们只是三个整数而已。通过给类型限定符添加元注解，这个 JSR 提供了让开发人员可以添加必要的类型限定符的机制。前面返回非空值的例子可以被描述成：

<pre id="rg:59">@Documented<br id="rg:510"></br>@TypeQualifier<br id="rg:511"></br>@Retention(RetentionPolicy.RUNTIME)<br id="rg:512"></br>public @interface Nonnull{<br id="rg:513"></br> When when() default When.ALWAYS;<br id="rg:514"></br> ElementType[] defaultFor() default{};<br id="rg:515"></br>}<br id="rg:516"></br>其中，@Documented 标识它是否进入 JavaDoc，@TypeQualifier 告诉我们这是一个类型限定符，@Retention 告诉我们它是否可以通过反射使用。而 When 参数可用作提供位置特定信息。

预期这个 JSR 会作为 Java 7 的一部分推出，不过它不需要开发语言上的变更；而且专家组正在试图支持 Java 5 和以上版本。Sun、Google、JetBrains 和 Doug Lea 都是专家组的成员。

查看英文原文： JSR-305: Annotations for Software Defect Detection