注解概述

什么是注解

什么是注解（Annotation）？注解是放在Java源码的类、方法、字段、参数前的一种用作标注的“元数据”。

注解的作用

从JVM的角度看，注解本身对代码逻辑没有任何影响，如何使用注解完全由工具决定。
Java的注解可以分为三类：
第一类是由编译器使用的注解，例如：

  • @Override：让编译器检查该方法是否正确地实现了覆写；
  • @SuppressWarnings：告诉编译器忽略此处代码产生的警告。

这类注解不会被编译进入.class文件，它们在编译后就被编译器扔掉了。

第二类是由工具处理.class文件使用的注解，比如有些工具会在加载class的时候，对class做动态修改，实现一些特殊的功能。这类注解会被编译进入.class文件，但加载结束后并不会存在于内存中。这类注解只被一些底层库使用，一般我们不必自己处理。

第三类是在程序运行期能够读取的注解，它们在加载后一直存在于JVM中，这也是最常用的注解。例如，一个配置了@PostConstruct的方法会在调用构造方法后自动被调用（这是Java代码读取该注解实现的功能，JVM并不会识别该注解）。

定义注解

Java语言使用@interface语法来定义注解（Annotation），它的格式如下：

  1. public @interface Report {
  2.     int type() default 0;
  3.     String level() default "info";
  4.     String value() default "";
  5. }

注解的参数类似无参数方法，可以用default设定一个默认值（强烈推荐）。最常用的参数应当命名为value。

注解的参数

定义一个注解时，还可以定义配置参数。配置参数可以包括：

  • 所有基本类型；
  • String；
  • 枚举类型；
  • 基本类型、String、Class以及枚举的数组。

因为配置参数必须是常量，所以，上述限制保证了注解在定义时就已经确定了每个参数的值。
注解的配置参数可以有默认值，缺少某个配置参数时将使用默认值。
此外，大部分注解会有一个名为value的配置参数，对此参数赋值，可以只写常量，相当于省略了value参数。如果只写注解，相当于全部使用默认值。

举个栗子，对以下代码：

  1. public class Hello {
  2.     @Check(min=0, max=100, value=55)
  3.     public int n;
  5.     @Check(value=99)
  6.     public int p;
  8.     @Check(99) // @Check(value=99)
  9.     public int x;
  11.     @Check
  12.     public int y;
  13. }

@Check就是一个注解。第一个@Check(min=0, max=100, value=55)明确定义了三个参数，第二个@Check(value=99)只定义了一个value参数，它实际上和@Check(99)是完全一样的。最后一个@Check表示所有参数都使用默认值。

元注解

有一些注解可以修饰其他注解，这些注解就称为元注解（meta annotation）。Java标准库已经定义了一些元注解，我们只需要使用元注解，通常不需要自己去编写元注解。

@Target

最常用的元注解是@Target。使用@Target可以定义Annotation能够被应用于源码的哪些位置：

  • 类或接口：ElementType.TYPE；
  • 字段：ElementType.FIELD；
  • 方法：ElementType.METHOD；
  • 构造方法：ElementType.CONSTRUCTOR；
  • 方法参数：ElementType.PARAMETER。

例如，定义注解@Report可用在方法上，我们必须添加一个@Target(ElementType.METHOD):

  1. @Target(ElementType.METHOD)
  2. public @interface Report {
  3.     int type() default 0;
  4.     String level() default "info";
  5.     String value() default "";
  6. }

定义注解@Report可用在方法或字段上，可以把@Target注解参数变为数组{ ElementType.METHOD, ElementType.FIELD }：

  1. @Target({
  2.     ElementType.METHOD,
  3.     ElementType.FIELD
  4. })
  5. public @interface Report {
  6.     ...
  7. }

实际上@Target定义的value是ElementType[]数组，只有一个元素时，可以省略数组的写法。

@Retention

另一个重要的元注解@Retention定义了Annotation的生命周期：

  • 仅编译期：RetentionPolicy.SOURCE；
  • 仅class文件：RetentionPolicy.CLASS；
  • 运行期：RetentionPolicy.RUNTIME。

如果@Retention不存在，则该Annotation默认为CLASS。因为通常我们自定义的Annotation都是RUNTIME，所以，务必要加上@Retention(RetentionPolicy.RUNTIME)这个元注解：

  1. @Retention(RetentionPolicy.RUNTIME)
  2. public @interface Report {
  3.     int type() default 0;
  4.     String level() default "info";
  5.     String value() default "";
  6. }

@Repeatable

使用@Repeatable这个元注解可以定义Annotation是否可重复。这个注解应用不是特别广泛。

  1. @Repeatable(Reports.class)
  2. @Target(ElementType.TYPE)
  3. public @interface Report {
  4.     int type() default 0;
  5.     String level() default "info";
  6.     String value() default "";
  7. }
  9. @Target(ElementType.TYPE)
  10. public @interface Reports {
  11.     Report[] value();
  12. }

经过@Repeatable修饰后，在某个类型声明处，就可以添加多个@Report注解：

  1. @Report(type=1, level="debug")
  2. @Report(type=2, level="warning")
  3. public class Hello {
  4. }

@Inherited

使用@Inherited定义子类是否可继承父类定义的Annotation。@Inherited仅针对@Target(ElementType.TYPE)类型的annotation有效，并且仅针对class的继承，对interface的继承无效：

  1. @Inherited
  2. @Target(ElementType.TYPE)
  3. public @interface Report {
  4.     int type() default 0;
  5.     String level() default "info";
  6.     String value() default "";
  7. }

在使用的时候，如果一个类用到了@Report：

  1. @Report(type=1)
  2. public class Person {
  3. }

则它的子类默认也定义了该注解：

  1. public class Student extends Person {
  2. }

如何定义Annotation

我们总结一下定义Annotation的步骤：
第一步，用@interface定义注解：

  1. public @interface Report { }

第二步，添加参数、默认值：

  1. public @interface Report {
  2.     int type() default 0;
  3.     String level() default "info";
  4.     String value() default "";
  5. }

把最常用的参数定义为value()，推荐所有参数都尽量设置默认值。
第三步，用元注解配置注解：

  1. @Target(ElementType.TYPE)
  2. @Retention(RetentionPolicy.RUNTIME)
  3. public @interface Report {
  4.     int type() default 0;
  5.     String level() default "info";
  6.     String value() default "";
  7. }

其中，必须设置@Target和@Retention，@Retention一般设置为RUNTIME，因为我们自定义的注解通常要求在运行期读取。一般情况下，不必写@Inherited和@Repeatable。

处理注解

如何使用注解完全由工具决定。SOURCE类型的注解主要由编译器使用，因此我们一般只使用，不编写。CLASS类型的注解主要由底层工具库使用，涉及到class的加载，一般我们很少用到。只有RUNTIME类型的注解不但要使用，还经常需要编写。以下示例如何读取RUNTIME类型的注解。

因为注解定义后也是一种class，所有的注解都继承自java.lang.annotation.Annotation，因此，读取注解，需要使用反射API。

Java提供的使用反射API读取Annotation的方法包括：

  1. 判断某个注解是否存在于Class、Field、Method或Constructor：
  • Class.isAnnotationPresent(Class)
  • Field.isAnnotationPresent(Class)
  • Method.isAnnotationPresent(Class)
  • Constructor.isAnnotationPresent(Class)
  1. 使用反射API读取Annotation：
  • Class.getAnnotation(Class)
  • Field.getAnnotation(Class)
  • Method.getAnnotation(Class)
  • Constructor.getAnnotation(Class)

读取Class的注解：

  1. //Class cls = Person.class;
  2. //if (cls.isAnnotationPresent(Report.class)) {
  3. //    Report report = cls.getAnnotation(Report.class);
  4. //    ...
  5. //}
  7. Class cls = Person.class;
  8. Report report = cls.getAnnotation(Report.class);
  9. if (report != null) {
  10.    ...
  11. }

读取方法、字段和构造方法的Annotation和Class类似。但要读取方法参数的Annotation就比较麻烦一点，因为方法参数本身可以看成一个数组，而每个参数又可以定义多个注解，所以，一次获取方法参数的所有注解就必须用一个二维数组来表示。例如，对于以下方法定义的注解：

  1. // 获取Method实例:
  2. Method m = ...
  3. // 获取所有参数的Annotation:
  4. Annotation[][] annos = m.getParameterAnnotations();
  5. // 第一个参数（索引为0）的所有Annotation:
  6. Annotation[] annosOfName = annos[0];
  7. for (Annotation anno : annosOfName) {
  8.     if (anno instanceof Range) { // @Range注解
  9.         Range r = (Range) anno;
  10.     }
  11.     if (anno instanceof NotNull) { // @NotNull注解
  12.         NotNull n = (NotNull) anno;
  13.     }
  14. }

测试

定义注解：

  1. package com.hanliukui.annotationtest;
  3. import java.lang.annotation.ElementType;
  4. import java.lang.annotation.Retention;
  5. import java.lang.annotation.RetentionPolicy;
  6. import java.lang.annotation.Target;
  8. /**
  9.  * @Author hanliukui
  10.  * @Date 2022/5/5 17:04
  11.  * @Description xxx
  12.  */
  13. @Target(ElementType.TYPE)
  14. @Retention(RetentionPolicy.RUNTIME)
  15. public @interface ClassAnnotation {
  16.     String value() default "";
  17. }
  1. package com.hanliukui.annotationtest;
  3. import java.lang.annotation.ElementType;
  4. import java.lang.annotation.Retention;
  5. import java.lang.annotation.RetentionPolicy;
  6. import java.lang.annotation.Target;
  8. /**
  9.  * @Author hanliukui
  10.  * @Date 2022/5/5 16:43
  11.  * @Description xxx
  12.  */
  13. @Target(ElementType.FIELD)
  14. @Retention(RetentionPolicy.RUNTIME)
  15. public @interface FieldAnnotation {
  17.     int min() default 1;
  19.     int max() default 999;
  21. }
  1. package com.hanliukui.annotationtest;
  3. import java.lang.annotation.ElementType;
  4. import java.lang.annotation.Retention;
  5. import java.lang.annotation.RetentionPolicy;
  6. import java.lang.annotation.Target;
  8. /**
  9.  * @Author hanliukui
  10.  * @Date 2022/5/5 17:04
  11.  * @Description xxx
  12.  */
  13. @Target(ElementType.PARAMETER)
  14. @Retention(RetentionPolicy.RUNTIME)
  15. public @interface ParamAnnotationNotNull {
  16.     boolean value() default false;
  17. }

在类上使用注解：

  1. package com.hanliukui.annotationtest;
  3. /**
  4.  * @Author hanliukui
  5.  * @Date 2022/5/5 16:58
  6.  * @Description xxx
  7.  */
  8. @ClassAnnotation("aaa")
  9. public class AppInfo {
  11.     @FieldAnnotation(min = 3,max = 888)
  12.     private Integer price;
  14.     AppInfo(Integer price){
  15.         this.price = price;
  16.     }
  18.     public void sale(@ParamAnnotationNotNull(value = true) String username){
  19.         System.out.println(username+"1111");
  20.     }
  23. }

测试：

  1. package com.hanliukui.annotationtest;
  3. import java.lang.annotation.Annotation;
  4. import java.lang.reflect.Field;
  5. import java.lang.reflect.Method;
  7. /**
  8.  * @Author hanliukui
  9.  * @Date 2022/5/5 16:43
  10.  * @Description xxx
  11.  */
  12. public class AnnotationTest {
  13.     public static void main(String[] args) {
  15.         AppInfo appInfo = new AppInfo(20);
  17.         Class<? extends AppInfo> aClass = appInfo.getClass();
  18.         Field[] fields = aClass.getDeclaredFields();
  20.         for (Field f:fields){
  21.             FieldAnnotation fieldAnnotation = f.getAnnotation(FieldAnnotation.class);
  22.             if (fieldAnnotation !=null){
  23.                 int max = fieldAnnotation.max();
  24.                 int min = fieldAnnotation.min();
  25.                 System.out.println("max="+max);
  26.                 System.out.println("min="+min);
  27.             }
  28.         }
  30.         ClassAnnotation classAnnotation = aClass.getAnnotation(ClassAnnotation.class);
  31.         System.out.println(classAnnotation.value());
  33.         Method[] methods = aClass.getDeclaredMethods();
  34.         for (Method method:methods){
  35.             Annotation[][] parameterAnnotations = method.getParameterAnnotations();
  36.             for (Annotation[] annotations:parameterAnnotations){
  37.                 for (Annotation annotation:annotations){
  38.                     if (annotation instanceof ParamAnnotationNotNull){
  39.                         ParamAnnotationNotNull annotationNotNull = (ParamAnnotationNotNull) annotation;
  40.                         System.out.println(annotationNotNull.value());
  41.                     }
  42.                 }
  43.             }
  44.         }
  45.     }
  46. }
  48. // max=888
  49. // min=3
  50. // aaa
  51. // true