Java 注解

Java注解（Annotation）是一种元数据形式，它提供了一种安全的方法来关联信息与程序元素（类、方法、变量等），而不会改变它们的行为。注解可以被编译器和工具处理，并在运行时通过反射访问。

1 基本概念

• 元注解：这些是用于定义其他注解的注解。Java提供了四个标准的元注解：

  • @Retention：指定注解的生命周期。
  • @Target：指定注解可以应用的目标类型。
  • @Documented：标记该注解应该包含在Javadoc中。
  • @Inherited：允许子类继承父类中的注解。

• 保留策略：由@Retention定义，有三种策略：

  • RetentionPolicy.SOURCE：注解仅存在于源码级别，编译时会被丢弃。
  • RetentionPolicy.CLASS：注解被编译器记录在class文件中，但不会加载到JVM中。
  • RetentionPolicy.RUNTIME：注解不仅保存在class文件中，还可以通过反射机制在运行时读取。

• 目标类型：由@Target定义，常见的有：

  • ElementType.TYPE：可以应用于类、接口或枚举声明。
  • ElementType.METHOD：可以应用于方法。
  • ElementType.FIELD：可以应用于字段。
  • ElementType.PARAMETER：可以应用于参数。
  • ElementType.CONSTRUCTOR：可以应用于构造函数。
  • ElementType.LOCAL_VARIABLE：可以应用于局部变量。
  • ElementType.ANNOTATION_TYPE：可以应用于自定义注解。
  • ElementType.PACKAGE：可以应用于包声明。

2 元注解

2.1 注解生命周期 （@Retention）

Java注解的生命周期是由@Retention元注解来定义的。@Retention指定了注解在什么级别上保留，以及它们如何被JVM处理。@Retention有三种策略，分别对应不同的生命周期：

• RetentionPolicy.SOURCE

  • 生命周期：源代码级
  • 说明：注解仅存在于源代码中，在编译时会被丢弃，不会保存到.class文件中。
  • 使用场景：通常用于编译器检查或静态分析工具。例如，@Override注解就是一个典型的例子，它帮助编译器检查方法是否正确地重写了父类的方法。

• RetentionPolicy.CLASS

  • 生命周期：字节码级
  • 说明：注解会在编译时被编译器记录在class文件中，但是加载到JVM时不会被保留，因此在运行时无法通过反射访问这些注解。
  • 使用场景：这类注解主要用于编译时处理和类加载时处理，比如@Deprecated用来标记过时的方法或字段，但不需要在运行时进行特殊处理。

• RetentionPolicy.RUNTIME

  • 生命周期：运行时
  • 说明：注解不仅被编译器记录在class文件中，而且加载到JVM后仍然可以保留，这样就可以通过反射机制在运行时读取到这些注解。
  • 使用场景：适用于那些需要在程序运行时获取注解信息的情况。例如，许多框架（如Spring）使用这种类型的注解来进行依赖注入、事务管理等。

2.2 @Target

@Target 是 Java 中的一个元注解，用于指定自定义注解可以应用的目标类型。通过 @Target 注解，你可以控制你的注解可以被用在哪些程序元素上，比如类、方法、字段等。@Target 使用 ElementType 枚举来定义这些目标。如果你创建了一个自定义注解但没有使用@Target来指定它的目标元素类型，那么这个自定义注解默认可以应用于所有可能的程序元素上。

ElementType 枚举值：ElementType 枚举中定义了多个值，每个值代表一种可能的注解目标：

• TYPE：应用于类、接口（包括注解类型）、枚举声明。
• FIELD：应用于字段声明（包括枚举常量）。
• METHOD：应用于方法声明。
• PARAMETER：应用于参数声明。
• CONSTRUCTOR：应用于构造器声明。
• LOCAL_VARIABLE：应用于局部变量声明。
• ANNOTATION_TYPE：应用于注解类型声明。
• PACKAGE：应用于包声明。
• TYPE_PARAMETER：应用于类型参数声明（Java 8 及以上版本）。
• TYPE_USE：应用于任何使用类型的语境（Java 8 及以上版本）。

示例代码：下面是一个使用 @Target 的例子，定义了一个只能用于方法上的注解。

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.METHOD)
public @interface MyMethodAnnotation {String value() default "";
}

然后可以在方法上使用这个注解：

public class ExampleClass {@MyMethodAnnotation("This is a method annotation")public void exampleMethod() {// 方法实现}
}

如果尝试将此注解应用于非方法的其他元素（例如类或字段），编译器将会报错。

作用多个目标示例代码：你需要在 @Target 注解中提供一个 ElementType 数组。

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.METHOD, ElementType.FIELD })
public @interface MyMultiTargetAnnotation {String value() default "";
}

这样，MyMultiTargetAnnotation 就可以同时用于方法和字段：

public class ExampleClass {@MyMultiTargetAnnotation("This is a field annotation")private int exampleField;@MyMultiTargetAnnotation("This is a method annotation")public void exampleMethod() {// 方法实现}
}

通过合理地使用 @Target，你可以确保你的注解只出现在它们应该出现的地方，从而增强代码的清晰性和可维护性。

2.3 @Documented

@Documented 用于标记自定义注解。当一个注解被 @Documented 标记时，该注解的信息将会被包含在生成的文档中，比如通过 Javadoc 工具生成的 API 文档。

作用：

使用 @Documented 的主要目的是让开发人员能够看到某个类、方法或字段上所使用的注解信息，这些信息对于理解代码的行为和约束条件是非常有用的。例如，如果某个方法被标记为 @Deprecated，那么这个信息会出现在文档中，提醒用户该方法已经过时，不推荐使用。

2.4  @Inherited

@Inherited 用于自定义注解。当一个注解被 @Inherited 标记时，表示该注解可以被子类继承。这意味着如果一个类被标记了带有 @Inherited 的注解，并且该类有子类，那么这些子类也会被视为带有这个注解，即使它们并没有显式地声明它。

作用：@Inherited 主要用于以下场景：

• 当你希望某个注解能够影响到所有继承它的类时。
• 当你需要通过反射来检查某个类是否带有特定的注解，而这个注解在父类中声明，但不在子类中重复声明。

限制：

• @Inherited 只对类级别的注解有效。也就是说，只有当注解的目标是 ElementType.TYPE 时，@Inherited 才会起作用。
• 如果子类直接声明了相同的注解，则会覆盖从父类继承来的注解。
• 接口不能继承注解，因此 @Inherited 对接口不起作用。

示例代码：

假设我们有一个注解 @MyAnnotation，并且我们希望它能够被子类继承。

import java.lang.annotation.*;@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
public @interface MyAnnotation {String value() default "";
}

然后我们在一个父类上使用这个注解：

@MyAnnotation(value = "Parent")
public class ParentClass {// 父类代码
}

接下来定义一个子类：

public class ChildClass extends ParentClass {// 子类代码
}

现在，如果我们使用反射来检查 ChildClass 是否带有 @MyAnnotation 注解，即使 ChildClass 没有直接声明这个注解，它也会返回 true：

public class Main {public static void main(String[] args) {Class<?> clazz = ChildClass.class;if (clazz.isAnnotationPresent(MyAnnotation.class)) {MyAnnotation annotation = clazz.getAnnotation(MyAnnotation.class);System.out.println("Value: " + annotation.value());} else {System.out.println("No annotation found.");}}
}

运行上面的代码将会输出：

Value: Parent

这表明 ChildClass 继承了 ParentClass 上的 @MyAnnotation 注解。

注意事项：

• 如果你不希望注解被继承，就不要使用 @Inherited。
• @Inherited 不会影响注解的生命周期，它只影响注解是否会被子类继承。注解的生命周期是由 @Retention 元注解控制的。
• 如果需要在多个层次的继承关系中传递注解信息，确保理解 @Inherited 的行为以及如何通过反射访问注解。

3 常用内置注解 

Java提供了一些内置的注解，这些注解在日常开发中非常有用。下面是一些常用的内置注解及其简单的使用示例：

3.1 @Override

• 用途：用于表示一个方法声明意图覆盖超类中的方法。
• 好处：如果方法签名不正确（例如拼写错误），编译器会报错。

public class Animal {public void makeSound() {System.out.println("Some generic animal sound");}
}public class Dog extends Animal {@Overridepublic void makeSound() {System.out.println("Bark");}
}

3.2 @Deprecated

• 用途：标记一个元素（如方法、字段或类）已经过时，该元素仍然可以使用，但是不推荐在新的代码中使用。
• 好处：编译器会在使用了被@Deprecated标记的元素时发出警告。

public class Calculator {@Deprecatedpublic int add(int a, int b) {return a + b;}public int sum(int a, int b) {return a + b; // 新的方法}
}public class Main {public static void main(String[] args) {Calculator calc = new Calculator();// 使用旧的方法会得到警告int result = calc.add(3, 4);System.out.println(result);}
}

3.3 @SuppressWarnings

• 用途：告诉编译器忽略特定的警告信息。
• 好处：可以用来抑制那些你认为不需要关注的警告。

常见的抑制警告类型：

@SuppressWarnings 注解接受一个字符串数组作为参数，每个元素代表一种类型的警告。以下是一些常见的警告类型：

• "unchecked": 抑制与泛型相关的未经检查的转换警告。
• "rawtypes": 抑制当使用原始类型（未参数化的泛型）时产生的警告。
• "deprecation": 抑制使用了过时 API 的警告。
• "unused": 抑制未使用的代码（如变量、参数等）的警告。
• "serial": 抑制当序列化类没有声明 serialVersionUID 时的警告。
• "fallthrough": 抑制 switch 语句中缺少 break 导致的 fall-through 警告。

抑制未经检查的警告： 

import java.util.ArrayList;
import java.util.List;public class Example {@SuppressWarnings("unchecked")public void addToList() {List list = new ArrayList();list.add("String"); // 不会发出未经检查的警告}
}

 抑制多个警告：

import java.util.logging.Logger;public class Example {private static final Logger LOGGER = Logger.getLogger(Example.class.getName());@SuppressWarnings({"unused", "rawtypes"})public void exampleMethod() {List list = new ArrayList(); // 不会发出未使用和原始类型的警告LOGGER.info("This is an info message");}
}

在类级别上抑制所有警告：

@SuppressWarnings("all")
public class Example {// 这个类中的所有警告都会被抑制
}

注意事项：

• 谨慎使用：虽然 @SuppressWarnings 很有用，但是应该谨慎使用，因为它可能会隐藏真正的代码问题。
• 明确指定警告类型：尽量不要使用 "all" 来抑制所有类型的警告，而应具体指出需要抑制哪些类型的警告。
• 文档说明：如果使用了 @SuppressWarnings，最好在代码中添加注释，解释为什么需要抑制这些警告，以及是否有计划在未来修复这些问题。

3.4 @FunctionalInterface 

• 用途：标记一个接口为函数式接口。
• 好处：确保接口有且仅有一个抽象方法，并且可以被用作Lambda表达式的类型。

@FunctionalInterface
public interface MyFunction {int apply(int x, int y);default int defaultMethod(int x) {return x * 2;}
}public class Main {public static void main(String[] args) {MyFunction func = (x, y) -> x + y;int result = func.apply(3, 4);System.out.println(result); // 输出 7}
}

函数式接口参考：Java 函数式接口-CSDN博客

Lambda表达式参考：Java Lambda表达式-CSDN博客

3.5 @SafeVarargs

@SafeVarargs 用于声明一个方法或构造器不会对泛型可变参数（varargs）进行不安全的操作。这个注解主要用于帮助开发者避免与泛型数组相关的潜在问题，并且告诉编译器可以忽略与该方法相关的堆污染警告。

在 Java 中，由于类型擦除机制，直接创建泛型类型的数组是不安全的，因为这会导致运行时的类型安全问题。例如，下面的代码会触发编译器警告。

public static <T> T[] badMethod(T... args) {T[] array = (T[]) new Object[args.length]; // 不安全的转换for (int i = 0; i < args.length; i++) {array[i] = args[i];}return array;
}

这段代码中，T[] array = (T[]) new Object[args.length]; 这一行会产生一个未经检查的转换警告，因为编译器无法保证 T 的实际类型是 Object 的子类。如果 T 是一个具体的引用类型，那么在运行时可能会抛出 ClassCastException。

@SafeVarargs 注解可以用来标记那些不会对泛型可变参数进行不安全操作的方法或构造器。使用 @SafeVarargs 后，编译器将不再为这些方法生成未经检查的转换警告。

import java.util.Arrays;public class SafeVarargsExample {@SafeVarargspublic static <T> void printArray(T... elements) {System.out.println(Arrays.toString(elements));}public static void main(String[] args) {printArray("Hello", "World");printArray(1, 2, 3);}
}

在这个例子中，printArray 方法使用了 @SafeVarargs 注解，表明它不会对传入的泛型可变参数进行不安全的操作。因此，编译器不会发出任何关于未经检查的转换的警告。

3.6 @Repeatable

@Repeatable 是 Java 8 引入的一个元注解，它允许你在同一个地方多次使用同一个注解。在 Java 8 之前，一个元素（如类、方法或字段）只能被同一种类型的注解标记一次。@Repeatable 注解的引入解决了这个问题，使得开发者可以更灵活地使用注解。

要使用 @Repeatable，你需要定义两个注解：

• 一个“容器注解”（Container Annotation），这是一个数组类型的注解，用于保存多个基础注解的实例。
• 一个“基础注解”（Base Annotation），使用 @Repeatable 元注解，并指定容器注解的类型，这是你实际想要重复使用的注解。

示例代码：假设我们有一个注解 @Roles，用于指定用户角色，我们希望能够在同一个方法上多次使用这个注解来表示不同的角色。

定义基础注解：

import java.lang.annotation.*;@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Repeatable(RolesContainer.class) // 指定容器注解
public @interface Roles {String[] value();
}

定义容器注解：

import java.lang.annotation.*;@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface RolesContainer {Roles[] value();
}

使用基础注解：

public class UserService {@Roles({"ADMIN", "USER"})@Roles({"GUEST"})public void performAction() {// 方法实现}
}

在这个例子中，@Roles 注解被两次应用于 performAction 方法，分别指定了不同的角色集合。

通过反射访问重复注解：

import java.lang.reflect.Method;public class Main {public static void main(String[] args) throws NoSuchMethodException {Method method = UserService.class.getMethod("performAction");// 获取容器注解RolesContainer rolesContainer = method.getAnnotation(RolesContainer.class);if (rolesContainer != null) {for (Roles roles : rolesContainer.value()) {System.out.println("Roles: " + Arrays.toString(roles.value()));}}// 或者直接获取所有基础注解Roles[] rolesAnnotations = method.getAnnotationsByType(Roles.class);for (Roles roles : rolesAnnotations) {System.out.println("Roles: " + Arrays.toString(roles.value()));}}
}

输出结果：

Roles: [ADMIN, USER]
Roles: [GUEST]
Roles: [ADMIN, USER]
Roles: [GUEST]

反射参考：Java 反射体系-CSDN博客 

注意事项：

• 容器注解必须是数组类型的：容器注解的值必须是一个数组，其元素类型是基础注解。
• 基础注解必须用 @Repeatable 标记：基础注解需要使用 @Repeatable 元注解，并指定容器注解的类型。
• 保留策略：通常情况下，基础注解和容器注解的保留策略应相同，通常是 RetentionPolicy.RUNTIME，以便通过反射访问。