Java注解 annotation

一.什么是注解

官方解释：

Java 注解用于为Java程序提供元数据。作为元数据，注解不直接影响代码的执行，但也有一些注解实际上可以用于这一目的。

什么是元数据，即一种描述数据的数据。所以可以说注解是描述源代码的数据。
简单理解注解可以看出一个个标签，用来标记你的代码，是一种应用于类，方法，参数，变量，构造器及包的一种特殊修饰符。

二.注解的定义

注解和class，interface一样也是一种类型，通过@interface定义
如下：

public @interface TestAnnotation {
    
}

三.元注解

注解的应用应用很简单，我们用使用TestAnnotation注解，在你想注解的类中@TestAnnotation就可以了
如下（注解类）：

@TestAnnotation
public class Test {
}

但是要想注解想要正常工作还需要元注解的帮助

1.什么是元注解

元注解就是注解到注解上的注解，或者说元注解是一种基本注解，它能用来注解其他注解。
我们可以将元注解看成一种特殊的修饰符，用来解释说明注解，它是注解的元数据。

2.元注解的种类

元注解一共用5种：

@Retention
Retention意为保留期，@Retention用来解释说明一个注解的存活周期
@Retention取值：
- RetentionPolicy.SOURCE 注解只在源码阶段保留，在编译器进行编译时它将被丢弃忽视。
- RetentionPolicy.CLASS 注解只被保留到编译进行的时候，它并不会被加载到 JVM 中。
- RetentionPolicy.RUNTIME 注解可以保留到程序运行的时候，它会被加载进入到 JVM 中，所以在程序运行时可以获取到它们。
  示例：

@Retention(RetentionPolicy.CLASS)
public @interface TestAnnotation {

}

@Documented
用于描述其它类型的annotation应该被作为被标注的程序成员的公共API，因此可以被例如javadoc此类的工具文档化。Documented是一个标记注解，没有成员。
@Target
指定注解应用的地方，用来限定注解的应用场景（类，方法，参数等等）
（不使用@Target注解则默认不限制）
取值如下：
- ElementType.ANNOTATION_TYPE 可以给一个注解进行注解
- ElementType.CONSTRUCTOR 可以给构造方法进行注解
- ElementType.FIELD 可以给属性进行注解
- ElementType.LOCAL_VARIABLE 可以给局部变量进行注解
- ElementType.METHOD 可以给方法进行注解
- ElementType.PACKAGE 可以给一个包进行注解
- ElementType.PARAMETER 可以给一个方法内的参数进行注解
- ElementType.TYPE 可以给一个类型进行注解，比如类、接口、枚举
@Inherited
继承的意思，当一个超类被@Inherited（@Inherited注解）注解的注解（A注解）进行过注解的话，如果它的子类没有被如何其他注解进行注解，那么这个子类就继承了超类的注解（A注解）

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

@Retention(RetentionPolicy.CLASS)
@Inherited
public @interface TestAnnotation {
}

@TestAnnotation
public class TestA {
}

public class TestB extends TestA{

}

TestAnnotation 被@Retention注解，类TestA被@TestAnnotation注解，类TestB继承类TestA，类TestB也拥有TestAnnotation注解

@Repeatable
@Repeatable是自然可重复的意思。这是Java 1.8加进来的新特性
在需要对同一种注解多次使用时，往往需要借助@Repeatable
举个列子

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Roles {
    Role[] value();
}

@Repeatable(Roles.class)
public @interface Role {
    String role() default "";
}

@Role(role="husband")
@Role(role="father")
@Role(role="son")
public class Person {
}

上面的代码@Repeatable注解了Role ，@Repeatable 后面括号中的类相当于一个容器注解

什么是容器注解：
本身也是注解，用来存放其他注解
按照规定，它里面必须要有一个 value 的属性，属性类型是一个被 @Repeatable 注解过的注解数组

@Role(role="husband")，role="husband"表示给Role这个注解的role属性赋值，关于注解的属性下面会说明。
Person 类需要多次使用@Role注解，所以这里使用@Repeatable注解@Role

测试一下注解效果：

Annotation[] annotations = Person.class.getAnnotations();
        System.out.println(annotations.length);
        Roles p1=(Roles) annotations[0];
        for(Role t:p1.value()){
            System.out.println(t.role());
        }

打印如下：

1
husband
father
son

四.注解的属性

注解的属性也叫成员变量。注解只有成员变量，没有方法。注解的成员变量在注解的定义中以“无参的方法”的形式来声明，其方法名定义了该成员变量的名字，其返回值定义了该成员变量的类型。

注解的属性类型必须以下几种：
8中基本类型（byte，boolean，char，short，int，long，float，double,）和
String，Enum，Class，annotation类型，以及这些类型的数组

public @interface TestAnnotation {
    int id();

    String msg();
}

上面代码定义TestAnnotation 这个注解有id和msg两个属性。在使用的时候我们需要给它们赋值

赋值方式：括号内以value=“”的形式赋值，多个属性以'',''隔开

@TestAnnotation(id = 1, msg = "注解测试")
public class Test {
}

注解中可以设置默认值，默认值用default关键字指定
使用注解时对于指定了默认值的属性，如果不需要修改，可以不赋值

public @interface TestAnnotation {
    int id() default 0;

    String msg() default "msg";
}

@TestAnnotation()
public class Test {
}

当一个注解只有一个属性且属性名为value时，使用此注解可以省略括号内的属性名直接赋值

public @interface TestAnnotation {
    String value();
}

@TestAnnotation("1")
public class Test {
}

如果注解没有属性，括号也可以省略

public @interface TestAnnotation {
}

@TestAnnotation
public class Test {
}

五.JDK预制注解

@Deprecated
标记过时元素的注解，用来标识类，方法或者变量已过时，不建议使用。调用过时方法时编译器会提醒。
@Override
重写注解，用来表示子类的方法是覆盖父类的方法。
@SuppressWarnings
抑制警告注解，用于抑制编译器产生警告信息.
@SafeVarargs
参数安全类型注解。它的目的是提醒开发者不要用参数做一些不安全的操作,它的存在会阻止编译器产生 unchecked 这样的警告。它是在 Java 1.7 的版本中加入的
@FunctionalInterface
函数式接口（函数式接口可以很容易转换为 Lambda 表达式）注解，这个是 Java 1.8 版本引入的新特性。函数式编程很火，所以 Java 8 也及时添加了这个特性。

六.注解的提取与应用

注解通过反射获取，通过Class对象的方法获取注解
常用的三个方法：

isAnnotationPresent()方法判断是否应用了某个注解

public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) {...}

getAnnotation() 方法获取指定类型的注解

public <A extends Annotation> A getAnnotation(Class<A> annotationClass) {...}

getAnnotations方法获取注解到当前元素上的所有注解

public Annotation[] getAnnotations() {

示例(以运行时注解为例)：获取下面TestAnnotation 注解的msg属性内容，可以如下获取

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE,ElementType.FIELD})
public @interface TestAnnotation {
    String msg();
}

@TestAnnotation(msg="注解内容")
public class Test {
}

public static void main(String[] args) {
        boolean hasAnnotation = Test.class.isAnnotationPresent(TestAnnotation.class);
        if (hasAnnotation){
            TestAnnotation annotation = Test.class.getAnnotation(TestAnnotation.class);
            System.out.println(annotation.msg());
        }
    }

打印结果：

注解内容

方法和属性也可以借助返回来获取注解

@Retention(RetentionPolicy.RUNTIME)
public @interface TestAnnotation {
    String msg();
}

@TestAnnotation(msg="注解类")
public class Test {

    @TestAnnotation(msg="注解成员变量")
    private String msg;

    @TestAnnotation(msg="注解方法")
    private void setMsg(){

    }
}

public static void main(String[] args) {
        boolean hasAnnotation = Test.class.isAnnotationPresent(TestAnnotation.class);
        if (hasAnnotation) {
            TestAnnotation annotation = Test.class.getAnnotation(TestAnnotation.class);
            if (annotation != null) {
                System.out.println(annotation.msg());
            }
        }

        try {
            //属性获取注解
            Field msg = Test.class.getDeclaredField("msg");
            if (msg != null) {
                msg.setAccessible(true);
                TestAnnotation annotation = msg.getAnnotation(TestAnnotation.class);
                if (annotation != null) {
                    System.out.println(annotation.msg());
                }
            }
            //方法获取注解
            Method setMsg = Test.class.getDeclaredMethod("setMsg");
            if (setMsg != null){
                TestAnnotation annotation = setMsg.getAnnotation(TestAnnotation.class);
                if (annotation != null) {
                    System.out.println(annotation.msg());
                }
            }
        } catch (NoSuchFieldException e) {
            e.printStackTrace();
        } catch (NoSuchMethodException e) {
            e.printStackTrace();
        }
    }

打印结果：

注解类
注解成员变量
注解方法

这里要注意是，如果一个注解要想在运行时被提取，那么@Retention(RetentionPolicy.RUNTIME)是必须的

注解的应用

提供信息给编译器：编译器可以通过注解来探测错误和警告信息
编译阶段处理：软件工具可以利用注解信息来自动生成代码，HTML文档或者做其他相应处理
运行时的处理：某些注解可以在程序运行时接收代码的提取

当开发者使用注解修饰了类，方法，变量等成员后，注解不会自己生效，必须由开发者提供对应的代码来提取处理注解信息。
这些用来提取和处理注解信息的代码统称为APT（Annotation Processing Tool），注解处理器，它用来在编译时扫描和处理注解。具体可参考APT 基于Android工程
总结来说，注解（Annotation）相对于一种标记，注解的应用就是编译器，开发工具或者程序通过反射来提取你的类和各种元素有无这种标记，有某种标记就去做相应的处理。

参考文章:
秒懂，Java 注解（Annotation）你可以这样学