阅读977 返回首页    go 阿里云 go 技术社区[云栖]

Java 注解指导手册 – 终极向导

编者的话：注解是java的一个主要特性且每个java开发者都应该知道如何使用它。

我们已经在Java Code Geeks提供了丰富的教程, 如Creating Your Own Java Annotations, Java Annotations Tutorial with Custom Annotation 和 Java Annotations: Explored & Explained.

我们也有些文章是关于注解在不同类库中的应用，包括 Make your Spring Security @Secured annotations more DRY和 Java Annotations & A Real World Spring Example.

现在，是时候汇总这些和注解相关的信息到一篇文章了，祝大家阅读愉快。

目录

  1. 什么是注解
  2. 介绍
  3. 消费器
  4. 注解语法和注解元素
  5. 在什么地方使用
  6. 使用案例
  7. 内建注解
  8. Java 8 与注解
  9. 自定义注解
  10. 提取注解
  11. 注解集成
  12. 使用注解的知名类库
  13. 小结
  14. 下载
  15. 资料

 

在这篇文章中我们将阐述什么是Java注解，它们如何工作，怎么使用它们。

我们将揭开Java注解的面纱，包括内建注解或称元注解，还将讨论Java8中与之相关的的新特性。

最后，我们将实现自定义的注解，编写一个使用注解的处理程序（消费器），它通过java反射使用注解。

我们还会列出一些基于注解，知名且被广泛应用的第三方类库如：Junit，JAXB，Spring，Hibernate。

在文章的最后，会有一个压缩文件包含了文章中的所有示例，实现这些例子使用的软件版本如下所示：

  • Eclipse Luna 4.4
  • JRE Update 8.20
  • Junit 4
  • Hibernate 4.3.6
  • FindBugs 3.0.0

1.什么是注解？

注解早在J2SE1.5就被引入到Java中，主要提供一种机制，这种机制允许程序员在编写代码的同时可以直接编写元数据。

在引入注解之前，程序员们描述其代码的形式尚未标准化，每个人的做法各异：transient关键字、注释、接口等。这显然不是一种优雅的方式，随之而来的一种崭新的记录元数据的形式——注解被引入到Java中。

其它因素也促成了这个决定：当时不同类型的应用程序使用XML作为标准的代码配置机制，这其实并不是最佳方式，因为代码和XML的解耦以及未来对这种解耦应用的维护并不低廉。另外，由于非保留字的使用，例如“@deprecated”自从Java1.4便开始在Java文档中使用。我非常确定这是一个现在在注解中使用“@”原因。

包含注解的设计和开发的Java规范主要有以下两篇：

2. 介绍

解释何为注解的最佳方式就是元数据这个词：描述数据自身的数据。注解就是代码的元数据，他们包含了代码自身的信息。

注解可以被用在包，类，方法，变量，参数上。自Java8起，有一种注解几乎可以被放在代码的任何位置，叫做类型注解。我们将会在后面谈到具体用法。

被注解的代码并不会直接被注解影响。这只会向第三系统提供关于自己的信息以用于不同的需求。

注解会被编译至class文件中，而且会在运行时被处理程序提取出来用于业务逻辑。当然，创建在运行时不可用的注解也是可能的，甚至可以创建只在源文件中可用，在编译时不可用的注解。

3.消费器

理解注解的目的以及如何使用它都会带来困难，因为注解本身并不包含任何功能逻辑，它们也不会影响自己注解的代码，那么，它们到底为什么而存在呢？

这个问题的解释就是我所称的注解消费器。它们是利用被注解代码并根据注解信息产生不同行为的系统或者应用程序。

例如，在Java自带的内建注解（元注解）中，消费器是执行被注解代码的JVM。还有其他稍后谈到的其他例子，例如JUnit，消费器是读取，分析被注解代码的JUnit处理程序，它还可以决定测试单元和方法执行顺序。我们会在JUnit章节更深入。

消费器使用Java中的反射机制来读取和分析被注解的源代码。使用的主要的包有：java.lang, java.lang.reflect。我们将会在本篇指南中介绍如何用反射从头开始创建一个自定义的消费器。

4. 注解语法和元素

声明一个注解需要使用“@”作为前缀，这便向编译器说明，该元素为注解。例如：

1 @Annotation
2 public void annotatedMehod() {
3 ...
4  }

上述的注解名称为Annotation，它正在注解annotatedMethod方法。编译器会处理它。注解可以以键值对的形式持有有很多元素，即注解的属性。

1 @Annotation(
2  info = "I am an annotation",
3  counter = "55"
4 )
5 public void annotatedMehod() {
6 ...
7  }

如果注解只包含一个元素（或者只需要指定一个元素的值，其它则使用默认值），可以像这样声明：

1 @Annotation("I am an annotation")
2 public void annotatedMehod() {
3 ...
4  }

就像我们看到的一样，如果没有元素需要被指定，则不需要括号。多个注解可以使用在同一代码上，例如类：

1 @ Annotation (info = "U a u O")
2 @ Annotation2
3 class AnnotatedClass { ... }

一些java本身提供的开箱即用的注解，我们称之为内建注解。也可以定义你自己的注解，称之为子定义注解。我们会在下一章讨论。

5. 在什么地方使用

注解基本上可以在Java程序的每一个元素上使用：类，域，方法，包，变量，等等。

自Java8，诞生了通过类型注解的理念。在此之前，注解是限于在前面讨论的元素的声明上使用。从此，无论是类型还是声明都可以使用注解，就像：

1 @MyAnnotation String str = "danibuiza";

我们将会在Java8关联章节看到这种机制的更多细节。

6. 使用案例

注解可以满足许多要求，最普遍的是：

  • 向编译器提供信息：注解可以被编译器用来根据不同的规则产生警告，甚至错误。一个例子是Java8中@FunctionalInterface注解，这个注解使得编译器校验被注解的类，检查它是否是一个正确的函数式接口。
  • 文档：注解可以被软件应用程序计算代码的质量例如：FindBugs，PMD或者自动生成报告，例如：用来Jenkins, Jira，Teamcity。
  • 代码生成：注解可以使用代码中展现的元数据信息来自动生成代码或者XML文件，一个不错的例子是JAXB。
  • 运行时处理：在运行时检查的注解可以用做不同的目的，像单元测试（JUnit），依赖注入（Spring），校验，日志（Log4j），数据访问（Hibernate）等等。

在这篇手册中我们将展现几种注解可能的用法，包括流行的Java类库是如何使用它们的。

7. 内建注解

Java语言自带了一系列的注解。在本章中我们将阐述最重要的一部分。这个清单只涉及了Java语言最核心的包，未包含标准JRE中所有包和库如JAXB或Servlet规范。

以下讨论到的注解中有一些被称之为Meta注解，它们的目的注解其他注解，并且包含关于其它注解的信息。

  • @Retention：这个注解注在其他注解上，并用来说明如何存储已被标记的注解。这是一种元注解，用来标记注解并提供注解的信息。可能的值是：
    • SOURCE：表明这个注解会被编译器忽略，并只会保留在源代码中。
    • CLASS:表明这个注解会通过编译驻留在CLASS文件，但会被JVM在运行时忽略,正因为如此,其在运行时不可见。
    • RUNTIME：表示这个注解会被JVM获取，并在运行时通过反射获取。

我们会在稍后展开几个例子。

  • @Target：这个注解用于限制某个元素可以被注解的类型。例如：
    • ANNOTATION_TYPE 表示该注解可以应用到其他注解上
    • CONSTRUCTOR 表示可以使用到构造器上
    • FIELD 表示可以使用到域或属性上
    • LOCAL_VARIABLE表示可以使用到局部变量上。
    • METHOD可以使用到方法级别的注解上。
    • PACKAGE可以使用到包声明上。
    • PARAMETER可以使用到方法的参数上
    • TYPE可以使用到一个类的任何元素上。
  • @Documented：被注解的元素将会作为Javadoc产生的文档中的内容。注解都默认不会成为成为文档中的内容。这个注解可以对其它注解使用。
  • @Inherited：在默认情况下，注解不会被子类继承。被此注解标记的注解会被所有子类继承。这个注解可以对类使用。
  • @Deprecated：说明被标记的元素不应该再度使用。这个注解会让编译器产生警告消息。可以使用到方法，类和域上。相应的解释和原因，包括另一个可取代的方法应该同时和这个注解使用。
  • @SuppressWarnings：说明编译器不会针对指定的一个或多个原因产生警告。例如：如果我们不想因为存在尚未使用的私有方法而得到警告可以这样做：
1 @SuppressWarnings( "unused")
2 private String myNotUsedMethod(){
3  ...
4 }

通常,编译器会因为没调用该方而产生警告; 用了注解抑制了这种行为。该注解需要一个或多个参数来指定抑制的警告类型。

  • @Override：向编译器说明被注解元素是重写的父类的一个元素。在重写父类元素的时候此注解并非强制性的，不过可以在重写错误时帮助编译器产生错误以提醒我们。比如子类方法的参数和父类不匹配，或返回值类型不同。
  • @SafeVarargs：断言方法或者构造器的代码不会对参数进行不安全的操作。在Java的后续版本中，使用这个注解时将会令编译器产生一个错误在编译期间防止潜在的不安全操作。

更多信息请参考：https://docs.oracle.com/javase/7/docs/api/java/lang/SafeVarargs.html

8. Java 8 与注解

Java8带来了一些优势，同样注解框架的能力也得到了提升。在本章我们将会阐述，并就java8带来的3个注解做专题说明和举例：

@Repeatable注解，关于类型注解的声明，函数式接口注解@FunctionalInterface（与Lambdas结合使用）。

  • @Repeatable：说明该注解标识的注解可以多次使用到同一个元素的声明上。

看一个使用的例子。首先我们创造一个能容纳重复的注解的容器：

1 /**
2  * Container for the {@link CanBeRepeated} Annotation containing a list of values
3 */
4 @Retention( RetentionPolicy.RUNTIME )
5 @Target( ElementType.TYPE_USE )
6 public @interface RepeatedValues
7 {
8  CanBeRepeated[] value();
9 }

接着，创建注解本身，然后标记@Repeatable

1 @Retention( RetentionPolicy.RUNTIME )
2 @Target( ElementType.TYPE_USE )
3 @Repeatable( RepeatedValues.class )
4 public @interface CanBeRepeated
5 {
6  
7  String value();
8 }

最后，我们可以这样重复地使用：

1 @CanBeRepeated( "the color is green" )
2 @CanBeRepeated( "the color is red" )
3 @CanBeRepeated( "the color is blue" )
4 public class RepeatableAnnotated
5 {
6  
7 }

如果我们尝试去掉@Repeatable

01 @Retention( RetentionPolicy.RUNTIME )
02 @Target( ElementType.TYPE_USE )
03 public @interface CannotBeRepeated
04 {
05  
06  String value();
07 }
08  
09 @CannotBeRepeated( "info" )
10 /*
11  * if we try repeat the annotation we will get an error: Duplicate annotation of non-repeatable type
12  *
13  * @CannotBeRepeated. Only annotation types marked
14  *
15  * @Repeatable can be used multiple times at one target.
16  */
17 // @CannotBeRepeated( "more info" )
18 public class RepeatableAnnotatedWrong
19 {
20  
21 }

我们会得到编译器的错误信息：

1 Duplicate annotation of non-repeatable type
  • 自Java8开始，我们可以在类型上使用注解。由于我们在任何地方都可以使用类型，包括 new操作符，casting，implements，throw等等。注解可以改善对Java代码的分析并且保证更加健壮的类型检查。这个例子说明了这一点：
01 @SuppressWarnings( "unused" )
02 public static void main( String[] args )
03 {
04  // type def
05  @TypeAnnotated
06  String cannotBeEmpty = null;
07  
08  // type
09  List<@TypeAnnotated String> myList = new ArrayList<String>();
10  
11  // values
12  String myString = new @TypeAnnotated String( "this is annotated in java 8" );
13  
14 }
15  
16 // in method params
17 public void methodAnnotated( @TypeAnnotated int parameter )
18 {
19  System.out.println( "do nothing" );
20 }

所有的这些在Java8之前都是不可能的。

  • @FunctionalInterface：这个注解表示一个函数式接口元素。函数式接口是一种只有一个抽象方法（非默认）的接口。编译器会检查被注解元素，如果不符，就会产生错误。例子如下：
01 // implementing its methods
02 @SuppressWarnings( "unused" )
03 MyCustomInterface myFuncInterface = new MyCustomInterface()
04 {
05  
06  @Override
07  public int doSomething( int param )
08  {
09  return param * 10;
10  }
11 };
12  
13 // using lambdas
14 @SuppressWarnings( "unused" )
15  MyCustomInterface myFuncInterfaceLambdas = ( x ) -> ( x * 10 );
16 }
17  
18 @FunctionalInterface
19 interface MyCustomInterface
20 {
21 /*
22  * more abstract methods will cause the interface not to be a valid functional interface and
23  * the compiler will thrown an error:Invalid '@FunctionalInterface' annotation;
24  * FunctionalInterfaceAnnotation.MyCustomInterface is not a functional interface
25  */
26  // boolean isFunctionalInterface();
27  
28  int doSomething( int param );
29 }

这个注解可以被使用到类，接口，枚举和注解本身。它的被JVM保留并在runtime可见，这个是它的声明：

1 @Documented
2  @Retention(value=RUNTIME)
3  @Target(value=TYPE)
4 public @interface FunctionalInterface

9. 自定义注解

正如我们之前多次提及的，可以定义和实现自定义注解。本章我们即将探讨。
首先，定义一个注解：

1 public @interface CustomAnnotationClass

这样创建了一个新的注解类型名为 CustomAnnotationClass。关键字：@interface说明这是一个自定义注解的定义。

之后，你需要为此注解定义一对强制性的属性，保留策略和目标。还有一些其他属性可以定义，不过这两个是最基本和重要的。它们在第8章，描述注解的注解时讨论过，它们同样也是Java内建的注解。

所以，我们为自定义的注解设置属性：

1 @Retention( RetentionPolicy.RUNTIME )
2 @Target( ElementType.TYPE )
3 public @interface CustomAnnotationClass implements CustomAnnotationMethod

在保留策略中 RUNTIME 告诉编译器这个注解应该被被JVM保留，并且能通过反射在运行时分析。通过 TYPE 我们又设置该注解可以被使用到任何类的元素上。

之后，我们定义两个注解的成员：

01 @Retention( RetentionPolicy.RUNTIME )
02 @Target( ElementType.TYPE )
03 public @interface CustomAnnotationClass
04 {
05  
06  public String author() default "danibuiza";
07  
08  public String date();
09  
10 }

以上我们仅定义了默认值为“danibuiza”的 author 属性和没有默认值的date属性。我们应强调所有的方法声明都不能有参数和throw子句。这个返回值的类型被限制为之前提过的字符串，类，枚举，注解和存储这些类型的数组。

现在我们可以像这样使用刚创建的自定义注解：

1 @CustomAnnotationClass( date = "2014-05-05" )
2 public class AnnotatedClass
3 {
4 ...
5 }

在另一种类似的用法中我们可以创建一种注解方法的注解，使用Target METHOD：

01 @Retention( RetentionPolicy.RUNTIME )
02 @Target( ElementType.METHOD )
03 public @interface CustomAnnotationMethod
04 {
05  
06  public String author() default "danibuiza";
07  
08  public String date();
09  
10  public String description();
11  
12 }

这种注解可以使用在方法声明上：

01 @CustomAnnotationMethod( date = "2014-06-05", description = "annotated method" )
02 public String annotatedMethod()
03  {
04  return "nothing niente";
05 }
06  
07 @CustomAnnotationMethod( author = "friend of mine", date = "2014-06-05", description = "annotated method" )
08 public String annotatedMethodFromAFriend()
09 {
10  return "nothing niente";
11 }

有很多其它属性可以用在自定义注解上，但是 目标 （Target）和 保留策略（Retention Policy）是最重要的两个。

10. 获取注解

Java反射API包含了许多方法来在运行时从类，方法或者其它元素获取注解。接口AnnotatedElement包含了大部分重要的方法，如下：

  • getAnnotations(): 返回该元素的所有注解，包括没有显式定义该元素上的注解。
  • isAnnotationPresent(annotation): 检查传入的注解是否存在于当前元素。
  • getAnnotation(class): 按照传入的参数获取指定类型的注解。返回null说明当前元素不带有此注解。

class 通过java.lang.Class被实现，java.lang.reflect.Method 和 java.lang.reflect.Field，所以可以基本上被和任何Java元素使用。

现在，我们将看一个怎么读取注解的例子：
我们写一个程序，从一个类和它的方法中读取所有的存在的注解：

01 public static void main( String[] args ) throws Exception
02 {
03  
04  Class<AnnotatedClass> object = AnnotatedClass.class;
05  // Retrieve all annotations from the class
06  Annotation[] annotations = object.getAnnotations();
07  for( Annotation annotation : annotations )
08  {
09  System.out.println( annotation );
10  }
11  
12  // Checks if an annotation is present
13  if( object.isAnnotationPresent( CustomAnnotationClass.class ) )
14  {
15  
16  // Gets the desired annotation
17  Annotation annotation = object.getAnnotation( CustomAnnotationClass.class );
18  
19  System.out.println( annotation );
20  
21  }
22  // the same for all methods of the class
23  for( Method method : object.getDeclaredMethods() )
24  {
25  
26  if( method.isAnnotationPresent( CustomAnnotationMethod.class ) )
27  {
28  
29  Annotation annotation = method.getAnnotation( CustomAnnotationMethod.class );
30  
31  System.out.println( annotation );
32  
33  }
34  
35  }
36 }

输出如下：

1 @com.danibuiza.javacodegeeks.customannotations.CustomAnnotationClass(getInfo=Info, author=danibuiza, date=2014-05-05)
2  
3 @com.danibuiza.javacodegeeks.customannotations.CustomAnnotationClass(getInfo=Info, author=danibuiza, date=2014-05-05)
4  
5 @com.danibuiza.javacodegeeks.customannotations.CustomAnnotationMethod(author=friend of mine, date=2014-06-05, description=annotated method)
6 @com.danibuiza.javacodegeeks.customannotations.CustomAnnotationMethod(author=danibuiza, date=2014-06-05, description=annotated method)

在这个程序中，我们可以看到 getAnnotations()方法来获取所有某个对象（方法，类）上的所有注解的用法。展示了怎样使用isAnnotationPresent()方法和getAnnotation()方法检查是否存在特定的注解，和如何获取它。

11. 注解中的继承

注解在Java中可以使用继承。这种继承和普通的面向对象继承几乎没有共同点。

如果一个注解在Java中被标识成继承，使用了保留注解@Inherited，说明它注解的这个类将自动地把这个注解传递到所有子类中而不用在子类中声明。通常，一个类继承了父类，并不继承父类的注解。这完全和使用注解的目的一致的：提供关于被注解的代码的信息而不修改它们的行为。

我们通过一个例子更清楚地说明。首先，我们定义一个自动继承的自定义注解。

1 @Inherited
2 @Retention(RetentionPolicy.RUNTIME)
3 @Target(ElementType.TYPE)
4 public @interface InheritedAnnotation
5 {
6  
7 }

有一个父类名为：AnnotatedSuperClass，已经被自定义的注解给注解上了：

01 @InheritedAnnotation
02 public class AnnotatedSuperClass
03 {
04  
05  public void oneMethod()
06  {
07  
08  }
09  
10 }

一个子类继承父类：

01 @InheritedAnnotation
02 public class AnnotatedSuperClass
03 {
04  
05  public void oneMethod()
06  {
07  
08  }
09  
10 }

子类 AnnotatedSubClass 展示了自动继承的注解 @InheritedAnnotation。我们看到下面的代码通过 isAnnotationPresent() 方法测试出了当前注解。

1 <pre>System.out.println( "is true: " + AnnotatedSuperClass.class.isAnnotationPresent( InheritedAnnotation.class ) );
2  
3 System.out.println( "is true: " + AnnotatedSubClass.class.isAnnotationPresent( InheritedAnnotation.class ) );</pre>
4 <pre>

输出如下：

1 is true: true
2 is true: true

我们可以看到子类虽然并没有声明注解，但还是被自动地注解上了。

如果我们尝试注解在一个接口中：

1 @InheritedAnnotation
2 public interface AnnotatedInterface
3 {
4  
5  public void oneMethod();
6  
7 }

一个实现了该接口的类：

01 public class AnnotatedImplementedClass implements AnnotatedInterface
02 {
03  
04  @Override
05  public void oneMethod()
06  {
07  
08  }
09  
10 }

经过 isAnnotationPresent() 方法测试：

1 System.out.println( "is true: " + AnnotatedInterface.class.isAnnotationPresent( InheritedAnnotation.class ) );
2  
3 System.out.println( "is true: " + AnnotatedImplementedClass.class.isAnnotationPresent( InheritedAnnotation.class ) );

结果如下：

1 is true: true
2 is true: false

这个结果说明继承注解和接口在一起使用时，接口中的注解在实现类中：仅仅被忽略。实现类并不继承接口的注解；接口继承仅仅适用于类继承。正如 AnnotatedSubClass。
@Inheriated注解仅在存在继承关系的类上产生效果，在接口和实现类上并不工作。这条同样也适用在方法，变量，包等等。只有类才和这个注解连用。

一条关于@Inheriated注解的很好的解释在Javadoc中：https://docs.oracle.com/javase/7/docs/api/java/lang/annotation/Inherited.html.

注解不能继承注解，如果你尝试这么做了，就会得到编译器抛出的错误：

1 Annotation type declaration cannot have explicit superinterfaces

12. 使用注解的知名类库

在这一章我们将展示知名类库是如何利用注解的。一些类库如：JAXB, Spring Framework, Findbugs, Log4j, Hibernate, Junit。它们使用注解来完成代码质量分析，单元测试，XML解析，依赖注入和许多其它的工作。

在这篇手册中我们将讨论以下类库的部分内容：

12.1. Junit

这个框架用于完成Java中的单元测试。自JUnit4开始，注解被广泛应用，成为Junit的设计的主干之一。

基本上，JUnit处理程序通过反射读取类和测试套件，按照在方法上，类上的注解顺序地执行它们。当然还有一些用来修改测试执行的注解。其它注解都用来执行测试，阻止执行，改变执行顺序等等。

用到的注解相当多，但是我们将会看到最重要的几个：