Java — 注解

Java 注解（Annotation）又称为 Java 标注，是 Java5 开始支持加入源代码的特殊语法元数据。

Java 语言中的类、方法、变量、参数和包等都可以被标注。

Java 标注可以通过反射获取标注的内容，在编译器生成 class 文件时，标注可以被嵌入到字节码中。

Java 虚拟机可以保留标注内容，在运行时可以获取到标注内容。

2.1、内置注解

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

2.2、用在代码上的注解

注解 描述 @Override 检查该方法是否正确地重写了父类的方法。如果重写错误，会报编译错误。 @Deprecated 标记废弃的方法。如果使用该方法，会报编译警告。 @SuppressWarnings 提示编译器忽略注解中声明的警告。 @SafeVarargs Java 7 开始支持，忽略任何使用参数为泛型变量的方法或构造函数调用产生的警告。 @FunctionalInterface Java 8 开始支持，标识一个匿名函数或函数式接口。

2.3、用在其它注解上的注解

此类注解也称为 元注解（meta annotation）。

注解 描述 @Retention 标记在什么时候保存该注解信息，用于描述注解的生命周期。 @Target 标记该注解的使用范围。 @Documented 标记这些注解是否包含在用户文档中。 @Inherited 标记子类可以继承父类的注解。 @Repeatable Java 8 开始支持，标识某注解可以在同一个声明上使用多次。

格式： public @interface 注解名称 {}

步骤：创建注解、定义注解的参数和默认值、用上元注解配置该注解。

3.1、创建注解

示例：定义一个可用于检查字符串长度的注解

public @interface Length {

}

3.2、定义参数和默认值

public @interface Length {
    // 最小长度
    int min() default 0;
    // 最大长度
    int max() default Integer.MAX_VALUE;
    // 长度不合法
    String message() default "长度不合法";
}

注意：

3.3、用元注解配置注解

Retention 译为保留，该注解定义了一个注解的生命周期。

参数 描述 RetentionPolicy.RUNTIME （运行期间有效）注解可以保留到程序运行的时候，它会被加载进入到JVM中，所以在程序运行时可以获取到它们 RetentionPolicy.CLASS （编译期间有效）注解只被保留到编译进行的时候，它并不会被加载到JVM中 RetentionPolicy.SOURCE （源码期间有效）注解只在源码阶段保留，在编译器进行编译时它将被丢弃忽视

// 运行期间有效
@Retention(RetentionPolicy.RUNTIME)
public @interface Length {
    int min() default 0;
    int max() default Integer.MAX_VALUE;
    String message() default "长度不合法";
}

Target 译为目标，该是最为常用的元注解，可以指定自己能够被应用于源码中的哪些位置。

参数 描述 ElementType.TYPE 给一个类型进行注解，比如类、接口、枚举 ElementType.FIELD 给属性进行注解 ElementType.METHOD 给方法进行注解 ElementType.PARAMETER 给一个方法内的参数进行注解 ElementType.CONSTRUCTOR 给构造方法进行注解 ElementType.LOCAL_VARIABLE 给局部变量进行注解 ElementType.ANNOTATION_TYPE 给一个注解进行注解 ElementType.PACKAGE 给一个包进行注解

// 只用用于类属性或局部变量上
@Target({ElementType.FIELD, ElementType.LOCAL_VARIABLE})
public @interface Length {
    int min() default 0;
    int max() default Integer.MAX_VALUE;
    String message() default "长度不合法";
}

Documented 译为文档，标注了此注解的注解，能够将注解中的元素包含到 Javadoc 中去。

// 将该注解元素添加到JavaDoc中
@Documented
public @interface Length {
    int min() default 0;
    int max() default Integer.MAX_VALUE;
    String message() default "长度不合法";
}

Inherited 译为继承，使用该注解定义子类是否可继承父类定义的注解。

@Inherited 仅针对 @Target(ElementType.TYPE) 类型的注解有效，并且仅针对类的继承有效，对接口的继承无效。

// 使用该注解的类，其子类默认继承该注解（仅针对类的继承有效）
@Inherited
// 给一个类型进行注解，类、接口、枚举等
@Target(ElementType.TYPE)
public @interface Length {
    int min() default 0;
    int max() default Integer.MAX_VALUE;
    String message() default "长度不合法";
}

此时一个类用到了该注解

@Length(min = 2, max = 16, message = "昵称长度2~16之间")
public class Pet {}

其子类默认继承了该注解

// 相当于继承了@Length
public class Cat extends Pet {}

Repeatable 译为可重复，使用该元注解可以定义注解是否可重复。

// 作用于类的属性上
@Target(ElementType.FIELD)
// 注解Role注解，在类的属性上可使用多个Role注解
@Repeatable(Roles.class)
public @interface Role {
    String value() default "";
}

// 作用于类的属性上
@Target(ElementType.FIELD)
public @interface Roles {
    Role[] value();
}

@Repeatable 元注解标注了 @Role，而 @Repeatable 后面括号中的类相当于一个容器注解。

按照规定，它里面必须要有一个 value 的属性，属性类型是一个被 @Repeatable 注解标注过的注解数组。

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

4.1、示例1

需求：使用 @length 注解判断学生姓名长度是否合法。

示例：

// 运行期间有效
@Retention(RetentionPolicy.RUNTIME)
// 作用于类的属性上
@Target({ElementType.FIELD})
public @interface Length {
    // 最小长度
    int min() default 0;
    // 最大长度
    int max() default Integer.MAX_VALUE;
    // 提示信息
    String message() default "长度不合法";
}

public class Student {

    @Length(min = 1, max = 3, message = "名称超长")
    private String name;

    public Student(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }

    public static void main(String[] args) throws NoSuchFieldException {
        Student student = new Student("上官飞燕");
        // 判断name属性上length注解是否存在
        boolean lengthPresent = student.getClass().getDeclaredField("name").isAnnotationPresent(Length.class);
        if (lengthPresent) {
            // 获取注解内容
            Length length = student.getClass().getDeclaredField("name").getAnnotation(Length.class);
            // 使用注解信息校验名称是否合法
            if (length.min()

运行：

名称超长，合法长度：1~3。当前长度：4

4.2、示例2

需求：使用 @Repeatable 注解获取学生所有的职位。

示例：

// 运行期间有效
@Retention(RetentionPolicy.RUNTIME)
// 作用于类的属性上
@Target(ElementType.FIELD)
public @interface Roles {
    Role[] value();
}

// 运行期有效
@Retention(RetentionPolicy.RUNTIME)
// 作用与类的属性上
@Target({ElementType.FIELD})
// 注解Role注解，在类的属性上可使用多Role注解
@Repeatable(Roles.class)
public @interface Role {
    String value() default "";
}

public class Student {

    @Role("学习委员")
    @Role("体育委员")
    private String name;

    public Student(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }

    public static void main(String[] args) throws NoSuchFieldException {
        Student student = new Student("王五");
        // 判断name属性上@Role注解是否存在
        Role[] roles = student.getClass().getDeclaredField("name").getAnnotationsByType(Role.class);
        if (roles.length == 0) {
            System.out.println("Student.name属性上没有找到@Role注解");
        } else {
            // 获取注解内容
            for (Role role : roles) {
                System.out.println(student.getName() + " = " + role.value());
            }
        }
    }
}

运行：

王五 = 学习委员
王五 = 体育委员

Original: https://www.cnblogs.com/bybeiya/p/15086690.html
Author: 北涯
Title: Java — 注解