关于Java注解（annotation）的简单理解

一、什么是注解？

　　从 JDK5 开始，Java增加对元数据的支持，也就是注解。简单理解就是代码里的特殊标志，这些标志可以在编译，类加载，运行时被读取，并执行相应的处理，以便于其他工具补充信息或者进行部署。

二、为什么要使用注解？

　　注解可以被其他程序（比如：编译器等）读取，开发人员可以在不改变原有代码和逻辑的情况下在源代码中嵌入补充信息。

三、注解的相关概述

3.1 注解的格式

　　注解就是以 @XXX 形式在代码中存在的，我们还可以为注解添加一些参数值，例如  @SuppressWarnings(value = "unchecked") 。

3.2 元注解

　　元注解就是负责注解其它注解的注解。

　　下图为Java定义的标准的 元注解类型，他们用来对其他的注解进行说明，可以在 Java API 的 java.lang.annotation 包中找到。

　　

3.2.1 @Document

官方示例：

// since 1.5
@Documented
@Retention(RUNTIME)
@Target(ANNOTATION_TYPE)
public @interface Documented

官方描述：

• 如果注释@Documented出现在注释类型A的声明中，那么元素上的任何@A注释都被认为是元素公共契约的一部分。
• 更详细地说，当使用Documented对注释类型A进行注释时，类型A的注释的存在和值是A注释的元素的公共契约的一部分。相反，如果注释类型B没有被文档化注释，那么B注释的存在和值就不是B注释元素的公共契约的一部分。
• 具体地说，如果注释类型是用Documented注释的，那么默认情况下，像javadoc这样的工具将在其输出中显示该类型的注释，而没有Documented的注释类型的注释将不会显示。

间而言之：

　　如果使用了 @Documented ，就说明此类（或方法、字段等）的文档化注释就会被包含在JavaDoc中。

3.2.2 @Inherited

官方示例：

// since 1.5
@Documented
@Retention(RUNTIME)
@Target(ANNOTATION_TYPE)
public @interface Inherited

官方描述：

• 指示自动继承批注类型。
• 如果在注释类型声明上存在继承的元注释，并且用户在类声明上查询注释类型，而该类声明对此类型没有注释，则将自动在类的超类中查询注释类型。将重复此过程，直到找到此类型的注释，或到达类层次结构（对象）的顶部。
  如果没有超类具有此类型的注释，则查询将指示所讨论的类没有此类注释。
• 请注意，如果注释类型用于注释类以外的任何内容，则此元注释类型无效。还要注意，这个元注释只会导致注释从超类继承；对实现接口的注释没有影响。

简而言之：

　　子类可以继承父类（超类）中的该注解。这个注解指定被他修饰的注解将具有继承性——如果某个类使用了@XXX，则其子类将自动被@XXX修饰

代码示例：

public class test2 {

    public static void main(String[] args) {
        Person person = new Person();
        Student student = new Student();

        Annotation[] parentAnnotation = person.getClass().getAnnotations();
        Annotation[] studentAnnotation = student.getClass().getAnnotations();
        for (Annotation annotation : parentAnnotation) {
            System.out.println(annotation);
        }
        System.out.println("---------------------");
        for (Annotation annotation : studentAnnotation) {
            System.out.println(annotation);
        }

        // 输出结果
//        @com.ruiyicloud.bbfbusiness.demo.annotation.MyAnnotation3()
//        ---------------------
//        @com.ruiyicloud.bbfbusiness.demo.annotation.MyAnnotation3()

    }


}

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@interface MyAnnotation3{

}
@MyAnnotation3
class Person{
    String name;
}

class Student extends Person{
    int age;
}

注意：

　　如果 MyAnnotation3 注解 去掉 @Inherited，则student.getClass().getAnnotations() 将输入空。

3.2.3 @Native

官方代码：

// since 1.8
@Documented
@Target(FIELD)
@Retention(SOURCE)
public @interface Native

官方描述：

　　指示定义常量值的字段可以从本机代码引用。生成本机头文件的工具可以使用该注释作为提示，以确定是否需要头文件，如果需要，还应该包含哪些声明。

间而言之：

　　Navtive是指一些变量和平台相关的linux系统和window操作系统的本地文件头。　　

　　使用本地方法，我们可以用java与底层系统的交互，如果使用Java获取不到我们想要的内容，我们可以选择使用本地方法。

　　使用 @Native 注解修饰变量值的字段，则表示这个变量可以被本地代码引用。

代码示例：

　　附上Integer的部分源码

public final class Integer extends Number
        implements Comparable<Integer>, Constable, ConstantDesc {
    /**
     * A constant holding the minimum value an {@code int} can
     * have, -2<sup>31</sup>.
     */
    @Native public static final int   MIN_VALUE = 0x80000000;



　　// 比较值的大小
    public static int compareUnsigned(int x, int y) {
        return compare(x + MIN_VALUE, y + MIN_VALUE);
    }

3.2.4  @Repeatable

官方代码：

// since 1.8
@Documented
@Retention(RUNTIME)
@Target(ANNOTATION_TYPE)
public @interface Repeatable

官方描述：

　　注释类型java.lang.annotation注释.Repeatable用于指示它（meta-）注释其声明的注释类型是可重复的。@Repeatable的值表示可重复注释类型的包含注释类型。

间而言之：

　　使用@Repeatable这个声明的注解是可重复的。@Repeatable的值是另一个注解，其可以通过这个另一个注解的值来包含这个可重复的注解。

代码示例：

　　FooContainer 作用于范围只能在注解类型上，所以作用于接口上时会报错

import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Target;

public class test03 {

}


@Target({ElementType.TYPE,ElementType.ANNOTATION_TYPE})
@Repeatable(FooContainer.class)
@interface Foo {}

@Target(ElementType.ANNOTATION_TYPE)
@interface FooContainer {
    Foo[] value();
}

//正确的
@Foo @Foo
@interface FooContainer1 {
    Foo[] value();
}

// 错误的
@Foo @Foo
interface aa {
    
}

注意事项：

• Foo的保留时间至少与FooContainer一样长，其中保留用@Retention 注释显式或隐式表示。特别：
• 如果Foo的保留为java.lang.annotation.RetentionPolicy.SOURCE，则FooContainer的保留为java.lang.annotation.RetentionPolicy.SOURCE。
• 如果Foo的保留值为java.lang.annotation.RetentionPolicy.CLASS，则FooContainer的保留值为java.lang.annotation.RetentionPolicy.CLASS或 java.lang.annotation.RetentionPolicy.SOURCE。
• 如果保留Foo是java.lang.annotation.RetentionPolicy.RUNTIME，则保留FooContainer是java.lang.annotation.RetentionPolicy.SOURCE， java.lang.annotation.RetentionPolicy.CLASS，或java.lang.annotation.RetentionPolicy.RUNTIME。

3.2.5 @Retention

官方示例：

// since 1.5
@Documented
@Retention(RUNTIME)
@Target(ANNOTATION_TYPE)
public @interface Retention

官方描述：

• 指示带批注类型的批注要保留多长时间。如果批注类型声明上不存在保留批注，则保留策略默认为保留策略.CLASS.
• 只有当元注释类型直接用于注释时，保留元注释才有效。如果元注释类型被用作另一个注释类型中的成员类型，则没有效果。

枚举常量

枚举常量	描述
CLASS	枚举常量将由编译器记录在类文件中，但不需要在运行时由VM保留.
RUNTIME	注释将由编译器记录在类文件中，并在运行时由VM保留，因此可以反射地读取它们.
SOURCE	注释将被编译器丢弃.

间而言之：

　　此注解主要作用为在什么级别保存该注解信息，用于描述注解的声明周期，需要主要的是 SOURCE < CLASS < RUNTIME 。

3.2.6 @Target

官方示例：

// since 1.5
@Documented
@Retention(RUNTIME)
@Target(ANNOTATION_TYPE)
public @interface Target

官方描述：

• 指示批注类型适用的上下文。JLS 9.6.4.1中指定了可应用注释类型的声明上下文和类型上下文，并在源代码中用java.lang.annotation注释.ElementType。
• 如果@Target元注释不存在于注释类型T上，那么类型T的注释可以作为除类型参数声明之外的任何声明的修饰符来编写。
• 如果存在@Target元注释，编译器将根据JLS 9.7.4强制执行由ElementType enum常量指示的使用限制。

简而言之：

　　@Target注解主要用于描述注解的使用范围（例如，添加某些属性的时候注解可以使用在类上，添加某些属性的时候注解可以使用在方法上等）

3.3 注解的使用范围？

ElementType枚举常量	作用范围
TYPE	类、接口（包括注释类型）、枚举或记录
FIELD	字段声明（包括枚举常量）
METHOD	方法声明
PARAMETER	形式参数声明
CONSTRUCTOR	构造函数声明
LOCAL_VARIABLE	局部变量声明
ANNOTATION_TYPE	注解类型声明
PACKAGE	包声明
TYPE_PARAMETER	类型参数声明（since 8）
TYPE_USE	类型的使用（since 8）
MODULE	模块声明 （since 9）
RECORD_COMPONENT	Java语言的一种预览功能（since 14）

 

 

3.4 常用的几个注解

@Override :

　　限定父类重写方法，当子类重写父类方法时，子类可以加上这个注解，可以确保子类确实重写了父类的方法，避免出现低级错误。

@FunctionalInterface:

　　函数式接口，注解保证这个接口只有一个抽象方法，注意这个只能修饰接口。（函数式接口是指 接口中只有一个抽象方法（可以包含多个默认方法或多个static方法），接口体内只能声明常量字段和抽象方法，并且被隐式声明为public，static，final。接口里面不能有私有的方法或变量。）

@Deprecated:

　　标示已过时，这个注解用于表示某个程序元素类，方法等已过时，当其他程序使用已过时的类，方法时编译器会给出警告。

@SuppressWarning: 

 　　抑制编译器警告，被该注解修饰的元素以及该元素的所有子元素取消显示编译器警告。

四、自定义注解实战

　　本例创建一个简单的注解，并在方法上、类上进行使用

@MyAnnotation
public class Main {
    @MyAnnotation
    public static void main(String[] args) {

    }
}

// Target 标识注解可以在什么地方使用
@Target({ElementType.METHOD,ElementType.TYPE})
// 标识此注解在什么地方还有效
@Retention(RetentionPolicy.RUNTIME)
// 标识是否将我们的注解生成在JavaDoc中
@Documented
// 子类可以继承父类的注解
@Inherited
@interface MyAnnotation{

}

五、总结

　　总的来说，注解还是比较简单的。