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

作者 Charles Humble 译者 郑柯 发布于 2008年7月7日 上午12时56分

社区

Java

主题

工件和工具

标签

注释

诸如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提供了让开发人员可以添加必要的类型限定符的机制。前面返回非空值的例子可以被描述成：

@Documented
@TypeQualifier
@Retention(RetentionPolicy.RUNTIME)
public @interface Nonnull{
	When when() default When.ALWAYS;
	ElementType[] defaultFor() default{};
}

其中，@Documented标识它是否进入JavaDoc，@TypeQualifier告诉我们这是一个类型限定符，@Retention告诉我们它是否可以通过反射使用。而When参数可用作提供位置特定信息。

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

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

• 更早的 >