注解Annotation

秒懂，Java 注解 （Annotation）你可以这样学

1、Annotation的概述

1.1、定义

注解（Annotation），也叫元数据，是一种代码级别的说明。

它是JDK1.5及以后版本引入的一个特性，与类、接口、枚举是在同一个层次。它可以声明在包、类、字段、方法、局部变量、方法参数等的前面，用来对这些元素进行说明，注释。

其实Annotation就是代码里的特殊标记，它们可以在编译，类加载，运行时被读取，并执行相应的处理，以便于其他工具补充信息或者进行部署。

注意：Annotation能被用来为程序元素（类、方法、成员变量等）设置元素据。Annotaion不影响程序代码的执行，无论增加、删除Annotation，代码都始终如一地执行。如果希望让程序中的Annotation起一定的作用，只有通过解析工具或编译工具对Annotation中的信息进行解析和处理。

1.2、Annotation作用分类

一般来说，元数据可以用于创建文档（根据程序元素上的注释创建文档），跟踪代码中的依赖性（可声明方法是重载，依赖父类的方法），执行编译时检查（可声明是否编译期检测），代码分析。
如下：

• 1、编写文档：通过注解生成API文档（@Documented）
• 2、编译检查：通过注解让编译器实现基本的编译检查（@Override）
• 3、代码分析：通过注解对代码进行分析【反射等】（重点）

1.3、Annotation 架构

从中，我们可以看出：

• (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 关联"。

下面，我先介绍框架图的左半边(如下图)，即 Annotation, RetentionPolicy, ElementType；然后在就 Annotation 的实现类进行举例说明。

Annotation 组成部分

java Annotation 的组成中，有 3 个非常重要的主干类。它们分别是：

Annotation.java

package java.lang.annotation;
public interface Annotation {boolean equals(Object obj);int hashCode();String toString();Class<? extends Annotation> annotationType();
}

ElementType.java

package java.lang.annotation;public enum ElementType {TYPE,               /* 类、接口（包括注释类型）或枚举声明  */FIELD,              /* 字段声明（包括枚举常量）  */METHOD,             /* 方法声明  */PARAMETER,          /* 参数声明  */CONSTRUCTOR,        /* 构造方法声明  */LOCAL_VARIABLE,     /* 局部变量声明  */ANNOTATION_TYPE,    /* 注释类型声明  */PACKAGE             /* 包声明  */
}

RetentionPolicy.java

package java.lang.annotation;
public enum RetentionPolicy {SOURCE,            /* Annotation信息仅存在于编译器处理期间，编译器处理完之后就没有该Annotation信息了  */CLASS,             /* 编译器将Annotation存储于类对应的.class文件中。默认行为  */RUNTIME            /* 编译器将Annotation存储于class文件中，并且可由JVM读入 */
}

说明：

(1) Annotation 就是个接口。
“每 1 个 Annotation” 都与 “1 个 RetentionPolicy” 关联，并且与 “1～n 个 ElementType” 关联。可以通俗的理解为：每 1 个 Annotation 对象，都会有唯一的 RetentionPolicy 属性；至于 ElementType 属性，则有 1~n 个。

(2) ElementType 是 Enum 枚举类型，它用来指定 Annotation 的类型。
“每 1 个 Annotation” 都与 “1～n 个 ElementType” 关联。当 Annotation 与某个 ElementType 关联时，就意味着：Annotation有了某种用途。例如，若一个 Annotation 对象是 METHOD 类型，则该 Annotation 只能用来修饰方法。

(3) RetentionPolicy 是 Enum 枚举类型，它用来指定 Annotation 的策略。通俗点说，就是不同 RetentionPolicy 类型的 Annotation 的作用域不同。

“每 1 个 Annotation” 都与 “1 个 RetentionPolicy” 关联。

• a) 若 Annotation 的类型为 SOURCE，则意味着：Annotation 仅存在于编译器处理期间，编译器处理完之后，该Annotation 就没用了。 例如，" @Override" 标志就是一个Annotation。当它修饰一个方法的时候，就意味着该方法覆盖父类的方法；并且在编译期间会进行语法检查！编译器处理完后，"@Override"就没有任何作用了。
• b) 若 Annotation 的类型为 CLASS，则意味着：编译器将 Annotation 存储于类对应的 .class 文件中，它是Annotation 的默认行为。
• c) 若 Annotation 的类型为 RUNTIME，则意味着：编译器将 Annotation 存储于 class文件中，并且可由JVM读入。

这时，只需要记住"每 1 个 Annotation" 都与 “1 个 RetentionPolicy” 关联，并且与 “1～n 个 ElementType” 关联。

2、Annotation的语法形式

public @interface 注解名称 {}

我们可以定义一个简单的注解，如下：

package com.hanyxx.annotaion;/*** @author xxx* @description: 自定义注解*/
public @interface bocai {
}

如果通过 javac命令将注解类编译，然后再通过 javap 命令进行反编译，就会发现：
public interface com.hanyxx.annotaion.bocai extends java.lang.annotation.Annotation {}

注解的本质就是：接口

3、Annotation的分类

java内置了6个基本注解和4个元注解

3.1、基本注解

@Override ：检测被该注解标注的方法是继承自父类(接口)的@Deprecated：该注解标注的内容，表示已过时@SuppressWarnings：压制警告其中jdk1.7之后引入了另外两个基本注解：@SafeVarargs ： Java7 开始支持，忽略任何使用参数为泛型变量的方法或构造函数调用产生的警告@FunctionalInterface ： Java8 开始支持，标识一个匿名函数或函数式接口。@Repeatable： Java8 开始支持，标识某注解可以在同一个声明上使用多次其中@Override、@Deprecated、@SuppressWarnings、@SafeVarargs
和@FunctionalInterface在java.lang包下而@Repeatable在java.lang.annotation包下

/*** @Date 2021/11/13 14:04* @Version 10.21* @Author XXX*/
public class AnnotationTest {public static void main(String[] args) {@SuppressWarnings("unused")int a = 10;}@Deprecatedpublic void myPrint(){System.out.println("@Deprecated修饰的方法表示已过时");}@Overridepublic String toString(){return "重写的toString()";}
}

3.2、元注解

元注解（meta-annotation）：定义注解的注解

3.2.1、@Target

@Target：用于描述注解能够作用的范围，可取的值存于ElementType枚举类中。

• 当注解类型声明中没有@Target元注解，则默认为可适用所有的程序元素。如果存在指定的@Target元注解，则编译器强制实施相应的使用限制。

@Target(ElementType.TYPE)
public @interface Table {/*** 数据表名称注解，默认值为类名称* @return*/public String tableName() default "className";
}@Target(ElementType.FIELD)
public @interface NoDBColumn {}

注解Table 可以用于注解类、接口(包括注解类型) 或enum声明,而注解NoDBColumn仅可用于注解类的成员变量。

3.2.2、@Retention

@Retention：指定所修饰的 Annotation 的生命周期：SOURCE\CLASS（默认行为）\RUNTIME只有声明为RUNTIME生命周期的注解，才能通过反射获取。

@Rentention 包含一个 RetentionPolicy 类型的成员变量, 使用@Rentention 时必须为该 value 成员变量指定值：

• RetentionPolicy.SOURCE:在源文件中有效（即源文件保留），编译器直接丢弃这种策略的注释
• RetentionPolicy.CLASS:在class文件中有效（即class保留） ， 当运行 Java 程序时,
  JVM不会保留注解。 这是默认值
• RetentionPolicy.RUNTIME:在运行时有效（即运行时保留），当运行 Java程序时, JVM会保留注释。程序可以通过反射获取 该注释。
  

@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,这样注解处理器可以通过反射，获取到该注解的属性值，从而去做一些运行时的逻辑处理

3.2.3、@Documented

@Documented:用于指定被该元 Annotation 修饰的 Annotation 类将被javadoc 工具提取成文档。默认情况下，javadoc是不包括注解的。

• 定义为Documented的注解必须设置Retention值为RUNTIME。

@author 标明开发该类模块的作者，多个作者之间使用,分割@version 标明该类模块的版本@see 参考转向，也就是相关主题@since 从哪个版本开始增加的@param 对方法中某参数的说明，如果没有参数就不能写@return 对方法返回值的说明，如果方法的返回值类型是void就不能写@exception 对方法可能抛出的异常进行说明 ，如果方法没有用throws显式抛出的异常就不能写其中@param @return 和 @exception 这三个标记都是只用于方法的。@param的格式要求：@param 形参名 形参类型 形参说明@return 的格式要求：@return 返回值类型 返回值说明@exception的格式要求：@exception 异常类型 异常说明@param和@exception可以并列多个

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

3.2.4、@Inherited:

@Inherited:被它修饰的 Annotation 将具有 继承性。如果某个类使用了被@Inherited 修饰的 Annotation, 则其子类将自动具有该注解。

• 比如：如果把标有@Inherited注解的自定义的注解标注在类级别上，子类则可以继承父类类级别的注解。

注意：

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

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

/*** * @author test**/
@Inherited
public @interface Greeting {public enum FontColor{ BULE,RED,GREEN};String name();FontColor fontColor() default FontColor.GREEN;
}

4、自定义annotation

4 .1、定义说明

• 1、定义新的 Annotation 类型使用 @interface 关键字
• 2、自定义注解自动继承了java.lang.annotation.Annotation 接口
• 3、Annotation 的成员变量在Annotation定义中以无参数方法的形式来声明。其方法名和返回值定义了该成员的名字和类型。我们称为配置参数。类型只能是八种基本数据类型、String类型、Class 类型 、enum 类型 、Annotation 类型 、以上所有类型的 数组。
• 4、可以在定义 Annotation的成员变量时为其指定初始值, 指定成员变量的初始值可使用 default 关键字
• 5、如果只有一个参数成员，建议使用 参数名为value
• 6、如果定义的注解含有配置参数，那么使用时必须指定参数值，除非它有默认值。格式是“参数名 = 参数值”，如果只有一个参数成员，且名称为value，可以省略“value=”
• 7、没有成员定义的 Annotation 称为 标记; 包含成员变量的 Annotation 称为元数据 Annotation

注意：自定义注解必须配上注解的信息处理流程才有意义。

package com.hanyxx.annotaion;
import java.lang.annotation.*;
/*** @author 菠菜饭团* @description: 自定义注解*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface BoCai {String name() default "XXX";ElementType[] value() default ElementType.TYPE ;String className();String methodName();
}

package com.hanyxx.annotaion;
import java.lang.reflect.Method;
/*** @author XXX* @description: 通过注解的形式创建任意对象，并且执行任意方法*/
@BoCai(className="com.hanyxx.annotaion.PlayGame",methodName = "play")
public class AnnotationTest {public static void main(String[] args) throws Exception {/***  <A extends Annotation> A getAnnotation(Class<A> annotationClass) ：如果存在该元素的指定类型的注解，则返回这些注解，否则返回 null。*  Annotation[] getAnnotations() : 返回此元素上存在的所有注解。*///1.获取类字节码对象Class<AnnotationTest> annotationClass = AnnotationTest.class;//2.获取该类的注解对象(本质是在内存中生成该注解接口的子类实现对象)BoCai boCai = annotationClass.getAnnotation(BoCai.class);//3.获取传入的类名和方法名String className = boCai.className();System.out.println("获取类名:"+className);System.out.println("===========================");String methodName = boCai.methodName();System.out.println("获取方法名:"+methodName);System.out.println("===========================");//4.加载类进内存，并获取方法对象Class<?> Cls = Class.forName(className);Method method = Cls.getMethod(methodName);//5.创建对象实例并调用方法Object o = Cls.newInstance();method.invoke(o);}
}

4.2、实例

MyAnnotation

package com.atguigu.java1;import java.lang.annotation.*;import static java.lang.annotation.ElementType.*;@Inherited
@Repeatable(MyAnnotations.class)
@Retention(RetentionPolicy.RUNTIME)
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE,TYPE_PARAMETER,TYPE_USE})
public @interface MyAnnotation {String value() default "hello";
}

MyAnnotations

package com.atguigu.java1;import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;import static java.lang.annotation.ElementType.*;@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
public @interface MyAnnotations {MyAnnotation[] value();
}

AnnotationTest

package com.atguigu.java1;import org.junit.Test;import java.lang.annotation.Annotation;
import java.util.ArrayList;
import java.util.Date;/*** 注解的使用** 1. 理解Annotation:* ① jdk 5.0 新增的功能** ② Annotation 其实就是代码里的特殊标记, 这些标记可以在编译, 类加载, 运行时被读取, 并执行相应的处理。通过使用 Annotation,* 程序员可以在不改变原有逻辑的情况下, 在源文件中嵌入一些补充信息。** ③在JavaSE中，注解的使用目的比较简单，例如标记过时的功能，忽略警告等。在JavaEE/Android* 中注解占据了更重要的角色，例如用来配置应用程序的任何切面，代替JavaEE旧版中所遗留的繁冗* 代码和XML配置等。** 2. Annocation的使用示例* 示例一：生成文档相关的注解* 示例二：在编译时进行格式检查(JDK内置的三个基本注解)@Override: 限定重写父类方法, 该注解只能用于方法@Deprecated: 用于表示所修饰的元素(类, 方法等)已过时。通常是因为所修饰的结构危险或存在更好的选择@SuppressWarnings: 抑制编译器警告* 示例三：跟踪代码依赖性，实现替代配置文件功能** 3. 如何自定义注解：参照@SuppressWarnings定义* ① 注解声明为：@interface* ② 内部定义成员，通常使用value表示* ③ 可以指定成员的默认值，使用default定义* ④ 如果自定义注解没有成员，表明是一个标识作用。如果注解有成员，在使用注解时，需要指明成员的值。自定义注解必须配上注解的信息处理流程(使用反射)才有意义。自定义注解通过都会指明两个元注解：Retention、Target4. jdk 提供的4种元注解元注解：对现有的注解进行解释说明的注解Retention：指定所修饰的 Annotation 的生命周期：SOURCE\CLASS（默认行为）\RUNTIME只有声明为RUNTIME生命周期的注解，才能通过反射获取。Target:用于指定被修饰的 Annotation 能用于修饰哪些程序元素*******出现的频率较低*******Documented:表示所修饰的注解在被javadoc解析时，保留下来。Inherited:被它修饰的 Annotation 将具有继承性。5.通过反射获取注解信息 ---到反射内容时系统讲解6. jdk 8 中注解的新特性：可重复注解、类型注解6.1 可重复注解：① 在MyAnnotation上声明@Repeatable，成员值为MyAnnotations.class② MyAnnotation的Target和Retention等元注解与MyAnnotations相同。6.2 类型注解：ElementType.TYPE_PARAMETER 表示该注解能写在类型变量的声明语句中（如：泛型声明）。ElementType.TYPE_USE 表示该注解能写在使用类型的任何语句中。**/
public class AnnotationTest {public static void main(String[] args) {Person p = new Student();p.walk();Date date = new Date(2020, 10, 11);System.out.println(date);@SuppressWarnings("unused")int num = 10;//        System.out.println(num);@SuppressWarnings({ "unused", "rawtypes" })ArrayList list = new ArrayList();}@Testpublic void testGetAnnotation(){Class clazz = Student.class;Annotation[] annotations = clazz.getAnnotations();for(int i = 0;i < annotations.length;i++){System.out.println(annotations[i]);}}
}//jdk 8之前的写法：
//@MyAnnotations({@MyAnnotation(value="hi"),@MyAnnotation(value="hi")})
@MyAnnotation(value="hi")
@MyAnnotation(value="abc")
class Person{private String name;private int age;public Person() {}@MyAnnotationpublic Person(String name, int age) {this.name = name;this.age = age;}@MyAnnotationpublic void walk(){System.out.println("人走路");}public void eat(){System.out.println("人吃饭");}
}interface Info{void show();
}class Student extends Person implements Info{@Overridepublic void walk() {System.out.println("学生走路");}public void show() {}
}class Generic<@MyAnnotation T>{public void show() throws @MyAnnotation RuntimeException{ArrayList<@MyAnnotation String> list = new ArrayList<>();int num = (@MyAnnotation int) 10L;}}

参考

1、https://www.cnblogs.com/Tanyboye/p/9138412.html
2、Java 注解（Annotation）