java 注解理解与开发

注解？

Java 注解（Annotation）又称 Java 标注，是 JDK5.0 引入的一种注释机制。
注解可以理解为元数据，即一种描述数据的数据。所以，可以说注解就是源代码的元数据。
Annotation是一种应用于类、方法、参数、变量、构造器及包声明中的特殊修饰符。它是一种由JSR-175标准选择用来描述元数据的一种工具。

为什么用

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

注解架构

1 个 Annotation 和 1 个 RetentionPolicy 关联。
1 个 Annotation 和 1~n 个 ElementType 关联。
Annotation 有许多实现类，包括：Deprecated, Documented, Inherited, Override 等等。

Annotation 组成部分

Annotation.java

package java.lang.annotation;

public interface Annotation {
    
    boolean equals(Object obj);

    int hashCode();

    String toString();

    Class<? extends Annotation> annotationType();
}

Annotation 就是个接口。

ElementType.java

package java.lang.annotation;

public enum ElementType {
    TYPE,           // 类、接口（包括注释类型）或枚举声明
    FIELD,          // 字段声明（包括枚举常量）
    METHOD,         // 方法声明
    PARAMETER,      // 形式参数声明
    CONSTRUCTOR,    // 构造函数声明
    LOCAL_VARIABLE, //  局部变量声明
    ANNOTATION_TYPE,//  批注类型声明
    PACKAGE,        //包装声明
    TYPE_PARAMETER, // 类型参数声明
    TYPE_USE        // 类型的使用
}

ElementType 是 Enum 枚举类型，它用来指定 Annotation 的类型。

RetentionPolicy.java

package java.lang.annotation;

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

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

Type	作用域
SOURCE	编译器处理期间有效
CLASS	在class文件有效，有可能被jvm忽略
RUNTIME	在运行时有效

语法定义

@Documented
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation {}

上面定义了一个名为MyAnnotation的Annotation(注解),
我们可以在代码中通过@MyAnnotation来使用它

@interface
- 使用 @interface 定义注解时，意味着它实现了 java.lang.annotation.Annotation 接口，即该注解就是一个Annotation。
- 定义 Annotation 时，@interface 是必须的。
- Annotation 接口的实现细节都由编译器完成。通过 @interface 定义注解后，该注解不能继承其他的注解或接口。
@Documented
- 类和方法的 Annotation 在缺省情况下是不出现在 javadoc 中的。
- 如果使用 @Documented 修饰该 Annotation,则表示它可以出现在 javadoc 中。
- 定义 Annotation 时，@Documented 可有可无；若没有定义，则 Annotation 不会出现在 javadoc 中。
@Target(ElementType.TYPE)
- 就是来指定 Annotation 的类型属性。
- 定义 Annotation 时，@Target 可有可无。
- 若有 @Target，则该 Annotation 只能用于它所指定的地方；
- 若无 @Target，则该 Annotation 可以用于任何地方。
@Retention(RetentionPolicy.RUNTIME)
- 就是指定 Annotation 的策略属性。
- 定义 Annotation 时，@Retention 可有可无。
- 若无 @Retention，则默认是 RetentionPolicy.CLASS。

内置注解

注解	所在包	作用
@Override	java.lang	检查该方法是否是重写方法。如果发现其父类，或者是引用的接口中并没有该方法时，会报编译错误
@Deprecated	java.lang	标记过时方法。如果使用该方法，会报编译警告
@SuppressWarnings	java.lang	指示编译器去忽略注解中声明的警告
@SafeVarargs	java.lang	忽略任何使用参数为泛型变量的方法或构造函数调用产生的警告
@FunctionalInterface	java.lang	标识一个匿名函数或函数式接口
@Retention	java.lang.annotation	标识这个注解怎么保存，是只在代码中，还是编入class文件中，或者是在运行时可以通过反射访问。
@Documented	java.lang.annotation	标记这些注解是否包含在用户文档中
@Target	java.lang.annotation	标记这个注解应该是哪种 Java 成员
@Inherited	java.lang.annotation	标记这个注解是继承于哪个注解类(默认注解并没有继承于任何子类)
@Repeatable	java.lang.annotation	标识某注解可以在同一个声明上使用多次

@Deprecated
1
2
3
4
5
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
public @interface Deprecated {
}
@interface 修饰 Deprecated 证明 Deprecated 实现了java.lang.annotation.Annotation 接口，Deprecated 为一个接口
@Documented 修饰该注解说明注解能出现在 javadoc 中。
@Retention(RetentionPolicy.RUNTIME) 中，RUNTIME说明编译器会将Deprecated 的信息保留在 .class 文件中，并且能被虚拟机读取。
@Deprecated 所标注内容，不再被建议使用。
@Inherited
1
2
3
4
5
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Inherited {
}
@interface 修饰 Inherited，意味着 Inherited 实现了 java.lang.annotation.Annotation 接口
@Documented 修饰该注解说明注解能出现在 javadoc 中。
@Retention(RetentionPolicy.RUNTIME) 中，RUNTIME说明编译器会将Deprecated 的信息保留在 .class 文件中，并且能被虚拟机读取。
@Target(ElementType.ANNOTATION_TYPE)中,ANNOTATION_TYPE 说明 @Inherited 只能被用来标注 “Annotation 类型”。
@Inherited 的含义是，它所标注的Annotation将具有继承性。

@SuppressWarnings

@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
    String[] value();
}

@interface修饰 SuppressWarnings，意味着 SuppressWarnings 实现了 java.lang.annotation.Annotation 接口
@Retention(RetentionPolicy.SOURCE)中SOURCE。这就意味着，SuppressWarnings 信息仅存在于编译器处理期间，编译器处理完之后 SuppressWarnings 就没有作用了。
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})

TYPE 意味着，它能标注”类、接口（包括注释类型）或枚举声明”。
FIELD 意味着，它能标注”字段声明”。
METHOD 意味着，它能标注”方法”。
PARAMETER 意味着，它能标注”参数”。
CONSTRUCTOR 意味着，它能标注”构造方法”。
LOCAL_VARIABLE 意味着，它能标注”局部变量”。

String[] value(); 意味着，SuppressWarnings 能指定参数

参数用途

deprecation 使用了不赞成使用的类或方法时的警告

unchecked 执行了未检查的转换时的警告，例如当使用集合时没有用泛型 (Generics) 来指定集合保存的类型。

fallthrough 当 Switch 程序块直接通往下一种情况而没有 Break 时的警告。

path 在类路径、源文件路径等中有不存在的路径时的警告。

serial 当在可序列化的类上缺少 serialVersionUID 定义时的警告。

finally 任何 finally 子句不能正常完成时的警告。

all 关于以上所有情况的警告。

SuppressWarnings 的作用是，让编译器对”它所标注的内容”的某些警告保持静默。

参数	用途
deprecation	使用了不赞成使用的类或方法时的警告
unchecked	执行了未检查的转换时的警告，例如当使用集合时没有用泛型 (Generics) 来指定集合保存的类型。
fallthrough	当 Switch 程序块直接通往下一种情况而没有 Break 时的警告。
path	在类路径、源文件路径等中有不存在的路径时的警告。
serial	当在可序列化的类上缺少 serialVersionUID 定义时的警告。
finally	任何 finally 子句不能正常完成时的警告。
all	关于以上所有情况的警告。

用例:

import java.util.Date;
public class SuppressWarningTest {

    @SuppressWarnings(value={"deprecation"})
    public static void doSomething(){
        Date date = new Date(113, 8, 26);
        System.out.println(date);
   }
}

基本用途

编译检查

@SuppressWarnings, @Deprecated 和 @Override 都具有编译检查作用。

反射

声明注解

/**
 * Annotation在反射函数中的使用示例
 */
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String[] value() default "unknown";
}

构建一个类

/**
 * Person类。它会使用MyAnnotation注解。
 */
class Person {

  /**
   * empty()方法同时被 "@Deprecated" 和 "@MyAnnotation(value={"a","b"})"所标注
   * (01) @Deprecated，意味着empty()方法，不再被建议使用
   * (02) @MyAnnotation, 意味着empty() 方法对应的MyAnnotation的value值是默认值"unknown"
   */
  @MyAnnotation
  @Deprecated
  public void empty() {
    System.out.println("\n调用方法 Person.empty()");
  }

  /**
   * sombody() 被 @MyAnnotation(value={"girl","boy"}) 所标注，
   *
   * @MyAnnotation(value={"girl","boy"}), 意味着MyAnnotation的value值是{"girl","boy"}
   */
  @MyAnnotation(value = {"111", "222", "333"})
  public void somebody(String name, int age) {
    System.out.println("\n调用方法 Person.somebody(String name, int age): " + name + ", " + age);
  }
}

反射调用拿到注解的值

public class AnnotationTest {

    public static void main(String[] args) throws Exception {

        // 新建Person
        Person person = new Person();
        // 获取Person的Class实例
        Class<Person> c = Person.class;
        // 获取 somebody() 方法的Method实例
        Method mSomebody = c.getMethod("somebody", new Class[]{String.class, int.class});
        // 执行该方法
        mSomebody.invoke(person, new Object[]{"wx", 20});
        iteratorAnnotations(mSomebody);
        
        System.out.println("\n================");

        // 获取 somebody() 方法的Method实例
        Method mEmpty = c.getMethod("empty", new Class[]{});
        // 执行该方法
        mEmpty.invoke(person, new Object[]{});
        iteratorAnnotations(mEmpty);
    }

    public static void iteratorAnnotations(Method method) {
        // 判断 somebody() 方法是否包含MyAnnotation注解
        if (method.isAnnotationPresent(MyAnnotation.class)) {
            // 获取该方法的MyAnnotation注解实例
            MyAnnotation myAnnotation = method.getAnnotation(MyAnnotation.class);
            // 获取 myAnnotation的值，并打印出来
            String[] values = myAnnotation.value();
            System.out.print("反射得到的方法上的注解所包含的值：");
            for (String str : values)
                System.out.printf(str + ", ");
            System.out.println();
        }
        // 获取方法上的所有注解，并打印出来
        Annotation[] annotations = method.getAnnotations();
        System.out.print("反射得到的方法上的所有注解：");
        for (Annotation annotation : annotations) {
            System.out.print(annotation + ",");
        }
    }
}

结果:

调用方法 Person.somebody(String name, int age): wx, 20
反射得到的方法上的注解所包含的值：111, 222, 333, 
反射得到的方法上的所有注解：@MyAnnotation(value=[111, 222, 333]),
================
调用方法 Person.empty()
反射得到的方法上的注解所包含的值：unknown, 
反射得到的方法上的所有注解：@MyAnnotation(value=[unknown]),@java.lang.Deprecated(),

生成帮助文档

通过给 Annotation 注解加上 @Documented 标签，能使该 Annotation 标签出现在 javadoc 中。

帮忙查看查看代码

通过 @Override, @Deprecated 等，我们能很方便的了解程序的大致结构。

进阶

我们还可以这样声明一个注解

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface myUser {
    String name() default "";
    int age();
    int id () default -1;
    String[] list() default {"list1","list2"};
 }

public class Test {
    
    @myUser(name = "test",age = 20,id = 01,list = {"1","2"})
    public void test(){}

}

感谢查阅

洛玖随笔

【Java注解】如何理解和使用 Java注解

注解？