Java 语言特性之 Annotation 注解

利用 Java 的反射机制，可以在运行时获取 Java 类的注解信息。

注解

注解的特性

注解是 Java 5 的一个新特性，是插入代码中的一种注释或者说是元数据。注解并不是程序代码，可以对程序作出解释，类似于注释。但是注解可以被相关程序读取（例如编译器）。

注解可以用在两个时刻：

• 在编译期间，编译工具会对注解进行处理
• 在运行期间，使用 Java 反射机制进行处理

注解格式及用法

注解的格式：注解以 @ 开头，后面跟注释名，还可以加参数。

注解使用的地方：package，class，method，field 上都可以使用注解。

• 类注解：

@MyAnnotation(name="someName",  value = "Hello World")
public class TheClass {
}

• 方法注解：

@Override
public String toString() { // 这里如果方法名写错，会报错
	return "";
}

注解的定义

注解的定义与接口的定义相似，但是需要在 interface 关键字前加 @ 符号：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
public @interface Deprecated {
}

元注解 meta-annotation

元注解负责注解其他注解。Java 定义了4个标准的元注解类型，用来对其它 注解类型作说明：

@Target

@Target 用于描述注解的使用位置。例如 @Target(ElementType.TYPE) 表示这个注解只能用在类型上面（比如类跟接口）。参数可以同时指定多个值，例如@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})。ElementType 的可用值有：

• CONSTRUCTOR：用于构造器
• FIELD：用于字段
• LOCAL_VARIABLE：用于局部变量
• METHOD：用于方法
• PACKAGE：用于包
• PARAMETER：用于参数
• TYPE：用于类、接口(包括注解类型) 或enum声明

@Retention

@Retention 用于描述注解的生命周期。可取值有：

• SOURCE：在源文件中有效，编译时丢弃
• CLASS：在class文件中有效，运行时丢弃
• RUNTIME：在运行时有效

@Documented

@Documented 用于描述是否可以被 javadoc 之类的工具文档化。@Documented 是标记注解，没有成员。

@Inherited

@Inherited 用于描述某个被标注的类型是被继承的。如果一个使用了 @Inherited 修饰的annotation类型被用于一个class，则这个注解将被用于该class的子类。

当@Inherited 类型标注的注解的Retention是RetentionPolicy.RUNTIME，则反射API增强了这种继承性。如果我们使用 java.lang.reflect 反射机制去查询一个@Inherited 类型的注解时，反射代码检查将展开工作：检查class和其父类，直到发现指定的annotation类型被发现，或者到达类继承结构的顶层。

内置注解

@Override

定义在 java.lang.Override 中，此注解只能用于修饰方法，表示重写父类中的方法。

@Deprecated

定义在 java.lang.Deprecated 中，可以用于修饰方法、属性或类，表示方法、属性或类已经废弃，不建议使用。

@SuppressWarnings

定义在 java.lang.SuppressWarnings 中，抑制编译时的警告信息。可以指定以下的一个或多个参数，例如 `@SuppressWarngins(value={“unchecked”, “path”})：

• all：抑制所有警告
• deprecate：抑制废弃方式、属性或类的警告
• unchecked：抑制未检查的警告，例如使用集合时未指定泛型
• path：路径、文件不存在的警告
• finally：抑制 finally 子句不能完成时的警告

自定义注解

使用 @interface 自定义注解时，自动继承 java.lang.annotation.Annotation 接口。注解不能继承其他的注解或接口。

@interface 用来声明一个注解，其中的每一个方法实际上是声明了一个配置参数。方法的名称就是参数的名称，返回值类型就是参数的类型（返回值类型只能是基本数据类型（int,float,boolean,byte,double,char,long,short)、Class、String、enum 及这些类型对应的数组）。可以通过default来声明参数的默认值。

定义注解的语法：

public @interface 注解名 {定义体}

• 例如，注解使用：

@MyAnnotation(name="someName",  value = "Hello World")
public class TheClass {
}

• 注解定义：

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)

public @interface MyAnnotation {
  public String name();
  public String value();
}

访问注解

只要是 Runtime 级别的注解，不管是类、方法、参数、变量注解都可以在运行时通过反射机制加载类后，进行访问，具体方法可以参考 这里。

Class aClass = TheClass.class;
Annotation annotation = aClass.getAnnotation(MyAnnotation.class);

if(annotation instanceof MyAnnotation){
    MyAnnotation myAnnotation = (MyAnnotation) annotation;
    System.out.println("name: " + myAnnotation.name());
    System.out.println("value: " + myAnnotation.value());
}