Java 之路 (十九) -- 注解（语法、预定义注解、元注解、

2018-08-23 本文已影响59人 whd_Alive

前言

官方注解的定义如下：

注解（一种元数据形式）提供有关不属于程序本身的程序的数据。注解对它们注解的代码的操作没有直接影响。

注解有许多用途，其中包括：

编译器的信息 - 编译器可以使用注解来检测错误或抑制警告。

编译时和部署时处理 - 软件工具可以处理注解信息以生成代码，XML文件等。

运行时处理 - 可以在运行时检查某些注解。

第一次看时候觉得"这尼玛是什么"，于是换个简单一点的说法。

我们可以把注解当作是“标签”，就像是我们对某个人的看法一样，这个“标签”包含了对其中属性的评价（注解元素）。我们就可以对某个程序元素贴上这种"标签"（使用注解），既然能贴上去，那么我们自然也能通过某种方式（反射）来将这个"标签"撕下去（获取注解）。

有了这种比喻，相信下面对于注解的讲解就能更更容易理解了。一旦觉得理解不了注解是个什么东西，就回想“注解 ≈ 标签”就好了。

1. 基础知识

1.1 注解的格式

注解中无元素：

@Entity

//如下，用于重写的 @Override 注解
@Override
void myMethod(){...}

注解中有多个元素，且这些元素有值：

//这里的 @Author 是假定的自定义注解
@Author(
   name = "Benjamin Franklin",
   date = "3/27/2003"
)
class MyClass() { ... }

注解中只有一个元素时：

//@SuppressWarnings 该注解是 Java 预定义的注解

@SuppressWarnings(value = "unchecked")
void myMethod() { ... }

//或者 可以将 value 省略
@SuppressWarnings("unchecked")
void myMethod() { ... }

可以在同一声明中添加多个注解：

@Author(name = "Jane Doe")
@EBook
class MyClass { ... }

可以使用重复注解（使用相同类型的注解）

@Author(name = "Jane Doe")
@Author(name = "John Smith")
class MyClass { ... }

1.2 可以使用注解的位置

注解可以应用于声明以下内容：

类
字段
方法
其他程序元素

在 Java SE 8 以前，注解只能应用于声明。从 Java SE 8开始，添加了类型注解，具体示例如下：

创建类实例
```
new @Interned MyObject();
```
类型转换
```
myString = (@NonNull String) str;
```

implements 子句

class UnmodifiableList<T> implements @Readonly List<@Readonly T> { ... }

异常抛出语句

void monitorTemperature() throws @Critical TemperatureException { ... }

2. 声明注解类型

注解类型定义类似于接口定义，通过使用 @interface 关键字进行定义。

@interface MyAnnotation{
    
}

前面我们提到过，注解中可以有元素，注解元素是通过以下方式定义的：

@interface MyAnnotation{
    int id() default 0;
    String msg();
    //...
}

这样定义好之后，我们就可以使用该类型的注解，并填入值，如下例子：

@MyAnnotation(id = 3, msg = "hello annotation")
public class Test {
    //...
}

在定义 @MyAnnotation 注解时，我使用了一个关键字 default，它是用来指定默认值的。当指定默认值之后，在我们使用注解并不填入值时，Java 会自动将其设为默认值。于是我们就可以如下调用：

@MyAnnotation(msg = "hello annotation")
public class Test {
    //...
}

这里需要注意注解元素的类型是有限制的，注解元素只能使用如下类型：

基本数据类型
String
Class
enum
Annotation
以上类型的数组

3. 预定义注解

3.1 Java 使用的预定义注解

Java 使用的注解类型有如下几种：

@Deprecated

表示被注解的元素已弃用，不应再使用，只要程序使用带有 @Deprecated 注解的方法/类/字段，编译器就会生成警告。当不推荐使用时，也应使用 Javadoc @deprecated 对其标记。
```
   // Javadoc comment follows
    /**
     * @deprecated
     * explanation of why it was deprecated
     */
    @Deprecated
    static void deprecatedMethod() { }
```
@Override

该注解通知编译器被注解的元素要覆盖超类中声明的元素，具体实际上就是重写方法时使用。
```
   // 将方法标记为已将超类方法覆盖
   @Override 
   int overriddenMethod() { }
```
需要强调一点：实际上，重写方法时 @Override 并非必须的，之所以使用该注解是为了防止出错。

当使用 @Override 注解的方法并没有正确覆盖其超类方法时，编译器会报错。
@SuppressWarnings

该注解告知编译器禁止可能生成的特定警告。举个例子，下面的示例中，使用了启用的方法，通常编译器会生成警告，但是使用 @SuppressWarnings 注解后，会导致该警告被禁止生成。
```
@SuppressWarnings("deprecation")
    void useDeprecatedMethod() {
        // deprecation warning
        // - suppressed
        objectOne.deprecatedMethod();
    }
```
关于编译器警告，Java 语言规范指定了两个类别：deprecation和unchecked

deprecation：使用了弃用方法时的类别

unchecked：当与泛型出现之前编写的遗留代码进行交互时，可能出现的警告类别。
@SafeVarargs

当该注解应用于方法或构造函数时，它保证了不会对可变参数执行不安全的操作。当使用该注解后，有关可变参数的 unchecked 警告将被禁止生成。
@FunctionalInterface

在Java SE 8中引入的，指出类型声明的目的是作为一个函数式接口注解。

3.2 元注解

适用于其他注解的注解称为元注解 。

@Retention

指定注解的存储方式：
1. RetentionPolicy.SOURCE - 标记的注解仅保留在源级别中，并被编译器忽略。
2. RetentionPolicy.CLASS - 标记的注解在编译时由编译器保留，但Java虚拟机（JVM）会忽略。
3. RetentionPolicy.RUNTIME - 标记的注解由JVM保留，因此运行时环境可以使用它。
@Documented

作用是能够将注解中的元素包含到 Javadoc 中去
@Target

限制可以应用注解的 Java 元素类型：
- ElementType.ANNOTATION_TYPE可以应用于注解类型。
- ElementType.CONSTRUCTOR可以应用于构造函数。
- ElementType.FIELD可以应用于字段或属性。
- ElementType.LOCAL_VARIABLE可以应用于局部变量。
- ElementType.METHOD可以应用于方法级注释。
- ElementType.PACKAGE可以应用于包声明。
- ElementType.PARAMETER可以应用于方法的参数。
- ElementType.TYPE可以应用于类的任何元素。
@Inherited

表明注解类型可以从超类继承。当超类使用了被" @Inherited 注解了的" 注解后，如果它的子类没有添加任何注解，那么子类会继承超类的注解。

比较绕，举个例子：
```
@Inherited
@interface Test {}


@Test
public class A {}


public class B extends A {}
```
上面，@Test 注解是可以被继承的，A 使用了 @Test 注解，B 继承 A，且未添加任何注解，于是 B 也就拥有 @Test 这个注解。
@Repeatable

Java SE 8 加入的特性，表明被注解的注解可以多次应用于相同的声明。

具体参见 重复注解 小节。

4. 重复注解

Java SE 8 中，加入了重复注解，这使得我们可以将相同的注解应用于声明或类型引用。

它的声明包含两个步骤：

声明可重复的注解类型
声明包含的注解类型

下面通过一个例子来介绍具体如何声明和使用重复注解：

第1步：声明可重复的注解类型

注解类型必须使用 @Repeatable 元注解进行标记：

@Repeatable(Schedules.class)
public @interface Schedule {
  String dayOfMonth() default "first";
  String dayOfWeek() default "Mon";
  int hour() default 12;
}

其中， @Repeatable 元注解的值是Java编译器为存储重复注解而生成的容器注解的类型。此例中，包含的注解类型是 Schedules，因此 @Schedule 注解存储在 @Schedules 注解中。

第2步：声明包含的注解类型

包含的注解类型必须带有数组类型的 value 元素，数组的类型必须是可重复的注解类型：

public @interface Schedules {
    Schedule[] value();
}

5. 检索 (Retrieving) 注解 - 注解与反射

前面我们所有讲解的都是如何声明和使用注解，那么此处就来讲讲怎么获取注解。

这主要是通过反射实现的，主要涉及以下 AnnotatedElement 接口提供的抽象方法：

查询是否应用了某个注解

default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)

获取注解

方法	功能	说明
`<T extends Annotation> T getAnnotation(Class<T> annotationClass)`	返回该程序元素上存在的指定类型的注解，如果该类型的注解不存在，则返回 null	泛型参数表明，只能说注解类型或者某注解类型的子类
`Annotation[] getAnnotations()`	返回该元素上存在的所有注解，包括继承得到的。如果没有注解，那么返回长度为零的数组
`default <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass)`	Java SE 8 新增方法，用来获得修饰该程序元素的、指定类型的多个注解
`default <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass)`	返回直接修饰该程序元素、指定类型的注解。如果该类型注解不存在，返回 null	忽略继承得到的注解
`default <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass)`	Java SE 8 新增方法，用来获得直接修饰该程序元素的、指定类型的多个注解	忽略继承得到的注解
`Annotation[] getDeclaredAnnotations()`	返回直接存在于此元素上的所有注解。如果没有注解，返回长度为零的数组。	忽略继承得到的注解

下面具体来看个例子：

MyAnnotation.java

@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)//指定注解保存在JVM 中，运行时可使用
@Target({ElementType.TYPE,ElementType.FIELD,ElementType.METHOD})//注解可以应用于类、方法和字段上
public @interface MyAnnotation{ 
    String type() default "ignore";
    String[] hobby();
}

TestAnnotation.java

@MyAnnotation(type = "class",hobby = {"sleep","play"})
public class TestAnnotation {
    
    @MyAnnotation(type = "Field",hobby = {"read"})
    private String whdalive;
    
    @MyAnnotation(type = "Field",hobby = {"piano"})
    private String cy;
    
    @MyAnnotation(type = "Method",hobby = {"guitar"})
    public void method1(){
        
    }
    
    public static void main(String[] args) {
        
        //反射获取类对象
        Class<TestAnnotation> clz = TestAnnotation.class;
        //类上是否含有指定类型注解
        boolean clzHasAnno = clz.isAnnotationPresent(MyAnnotation.class);
        //如果有，获取注解元素的值
        if(clzHasAnno) {
            MyAnnotation annotation = clz.getAnnotation(MyAnnotation.class);
            String type = annotation.type();
            String[] hobby = annotation.hobby();
            System.out.println(clz.getName() + ", type = " + type + ", hobby = " + Arrays.asList(hobby).toString());
        }
        //反射获取字段
        Field[] fields = clz.getDeclaredFields();
        for(Field field : fields) {
            boolean fieldHasAnno = field.isAnnotationPresent(MyAnnotation.class);
            if (fieldHasAnno) {
                MyAnnotation annotation = field.getAnnotation(MyAnnotation.class);
                String type = annotation.type();
                String[] hobby = annotation.hobby();
                System.out.println(field.getName() + ", type = " + type + ", hobby = " + Arrays.asList(hobby).toString());
            }
        }
        //反射获取方法
        Method[] methods = clz.getDeclaredMethods();
        for (Method method : methods) {
            boolean methodHasAnno = method.isAnnotationPresent(MyAnnotation.class);
            if (methodHasAnno) {
                MyAnnotation annotation = method.getAnnotation(MyAnnotation.class);
                String type = annotation.type();
                String[] hobby = annotation.hobby();
                System.out.println(method.getName() + ", type = " + type + ", hobby = " + Arrays.asList(hobby).toString());
            }
            
        }
    }
}

输出结果

com.whdalive.reflection.TestAnnotation, type = class, hobby = [sleep, play]
whdalive, type = Field, hobby = [read]
cy, type = Field, hobby = [piano]
method1, type = Method, hobby = [guitar]

总结

注解是 Java 引入的一个非常受欢迎的机制，它提供了一种结构化的并且具有类型检查能力的新途径。我们可以通过注解为代码加入元数据，而不会导致代码杂乱难以阅读。

同时，注解还是 Android 诸多开源框架的实现基础。比如 ButterKnife、Retrofit、Dagger2 等等等等。

注解还是很有必要好好学习一下的。

共勉。