Java 注解

本小节我们将学习 Java5 引入的一种机制 —— 注解（Annotation）。通过本小节的学习，你将了解什么是注解，注解的作用，Java 中内置注解有哪些以及注解的分类，如何自定义注解，如何处理注解等内容。

1. 什么是注解

Java 注解（Annotation）又称为 Java 标注，是 Java5开始支持加入源代码的特殊语法元数据。Java 语言中的类、方法、变量、参数和包等都可以被标注。Java 标注可以通过反射获取标注的内容。在编译器生成class文件时，标注可以被嵌入到字节码中。Java 虚拟机可以保留标注内容，在运行时可以获取到标注内容。

注解是一种用于做标注的“元数据”，什么意思呢？你可以将注解理解为一个标签，这个标签可以标记类、方法、变量、参数和包。

回想我们学习继承时，子类若重写了父类的方法，可以在子类重写的方法上使用@Override注解：

将@Override 注解标注在子类重写的方法上，可检查该方法是否正确地重写了父类的方法，如有错误将会编译报错。

2. 注解的作用

2.1 内置的注解

我们先看一下 Java 提供了哪些内置注解，以及这些注解的作用。（大致了解即可）

Java 定义了一套注解，共有 10 个，5 个在 java.lang 包中，剩下 5 个在 java.lang.annotation 包中。

2.1.1 用在代码的注解

• @Override：检查该方法是否正确地重写了父类的方法。如果重写错误，会报编译错误；

• @Deprecated：标记过时方法。如果使用该方法，会报编译警告；

• @SuppressWarnings：指示编译器去忽略注解中声明的警告；

• @SafeVarargs：Java 7 开始支持，忽略任何使用参数为泛型变量的方法或构造函数调用产生的警告；

• @FunctionalInterface：Java 8 开始支持，标识一个匿名函数或函数式接口。

2.1.2 用在其他注解的注解

此类注解也称为元注解（meta annotation），在下面学习定义注解的时候，我们将会详细讲解。

• @Retention：标识这个注解怎么保存，是只在代码中，还是编入class文件中，或者是在运行时可以通过反射访问；

• @Documented：标记这些注解是否包含在用户文档中；

• @Target：标记这个注解应该是哪种 Java 成员；

• @Inherited：标记这个注解是继承于哪个注解类；

• @Repeatable：Java 8 开始支持，标识某注解可以在同一个声明上使用多次。

2.2 分类

Java 注解可以分为 3 类：

1. 由编译器使用的注解：如@Override、@Deprecated、@SupressWarnings等；

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

3. 在程序运行期间能够读取的注解：它们在加载后一直存在于JVM中，这也是最常用的注解。

3. 定义注解

学会使用注解非常简单，很多框架都会提供丰富的注解文档（例如 Spring）。但关键的一点在于定义注解，知道如何定义注解，才能看懂别人定义的注解。

下面我们来定义一个注解。

想要定义一个注解，通常可分为 3 步：

1. 创建注解；

2. 定义注解的参数和默认值；

3. 用元注解配置注解。

关于这 3 个步骤是什么意思，如何来做，我们下面将来详细讲解。

3.1 创建注解

注解通过@interface关键字来定义。例如，我们想要定义一个可用于检查字符串长度的注解，实例如下：

public @interface Length {
  
}

Tips：通过 @interface 关键字定义注解，通过关键字 interface定义接口。注意两者不要混淆。

在IDEA中，我们可以在新建 Java 类的时候，选择新建注解：

输入我们要定义的注解的名称（遵循类命名规范），即可创建一个注解：

3.2 定义参数和默认值

注解创建完成后，可以向注解添加一些要接收的参数，下面我们为@Length注解添加 3 个参数：

public @interface Length {

    int min() default 0;

    int max() default Integer.MAX_VALUE;

    String message() default "长度不合法";
    
}

注解的参数类似无参数方法。另外参数的类型可以是基本数据类型、String类型、枚举类型、Class类型、Annotation类型以及这些类型的数组。

如果注解中只有一个参数，或者这个参数是最常用的参数，那么应将此参数命名为value。在调用注解时，如果参数名称是value，且只有一个参数，那么可以省略参数名称。（由于此注解没有最常用特征的参数，没有使用value）

可以使用default关键字来指定参数的默认值，推荐为每个参数都设定一个默认值。

3.3 用元注解配置注解

在前面学习 Java 内置的注解的时候，我们已经了解了元注解，元注解就是用于修饰其他注解的注解。

通常只需使用这些内置元注解，就可以基本满足我们自定义注解的需求。下面我们将会详解 Java 内置的 5 个元注解，你将会了解为什么需要这些元注解。

3.3.1 @Retention

Retention译为保留。@Retention注解定义了一个注解的生命周期（我们前面对于 Java 注解的分类，就是通过其生命周期来划定界限的）。它可以有如下几种取值：

• RetentionPolicy.SOURCE：注解只在源码阶段保留，在编译器进行编译时它将被丢弃忽视；

• RetentionPolicy.CLASS：注解只被保留到编译进行的时候，它并不会被加载到 JVM 中；

• RetentionPolicy.RUNTIME：注解可以保留到程序运行的时候，它会被加载进入到 JVM 中，所以在程序运行时可以获取到它们。

下面我们使用@Retention注解来指定我们自定义的注解@Length的生命周期，实例如下：

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

@Retention(RetentionPolicy.RUNTIME)
public @interface Length {

    int min() default 0;

    int max() default Integer.MAX_VALUE;

    String message() default "长度不合法";

}

上面的代码中，我们指定 @Length 注解可以在程序运行期间被获取到。

3.3.2 @Documented

这个元注解的作用很简单，标注了此注解的注解，能够将注解中的元素包含到 Javadoc 中去。因此不做过多解释。

3.3.3 @Target

@Target 注解是最为常用的元注解，我们知道注解可以被应用于类、方法、变量、参数和包等处，@Target 注解可以指定注解能够被应用于源码中的哪些位置，它可以有如下几种取值：

• ElementType.ANNOTATION_TYPE：可以给一个注解进行注解；

• ElementType.CONSTRUCTOR：可以给构造方法进行注解；

• ElementType.FIELD：可以给属性进行注解；

• ElementType.LOCAL_VARIABLE：可以给局部变量进行注解；

• ElementType.METHOD：可以给方法进行注解；

• ElementType.PACKAGE：可以给一个包进行注解；

• ElementType.PARAMETER：可以给一个方法内的参数进行注解；

• ElementType.TYPE：可以给一个类型进行注解，比如类、接口、枚举。

例如，我们定义注解@Length只能用在类的属性上，可以添加一个@Target(ElementType.FIELD)：

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

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface Length {

    int min() default 0;

    int max() default Integer.MAX_VALUE;

    String message() default "长度不合法";

}

@Target注解的参数也可以接收一个数组。例如，定义注解@Length可以用在属性或局部变量上：

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

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.LOCAL_VARIABLE})
public @interface Length {

    int min() default 0;

    int max() default Integer.MAX_VALUE;

    String message() default "长度不合法";

}

至此，我们就完成了 @Length 注解的定义。下面，我们再来看下剩余的两个元注解。

3.3.4 @Inherited

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

@Inherited
@Target(ElementType.TYPE)
public @interface TestAnnotation {
  	String value() default "test";
}

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

@TestAnnotation("测试注解")
public class Pet {
}

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

public class Cat extends Pet {  
}

3.3.5 @Repeatable

使用@Repeatable这个元注解可以定义注解是否可重复。

例如，一个注解用于标注一个人的角色，他可以是学生，也可以是生活委员。

@Target(ElementType.TYPE)
@Repeatable(Roles.class)
public @interface Role {
    String value() default "";
}

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

@Repeatable 元注解标注了@Role。而 @Repeatable 后面括号中的类相当于一个容器注解，按照规定，它里面必须要有一个 value 的属性，属性类型是一个被 @Repeatable 注解过的注解数组。

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

@Role("学生")
@Role("生活委员")
public class Student {
}

4. 处理注解

4.1 尝试使用注解

我们已经完成了@Length注解的定义：

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

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.LOCAL_VARIABLE})
public @interface Length {

    int min() default 0;

    int max() default Integer.MAX_VALUE;

    String message() default "长度不合法";

}

现在就可以在字段上标注这个注解了：

public class Student {

    // 标注注解
    @Length(min = 2, max = 5, message = "昵称的长度必须在2~5之间")
    private String nickname;

    public Student(String nickname) {
        this.setNickname(nickname);
    }

    public String getNickname() {
        return nickname;
    }

    public void setNickname(String nickname) {
        this.nickname = nickname;
    }

    public static void main(String[] args) {
        // 实例化对象
        Student student = new Student("我的名字很长很长");
        System.out.println(student.getNickname());
    }
}

上面代码中，我们在Student类中的nickname字段上标注了@Length注解，限定了其长度。

那么现在，是不是将其标注在字段上面就可以自动检查字段的长度了呢？答案是否定的。

运行过程如下，昵称长度不合法，但并没有抛出任何异常：

Java 的注解本身对代码逻辑没有任何影响，它只是一个标注。想要检查字段的长度，就要读取注解，处理注解的参数，可以使用反射机制来处理注解。

4.2 通过反射读取注解

我们先来学习一下通过反射读取注解内容相关的 API。

通过反射，判断某个注解是否存在于Class、Field、Method或Constructor：

• Class.isAnnotationPresent(Class)

• Field.isAnnotationPresent(Class)

• Method.isAnnotationPresent(Class)

• Constructor.isAnnotationPresent(Class)

isAnnotationPresent()方法的返回值是布尔类型，例如，判断Student类中的nickname字段上，是否存在@Length注解：

boolean isLengthPresent = Student.class.getDeclaredField("nickname").isAnnotationPresent(Length.class);

通过反射，获取 Annotation 对象：

使用反射 API 读取Annotation：

• Class.getAnnotation(Class)

• Field.getAnnotation(Class)

• Method.getAnnotation(Class)

• Constructor.getAnnotation(Class)

例如，获取nickname字段标注的@Length注解：

Length annotation = Student.class.getDeclaredField("nickname").getAnnotation(Length.class);

通过反射读取注解的完整实例如下：

public class Student {

    // 标注注解
    @Length(min = 2, max = 5, message = "昵称的长度必须在2~6之间")
    private String nickname;

    public Student(String nickname) {
        this.setNickname(nickname);
    }

    public String getNickname() {
        return nickname;
    }

    public void setNickname(String nickname) {
        this.nickname = nickname;
    }

    public static void main(String[] args) throws NoSuchFieldException {
        boolean isLengthPresent = Student.class.getDeclaredField("nickname").isAnnotationPresent(Length.class);
        if (isLengthPresent) {
            Length annotation = Student.class.getDeclaredField("nickname").getAnnotation(Length.class);
            // 获取注解的参数值
            int min = annotation.min();
            int max = annotation.max();
            String message = annotation.message();
            // 打印参数值
            System.out.println("min=" + min);
            System.out.println("max=" + max);
            System.out.println("message=" + message);
        } else {
            System.out.println("没有在nickname字段上找到@Length注解");
        }
    }
}

运行结果：

min=2  
max=5  
message=昵称的长度必须在2~6之间

运行过程如下：

4.3 编写校验方法

获取到了注解以及其内容，我们就可以编写一个校验方法，来校验字段长度是否合法了。我们在Student类中新增一个checkFieldLength()方法，用于检查字段长度是否合法，如果不合法则抛出异常。

完整实例如下：

import java.lang.reflect.Field;

public class Student {

    // 标注注解
    @Length(min = 2, max = 5, message = "昵称的长度必须在2~5之间")
    private String nickname;

    public Student(String nickname) {
        this.setNickname(nickname);
    }

    public String getNickname() {
        return nickname;
    }

    public void setNickname(String nickname) {
        this.nickname = nickname;
    }

    public void checkFieldLength(Student student) throws IllegalAccessException {
        // 遍历所有Field
        for (Field field: student.getClass().getDeclaredFields()) {
            // 获取注解
            Length annotation = field.getAnnotation(Length.class);
            if (annotation != null) {
                // 获取字段
                Object o = field.get(student);
                if (o instanceof String) {
                    String stringField = (String) o;
                    if (stringField.length() < annotation.min() || stringField.length() > annotation.max()) {
                        throw new IllegalArgumentException(field.getName() + ":" + annotation.message());
                    }
                }
            }
        }
    }

    public static void main(String[] args) throws NoSuchFieldException, IllegalAccessException {
        Student student = new Student("小");
        student.checkFieldLength(student);
    }
}

运行结果：

Exception in thread "main" java.lang.IllegalArgumentException: nickname昵称的长度必须在2~5之间
	at Student.checkFieldLength(Student.java:32)
	at Student.main(Student.java:41)

运行过程如下：

5. 小结

通过本小节的学习，我们知道了注解是 Java 语言的一种标注，Java 内置 10 个注解，要大致了解每个注解的作用。使用@interface关键字自定义注解；为注解定义参数的时候要注意其参数的类型，推荐为每个参数都设置默认值；想要自定义注解，必须了解 Java 中内置的 5 个元注解如何使用。

我们自定义的注解通常是用于运行时读取的，因此必须使用@Retention(RetentionPolicy.RUNTIME)进行标注。本小节的概念较多且较为抽象，建议读者亲手去编写几个注解，再来阅读本节内容会有更好的理解。