如何用 Java 自定义注解

自定义注解在 Java 中是一种应用元数据的方式、其实现通过使用 @interface 关键字、注解可具有元素来传递信息、且可通过反射在运行时获取和处理注解信息。在 Java 中自定义注解不仅能够通过编译时检查代码，还能在运行时通过反射进行处理。一种常见的使用场景是在框架开发中，比如 Spring 框架广泛使用注解来进行配置和管理。

一、注解的基本概念和语法

注解（Annotation）的基本概念是一种代码级别的说明。它由 Java 5 引入，使得开发者可以在不改变代码逻辑的情况下，在源码中添加信息。这些信息可以在编译时（source）、类加载时（class）或运行时（runtime）被读取，并对其进行相应的处理。

注解的声明使用 @interface 关键字。它的体内可以定义额外的“元素”（类似于接口的方法），用来接收额外的信息。

public @interface MyAnnotation {
    String value();
    int priority() default 0;
}

在这个例子中，MyAnnotation 是一个自定义注解，拥有两个元素：value和priority。其中priority元素有一个默认值0。

二、元素的定义和默认值

注解的元素类似于接口中的方法，但它们可以定义默认值。当在注解中不显式设置元素的值时，将使用其默认值。

public @interface MyAnnotation {
    String name();
    int age() default 18;
}

在使用带有默认值的注解时，可以忽略这些元素。例如，我们可以只设定name而忽略age：

@MyAnnotation(name = "Alice")
public class MyClass {
    //...类的其余部分...
}

三、注解的使用和获取

自定义注解的使用很简单，只需要在代码的合适位置前面加上注解的名字，如果有需要，再提供相关的元素值。

@MyAnnotation(name = "Bob", age = 25)
public void myMethod() {
    //...方法实现...
}

获取注解的信息通常依赖 Java 反射 API。可以在运行时获取类、方法或字段上的注解并查询它们的元素值。

Method m = MyClass.class.getMethod("myMethod");
if (m.isAnnotationPresent(MyAnnotation.class)) {
    MyAnnotation ann = m.getAnnotation(MyAnnotation.class);
    System.out.println("Name: " + ann.name() + ", Age: " + ann.age());
}

四、Retention 和 Target 元注解

Retention 元注解定义了注解的保留策略，即注解信息存在的时间长短。Java 提供了三种保留策略：

RetentionPolicy.SOURCE：注解仅在源码中保留，在编译时会被丢弃，不会写入字节码。
RetentionPolicy.CLASS：注解在编译时会被写入字节码，类加载时将会被忽略，是默认的行为。
RetentionPolicy.RUNTIME：注解在运行时仍然被保留，可以通过反射读取。

Target 元注解定义了注解用于哪些 Java 元素，如类型、字段、方法等。

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface MyAnnotation {
    //...元素定义...
}

通过使用这些元注解，可以控制自定义注解的适用场景和信息保留时间。

五、参数类型和约束

自定义注解中的参数类型受到一定的限制，有效的类型包括基本数据类型、String、Class、枚举、注解，以及上述类型的数组。

public @interface MyAnnotation {
    Class<?> targetClass();
    String[] aliases();
    RetentionPolicy policy();
}

注解元素在使用时还有一些约束：

元素不能有不确定的值，即非常数表达式；
注解不能自包含，即注解不能作为它自己的元素；
不能继承其他的注解或接口。

六、注解的继承和组合

尽管注解本身不能继承其他注解，但是注解可以具有继承行为。如果一个类的超类被某个注解标记，那么这个注解在某些情况下可以被继承到子类。

@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface InheritableAnnotation {
    //...元素定义...
}
@InheritableAnnotation
public class Base {
    //...基类代码...
}
public class Derived extends Base {
    //...派生类代码...
}

使用 @Inherited 元注解可以使注解具有继承性。在这个例子中，即便没有显式地在 Derived 类上标注 InheritableAnnotation，它也会继承自它的基类。

组合注解则是一种快速配置框架编程模式的方法，它可以组合多个注解到一个注解中。

@Retention(RetentionPolicy.RUNTIME)
public @interface Schedules {
    Schedule[] value();
}
@Schedules({
    @Schedule(dayOfMonth="last"),
    @Schedule(dayOfWeek="Fri", hour="23")
})
public void doPeriodicCleanup() {
    //...任务代码...
}