Java 注解 (Annotations)的定义和使用规则

关注

原创最新推荐文章于 2026-06-17 11:28:03 发布 1k 阅读 AI 写同款· GEO 优化 ›

Java语言的注解（Annotations）注解（Annotations）是Java 5引入的一种语法结构，它为程序元素（类、方法、变量等）提供元数据。注解本身不会直接影响代码的逻辑，但可以通过框架、工具等进行处理，从而达到特定的目的。注解使用“@”符号标识，后面跟随注解名和可选参数。自定义注解的创建与接口类似，我们可以定义注解的成员。```java@Target(ElementType.METHOD) // 指定注解可以用在方法上@Retention(RetentionPolicy.RUNTIME) // 指定注解在运行时仍然可用。阅读详情

Java 注解（Annotations）是 Java 5 引入的一种元数据（Metadata），它提供了一种在源代码中嵌入补充信息的方式，这些信息可以被编译器、JVM 或其他工具在编译时、运行时进行处理。注解本身不会直接影响程序的执行，但可以用来指导编译器、JVM 或其他工具的行为，从而实现各种功能。

一、注解的定义 (Annotation Definition)

什么是元数据 (Metadata)?
- 元数据是描述数据的数据。在 Java 中，元数据是指描述程序代码的数据，例如类、方法、字段等的属性信息。
- 注解就是一种元数据，它可以用来描述类、方法、字段、参数、局部变量等程序元素。
注解的语法：
```
@Retention(RetentionPolicy.RUNTIME) // 元注解，指定注解的保留策略
@Target({ElementType.METHOD, ElementType.TYPE}) // 元注解，指定注解可以应用的程序元素类型
public @interface MyAnnotation { // 定义一个注解

    // 注解成员 (Annotation Members)
    String name() default "Default Name"; // 默认值
    int value(); // 必须赋值

    Class<?> type() default void.class; //类型
}
```
- @interface 关键字： 用于定义一个注解。
- 注解名 (Annotation Name): 遵循 PascalCase 命名规范（每个单词首字母大写），例如 Override, Deprecated, WebServlet。
- 注解成员 (Annotation Members):
  - 类似于接口中的方法声明，但没有方法体。
  - 可以有默认值 (使用 default 关键字指定)。
  - 如果没有默认值，则在使用注解时必须显式赋值。
  - 成员的类型可以是原始类型、String、Class、枚举类型、注解类型或这些类型的数组。
  - 注解成员实际上类似于接口中的方法，这意味着它们可以有访问修饰符，但通常省略 (默认是 public)。
  - 注解成员后面要跟一对小括号，即使没有参数。

二、元注解 (Meta-Annotations)

元注解是用于修饰注解的注解，用于指定注解的特性。

@Retention：
- 作用： 指定注解的保留策略 (Retention Policy)，即注解在哪个阶段可用。
- RetentionPolicy 枚举：
  - RetentionPolicy.SOURCE: 注解仅保留在源代码中，在编译时被丢弃。例如，@Override 注解。
  - RetentionPolicy.CLASS: 注解保留在 class 文件中，但在运行时会被 JVM 丢弃。
  - RetentionPolicy.RUNTIME: 注解保留在 class 文件中，并且在运行时可以通过反射 API 获取。这是最常用的保留策略，可以实现各种动态功能。
- 示例：
```
@Retention(RetentionPolicy.RUNTIME) // 指定注解在运行时可用
public @interface MyAnnotation {
    // ...
}
```
@Target：
- 作用： 指定注解可以应用的程序元素类型 (Target Element)。
- ElementType 枚举：
  - ElementType.TYPE: 可以应用于类、接口、枚举、注解。
  - ElementType.FIELD: 可以应用于字段。
  - ElementType.METHOD: 可以应用于方法。
  - ElementType.PARAMETER: 可以应用于方法参数。
  - ElementType.CONSTRUCTOR: 可以应用于构造方法。
  - ElementType.LOCAL_VARIABLE: 可以应用于局部变量。
  - ElementType.ANNOTATION_TYPE: 可以应用于注解。
  - ElementType.PACKAGE: 可以应用于包。
  - ElementType.TYPE_PARAMETER: 类型参数，since 1.8
  - ElementType.TYPE_USE: 使用类型的任何地方, since 1.8
- 示例：
```
@Target({ElementType.METHOD, ElementType.TYPE}) // 指定注解可以应用于方法和类
public @interface MyAnnotation {
    // ...
}
```

@Documented：

作用： 指定该注解应该包含在 Javadoc 文档中。

示例：

@Documented // 指定该注解应该包含在 Javadoc 文档中
public @interface MyAnnotation {
    // ...
}

@Inherited：

作用： 指定该注解可以被子类继承。

示例：

@Inherited // 指定该注解可以被子类继承
public @interface MyAnnotation {
    // ...
}

@Repeatable (Java 8+)：

作用： 指定该注解可以在同一个程序元素上重复使用。

示例：

@Repeatable(Authorities.class)
public @interface Authority {
    String role();
}

public @interface Authorities {
    Authority[] value();
}

@Authority(role="Admin")
@Authority(role="Editor")
public class MyClass {
    // ...
}

三、内置注解 (Built-in Annotations)

Java 提供了一些内置注解，可以直接使用：

@Override：

作用： 用于标记一个方法是重写 (Override) 了父类的方法。
用途：
- 帮助编译器检查是否正确地重写了方法。如果方法签名与父类方法不匹配，编译器会报错。
- 提高代码可读性，明确表明该方法是重写了父类的方法。

示例：

class Animal {
    void eat() {
        System.out.println("Animal is eating.");
    }
}

class Dog extends Animal {
    @Override // 标记该方法重写了父类的 eat() 方法
    void eat() {
        System.out.println("Dog is eating.");
    }
}

@Deprecated：

作用： 用于标记一个类、方法或字段已过时 (Deprecated)，不建议使用。
用途：
- 提醒开发者该类、方法或字段已经不推荐使用，可能会在将来的版本中被移除。
- 可以提供替代方案的说明。

示例：

@Deprecated // 标记该方法已过时
public void oldMethod() {
    // ...
}

/**
 * @deprecated Use {@link #newMethod()} instead.
 */
@Deprecated
public void oldMethodWithComment(){
    //...
}

public void newMethod() {
    // ...
}

@SuppressWarnings：
- 作用： 用于抑制编译器发出的警告。
- 用途：
  - 在某些情况下，编译器可能会发出一些不必要的警告，可以使用 @SuppressWarnings 注解来抑制这些警告。
- 取值：
  - all: 抑制所有警告。
  - boxing: 抑制与自动装箱/拆箱相关的警告。
  - deprecation: 抑制与使用了 @Deprecated 标记的类、方法或字段相关的警告。
  - unchecked: 抑制与未检查的类型转换相关的警告（例如，在使用原始类型时）。
  - unused: 抑制与未使用的变量相关的警告。
  - resource: 抑制与资源未关闭相关的警告。
  - 等等 (具体取决于编译器)。
- 示例：
```
@SuppressWarnings("unchecked") // 抑制类型转换警告
List list = new ArrayList();
list.add("Hello");
String s = (String) list.get(0); // 编译器会发出 unchecked 类型转换警告
```

四、自定义注解 (Custom Annotations)

除了内置注解，你还可以根据自己的需求创建自定义注解。

定义注解：
- 使用 @interface 关键字定义注解。
- 指定元注解 (@Retention, @Target 等)。
- 定义注解成员。
使用注解：
- 在程序元素（类、方法、字段等）上使用自定义注解，并为注解成员赋值（如果需要）。
处理注解 (Annotation Processing):
- 编译时处理： 可以使用注解处理器 (Annotation Processor) 在编译时处理注解，生成代码或配置文件。例如，Lombok 使用注解处理器自动生成 getter/setter 方法。
- 运行时处理： 可以使用反射 API 在运行时获取注解信息，并根据注解信息执行相应的逻辑。

五、使用场景 (Annotation Usage Scenarios)

注解在 Java 中有着广泛的应用，主要包括以下场景：

编译时检查：
- 使用 @Override 注解进行方法重写检查。
- 使用 @SuppressWarnings 注解抑制编译器警告。
代码生成：
- Lombok 使用注解处理器自动生成 getter/setter 方法、构造方法、equals()/hashCode() 方法等，简化代码编写。
- JPA 使用注解来映射类和数据库表，生成 SQL 语句。
- Spring MVC 使用注解来映射请求 URL 和处理方法。
配置：
- Spring 使用注解来配置 Bean、依赖注入、事务管理、AOP 等。
- JAX-RS 使用注解来定义 RESTful Web 服务。
运行时行为修改：
- 单元测试框架 (例如 JUnit, TestNG) 使用注解来标记测试方法。
- 安全框架 (例如 Spring Security) 使用注解来进行权限控制。
- 序列化框架 (例如 Jackson, Gson) 使用注解来控制序列化和反序列化过程。

六、代码示例 (自定义注解)

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

@Retention(RetentionPolicy.RUNTIME) // 指定注解在运行时可用
@Target(ElementType.METHOD) // 指定注解可以应用于方法
public @interface MyAnnotation { // 定义一个自定义注解

    String name() default "Default Name"; // 成员变量,默认值Default Name
    int value();   // 成员变量

}

class MyClass {

    @MyAnnotation(name = "My Method", value = 100) // 使用注解并赋值
    public void myMethod() {
        System.out.println("My method is called.");
    }
}

public class AnnotationExample {

    public static void main(String[] args) throws Exception {
        Class<?> clazz = MyClass.class;
        Method method = clazz.getMethod("myMethod");

        if (method.isAnnotationPresent(MyAnnotation.class)) { // 判断方法是否使用了 MyAnnotation 注解
            MyAnnotation annotation = method.getAnnotation(MyAnnotation.class); // 获取注解对象

            System.out.println("Annotation name: " + annotation.name()); // 获取 name 成员的值
            System.out.println("Annotation value: " + annotation.value()); // 获取 value 成员的值
        }
    }
}

七、总结

Java 注解是一种强大的元数据机制，它可以在代码中嵌入补充信息，并在编译时或运行时被处理。理解注解的定义、元注解、内置注解、自定义注解以及使用场景，可以帮助你编写更简洁、更灵活、更易于维护的 Java 代码。掌握注解，能让你更深入地理解各种框架和库的运作方式，并能够自定义 Spring Boot Starter等功能.

收录于