自定义注解详解

文章引用

深入理解Java：注解（Annotation）自定义注解入门

自定义注解详细介绍

说在最前

文章忽略特性的一些基本概念

注解的本质是反射

1. 自定义注解

注解其实就是一种标记，可以在程序代码中的关键节点（类、方法、变量、参数、包）上打上这些标记，然后程序在编译时或运行时可以检测到这些标记从而执行一些特殊操作

• 第一步：定义注解——相当于定义标记
• 第二步：配置注解——把标记打在需要用到的程序代码中
• 第三部：解析注解——在编译期或运行时监测到标记，并进行特殊操作

1.2 基本语法

注解类型的声明部分：

注解在Java中，与类、接口、枚举类似，因此其声明语法基本一致，只是所使用的关键字有所不同@interface。在底层实现上，所有定义的注解都会自动继承java.lang.annotation.Annotation接口。在自定义注解中，其实现部分只能定义一个东西：注解类型元素（annotation type element）

public @interface MyAnnotation {
    public String name();
	int age() default 18; //赋予默认值
	int[] array();
}

1.2.1 定义注解类型的注意项

1. 访问修饰符必须为public，不写默认为public；
2. 该元素的类型只能是基本数据类型、String、Class、枚举类型（enum）、注解类型（annotation:体现了注解的嵌套效果）以及上述类型的一位数组；
3. 该元素的名称一般定义为名词，如果注解中只有一个元素，请把名字起为value（后面使用会带来便利操作）；
4. ()不是定义方法参数的地方，也不能在括号中定义任何参数，仅仅只是一个特殊的语法；
5. default代表默认值，值必须和第2点定义的类型一致；
6. 如果没有默认值，代表后续使用注解时必须给该类型元素赋值。

可以看出，注解类型元素的语法非常奇怪，即又有属性的特征（可以赋值）,又有方法的特征（打上了一对括号）。但是这么设计是有道理的，我们在后面的章节中可以看到：注解在定义好了以后，使用的时候操作元素类型像在操作属性，解析的时候操作元素类型像在操作方法。

1.3 元注解

元注解：专门修饰注解的注解。它们都是为了更好的设计自定义注解的细节而专门设计的。

1.3.1 @Target

@Target注解，是专门用来限定某个自定义注解能够被应用在哪种Java元素上面的

public enum ElementType {
    /** 类，接口（包括注解类型）或枚举的声明 */
    TYPE,

    /** 属性的声明 */
    FIELD,

    /** 方法的声明 */
    METHOD,

    /** 方法形式参数声明 */
    PARAMETER,

    /** 构造方法的声明 */
    CONSTRUCTOR,

    /** 局部变量声明 */
    LOCAL_VARIABLE,

    /** 注解类型声明 */
    ANNOTATION_TYPE,

    /** 包的声明 */
    PACKAGE
}

//@CherryAnnotation被限定只能使用在类、接口或方法上面
@Target(value = {ElementType.TYPE,ElementType.METHOD})
public @interface MyAnnotation {
    String name();
    int age() default 18;
    int[] array();
}

1.3.2 @Retention

用来修饰自定义注解的生命力。

注解的生命周期有三个阶段：

1. .java源文件阶段；
2. 编译到class文件阶段；
3. 运行期阶段。同样使用了RetentionPolicy枚举类型定义了三个阶段：

public enum RetentionPolicy {
    /**
     * Annotations are to be discarded by the compiler.
     * （注解将被编译器忽略掉）
     */
    SOURCE,

    /**
     * Annotations are to be recorded in the class file by the compiler
     * but need not be retained by the VM at run time.  This is the default
     * behavior.
     * （注解将被编译器记录在class文件中，但在运行时不会被虚拟机保留，这是一个默认的行为）
     */
    CLASS,

    /**
     * Annotations are to be recorded in the class file by the compiler and
     * retained by the VM at run time, so they may be read reflectively.
     * （注解将被编译器记录在class文件中，而且在运行时会被虚拟机保留，因此它们能通过反射被读取到）
     * @see java.lang.reflect.AnnotatedElement
     */
    RUNTIME
}

1. 如果一个注解被定义为RetentionPolicy.SOURCE，则它将被限定在Java源文件中，那么这个注解即不会参与编译也不会在运行期起任何作用，这个注解就和一个注释是一样的效果，只能被阅读Java文件的人看到；
2. 如果一个注解被定义为RetentionPolicy.CLASS，则它将被编译到Class文件中，那么编译器可以在编译时根据注解做一些处理动作，但是运行时JVM（Java虚拟机）会忽略它(例如@Override)，我们在运行期也不能读取到；
3. 如果一个注解被定义为RetentionPolicy.RUNTIME，那么这个注解可以在运行期的加载阶段被加载到Class对象中。那么在程序运行阶段，我们可以通过反射得到这个注解，并通过判断是否有这个注解或这个注解中属性的值，从而执行不同的程序代码段。我们实际开发中的自定义注解几乎都是使用的RetentionPolicy.RUNTIME；
4. 在默认的情况下，自定义注解是使用的RetentionPolicy.CLASS。

1.3.3 @Documented

@Documented注解，是被用来指定自定义注解是否能随着被定义的java文件生成到JavaDoc文档当中。

1.3.4 @Inherited

@Inherited注解，是指定某个自定义注解如果写在了父类的声明部分，那么子类的声明部分也能自动拥有该注解。@Inherited注解只对那些@Target被定义为ElementType.TYPE的自定义注解起作用。

2. 自定义注解的使用

回顾一下注解的使用流程：

• 第一步，定义注解——相当于定义标记；
• 第二步，配置注解——把标记打在需要用到的程序代码中；
• 第三步，解析注解——在编译期或运行时检测到标记，并进行特殊操作。

到目前为止我们只是完成了第一步，接下来我们就来学习第二步，配置注解，如何在另一个类当中配置它。

2.1 在具体额Java类上使用注解

首先，定义一个注解、和一个供注解修饰的简单Java类

@Retention(RetentionPolicy.RUNTIME)
@Target(value = {ElementType.METHOD})
@Documented
public @interface MyAnnotation {
    String name();
    int age() default 18;
    int[] score();
}

public class Student{
    public void study(int times){
        for(int i = 0; i < times; i++){
            System.out.println("Good Good Study, Day Day Up!");
        }
    }
}

2.2 特殊语法

特殊语法一：如果注解本身没有注解类型元素，那么在使用注解的时候可以省略()，直接写为：@注解名，它和标准语法@注解名()等效！

@Retention(RetentionPolicy.RUNTIME)
@Target(value = {ElementType.TYPE})
@Documented
public @interface FirstAnnotation {
}

//等效于@FirstAnnotation()
@FirstAnnotation
public class JavaBean{
	//省略实现部分
}

特殊语法二：如果注解本本身只有一个注解类型元素，而且命名为value，那么在使用注解的时候可以直接使用：@注解名(注解值)，其等效于：@注解名(value = 注解值)

@Retention(RetentionPolicy.RUNTIME)
@Target(value = {ElementType.TYPE})
@Documented
public @interface SecondAnnotation {
	String value();
}

//等效于@ SecondAnnotation(value = "this is second annotation")
@SecondAnnotation("this is annotation")
public class JavaBean{
	//省略实现部分
}

特殊用法三：如果注解中的某个注解类型元素是一个数组类型，在使用时又出现只需要填入一个值的情况，那么在使用注解时可以直接写为：@注解名(类型名 = 类型值)，它和标准写法：@注解名(类型名 = {类型值})等效！

@Retention(RetentionPolicy.RUNTIME)
@Target(value = {ElementType.TYPE})
@Documented
public @interface ThirdAnnotation {
	String[] name();
}

//等效于@ ThirdAnnotation(name = {"this is third annotation"})
@ ThirdAnnotation(name = "this is third annotation")
public class JavaBean{
	//省略实现部分
}

3.自定义注解的运行时解析

系统是如何在程序运行时检测到注解，并进行一系列特殊操作？

只有当注解的保持力处于运行阶段，即使用@Retention(RetentionPolicy.RUNTIME)修饰注解时，才能在JVM运行时，检测到注解，并进行一系列特殊操作。

3.1 反射操作获取注解

因此，明确我们的目标：在运行期探究和使用编译期的内容（编译期配置的注解），要用到Java中的灵魂技术——反射！

public class TestAnnotation {
    public static void main(String[] args) {
        try{
            //获取Student的Class对象
            Class stuClass = Class.forName("com.hong.example.Student");
            //这里的形参不能写成Integer.class,应该写int.class
            Method stuMethod = stuClass.getMethod("study",int.class);
            if (stuMethod.isAnnotationPresent(MyAnnotation.class)){
                System.out.println("Student类上配置了MyAnnotation注解！");
                //获取该元素上指定类型的注解
                MyAnnotation myAnnotation = stuMethod.getAnnotation(MyAnnotation.class);
                System.out.print("name: "+myAnnotation.name()+", age: "+myAnnotation.age()+", score:");
                for (int i = 0 ;i < myAnnotation.score().length;i++){
                    System.out.print(myAnnotation.score()[i]+" ");
                }
            }else{
                System.out.println("Student类上没有配置MyAnnotation注解");
            }
            System.out.println();
        }catch (ClassNotFoundException | NoSuchMethodException e){
            e.printStackTrace();
        }
    }
}

1. 如果我们要获得的注解是配置在方法上的，那么我们要从Method对象上获取；如果是配置在属性上，就需要从该属性对应的Field对象上去获取，如果是配置在类型上，需要从Class对象上去获取。总之在谁身上，就从谁身上去获取！
2. isAnnotationPresent(Class<? extends Annotation> annotationClass)方法是专门判断该元素上是否配置有某个指定的注解；
3. getAnnotation(Class<A> annotationClass)方法是获取该元素上指定的注解。之后再调用该注解的注解类型元素方法就可以获得配置时的值数据；
4. 反射对象上还有一个方法getAnnotations()，该方法可以获得该对象身上配置的所有的注解。它会返回给我们一个注解数组，需要注意的是该数组的类型是Annotation类型，这个Annotation是一个来自于java.lang.annotation包的接口。