注解 - 内置注解，元注解与自定义注解

image

注解的作用

注解这一概念是在java1.5版本提出的，Java提供了一种原程序中的元素关联任何信息和任何元数据的途径的方法。

单纯说注解，注解本身没有任何的作用。简单说和注释没啥区别，而它有作用的原因是：注解解释类，也就是相关对代码进行解释的特定类。一般这些类使用反射是可以拿到的。

因此，通过注解和反射这两者的结合使用，是可以做到很多功能的。在实际开发中使用到的一些第三方框架，很多框架都是使用了注解。如果再深入的看一看源码就会发现，很多注解是和反射一起使用的。

---

内置注解

Java 定义了一套注解，共有 7 个，3 个在 java.lang 中，剩下 4 个在 java.lang.annotation 中。

作用在代码的注解是

• @Override - 检查该方法是否是重载方法。如果发现其父类，或者是引用的接口中并没有该方法时，会报编译错误。
• @Deprecated - 标记过时方法。如果使用该方法，会报编译警告。
• @SuppressWarnings - 指示编译器去忽略注解中声明的警告。

作用在其他注解的注解(或者说 元注解)是:

• @Retention - 标识这个注解怎么保存，是只在代码中，还是编入class文件中，或者是在运行时可以通过反射访问。
• @Documented - 标记这些注解是否包含在用户文档中。
• @Target - 标记这个注解应该是哪种 Java 成员。
• @Inherited - 标记这个注解是继承于哪个注解类(默认 注解并没有继承于任何子类)

从 Java 7 开始，额外添加了 3 个注解:

• @SafeVarargs - Java 7 开始支持，忽略任何使用参数为泛型变量的方法或构造函数调用产生的警告。
• @FunctionalInterface - Java 8 开始支持，标识一个匿名函数或函数式接口。
• @Repeatable - Java 8 开始支持，标识某注解可以在同一个声明上使用多次。

Annotation 架构

Image text

1）1个Annotation和1个RetentionPolicy关联。可以理解为：每1个Annotation对象，都会有唯一的RetentionPolicy属性。
2）1个Annotation和1~n个ElementType关联。可以理解为：对于每 1 个 Annotation 对象，可以有若干个 ElementType 属性。
3）Annotation有许多实现类，包括：Deprecated, Documented, Inherited, Override 等等。

注：Annotation 的每一个实现类，都 "和 1 个 RetentionPolicy 关联" 并且 " 和 1~n 个 ElementType 关联"。

---

元注解

@Target：

@Target说明了Annotation所修饰的对象范围：Annotation可被用于packages、types（类、接口、枚举、Annotation类型）、类型成员（方法、构造方法、成员变量、枚举值）、方法参数和本地变量（如循环变量、catch参数）。

在Annotation类型的声明中使用了target可更加明晰其修饰的目标

1. CONSTRUCTOR : 用于描述构造器
2. FIELD : 用于描述域即类成员变量
3. LOCAL_VARIABLE : 用于描述局部变量
4. METHOD : 用于描述方法
5. PACKAGE : 用于描述包
6. PARAMETER : 用于描述参数
7. TYPE : 用于描述类、接口(包括注解类型) 或enum声明

@Retention：

@Retention定义了该Annotation被保留的时间长短：某些Annotation仅出现在源代码中，而被编译器丢弃；而另一些却被编译在class文件中；编译在class文件中的Annotation可能会被虚拟机忽略，而另一些在class被装载时将被读取（请注意并不影响class的执行，因为Annotation与class在使用上是被分离的）。使用这个meta-Annotation可以对 Annotation的“生命周期”限制。

作用：表示需要在什么级别保存该注释信息，用于描述注解的生命周期（即：被描述的注解在什么范围内有效）

取值（RetentionPoicy）有：

1. SOURCE:在源文件中有效（即源文件保留）
2. CLASS:在class文件中有效（即class保留）
3. RUNTIME:在运行时有效（即运行时保留）

@Target(ElementType.FIELD)  
@Retention(RetentionPolicy.RUNTIME)  
public @interface Column {  
    public String name() default "fieldName";  
    public String setFuncName() default "setField";  
    public String getFuncName() default "getField";   
    public boolean defaultDBValue() default false;  
}  

Column注解的的RetentionPolicy的属性值是RUTIME,这样注解处理器可以通过反射，获取到该注解的属性值，从而去做一些运行时的逻辑处理。

@Documented:

@Documented用于描述其它类型的annotation应该被作为被标注的程序成员的公共API，因此可以被例如javadoc此类的工具文档化。Documented是一个标记注解，没有成员。

@Inherited：

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

注意：@Inherited annotation类型是被标注过的class的子类所继承。类并不从它所实现的接口继承annotation，方法并不从它所重载的方法继承annotation。

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

实例代码：

---

自定义注解

使用@interface自定义注解时，自动继承了java.lang.annotation.Annotation接口，由编译程序自动完成其他细节。在定义注解时，不能继承其他的注解或接口。@interface用来声明一个注解，其中的每一个方法实际上是声明了一个配置参数。方法的名称就是参数的名称，返回值类型就是参数的类型（返回值类型只能是基本类型、Class、String、enum）。可以通过default来声明参数的默认值。

定义注解格式：

public @interface 注解名 {
    ... 定义体
}

注解参数的可支持数据类型：

1. 所有基本数据类型（int,float,boolean,byte,double,char,long,short)
2. String类型
3. Class类型
4. enum类型
5. Annotation类型
6. 以上所有类型的数组

示例：

// 自定义注解
public @interface MyAnnotation {

    String value();
    
    int[] nums();
    
    String info() default "默认值"
}

// 使用自定义注解
class Test {

    @MyAnnotation(value = "" , nums = {100,200,300}, info = "自定义注解方法")
    public void methodMyAnnotation(String str) {
        // 具体内容...
    }
    
    public static void main(String[] strs) { 
        // 获取Test类的Class实例
        Class clazz = Test.class;
        // 获取 somebody() 方法的Method实例
        Method methodMA = c.getMethod("methodMyAnnotation", new Class[]{String.class});
        // 获取所有的注解(Annotation)
        Annotation[] annotations = methodMA.getAnnotations();
        for(Annotation annotation : annotations){
            System.out.println(annotation);
        }
        // isAnnotationPresent 判断是否包含指定注解
        if (methodMA.isAnnotationPresent(MyAnnotation.class)) {
            // 获取该方法的MyAnnotation注解实例
            MyAnnotation myAnnotation = methodMA.getAnnotation(MyAnnotation.class);
            // 获取 myAnnotation的值，并打印出来
            String value = myAnnotation.value();
            System.out.printfln("value:" + value);
            
            int[] nums = myAnnotation.nums();
            System.out.printf("nums:" + value);
            for(int i = 0; i < nums.length; i++){
              if(i==nums.length-1){
                System.out.printf(i + "");
              }else{
                System.out.printf(i + ",");
              }
            }
            System.out.printfln("");
            
            String info = myAnnotation.info();
            System.out.printfln("info:" + info);
        }
    }
}

说明：

1. 当定义的注解中只有一个属性value的时候，在使用此注解时，对其value属性赋值可以不必明确写上value而是直接使用属性值即可。
2. 当定义的注解中有value属性，同时也包含有其他属性时候，那么在对属性赋值时候，必须明确的以name = value的形式赋值。
3. 如果注解中存在数组属性，那么在对其赋值的时候，如果是单个值，可不使用“{}”的形式，如果是多个值，必须使用“{}”。
   也可以对属性值直接赋予默认值，使用default关键字，那么在赋值的时候，可以不指定值，那么使用的就是默认值，同时也可以对于赋予新的值。

---

参考：https://www.runoob.com/w3cnote/java-annotation.html