注解

是什么，为什么存在

Java 注解是一条结构化记录，可以附在类、方法、字段、参数等声明上，也可以附在某些类型使用位置上。注解把「这段代码具有什么额外含义」写在被描述的程序元素附近，而不必把这些信息放进命名约定、外部 XML 或重复的注册代码中。

注解本身不会调用方法、执行权限检查或注入依赖。它只是元数据，具体语义来自消费者：编译器能检查 @Override，编译期处理器能生成文件或报告错误，运行时代码能通过 反射（reflection） 读取 RUNTIME 注解。若没有消费者，@Audited 只是一个没有行为的标记。

你会在编译器警告、测试发现、序列化映射、依赖注入、路由注册和静态分析中遇到注解。注解适合表达有限、声明式且能由工具统一解释的配置。需要任意控制流、动态数据或复杂对象关系时，普通 Java API 往往更清楚。

注解契约包含三方：声明注解接口的作者、把注解用于代码的调用方，以及读取它的消费者。只写清元素名称还不够；契约还要规定可标注位置、元数据保留到哪个阶段、缺省值含义、重复与继承规则，以及消费者找不到注解时的行为。

工作原理

注解接口使用 @interface 声明。它的无参数方法定义注解元素，调用注解时则为这些元素提供值。名为 value 的单个元素可省略名称，所以 @Role("admin") 等价于 @Role(value = "admin")。

注解元素的返回类型只能是基本类型、String、Class、枚举、另一个注解，或这些类型的一维数组。元素不能接收参数或声明类型参数，也不能用 null 作为值。缺省值属于注解接口，而不是复制到每个使用点；修改缺省值会影响之后读取既有二进制注解的结果。

元注解定义契约

元注解（meta-annotation） 标注另一个注解接口，并控制它的语言级行为。最常用的五个元注解各自解决一个独立问题。

没有 @Target 时，注解可用于大多数声明上下文，但不能因此用于类型参数声明或类型使用上下文。明确写出 @Target 能让编译器拒绝误放位置，也让读者知道消费者应扫描什么。Java 25 的目标还包括 TYPE_PARAMETER、TYPE_USE、MODULE 与 RECORD_COMPONENT。

保留策略（retention policy） 决定消费者在哪个阶段还能看到元数据。未声明 @Retention 时默认为 CLASS，不是 RUNTIME。

下面的流程图把三种主要消费路径分开。编译器总会检查注解语法与适用位置；是否运行处理器、是否把元数据保留到运行时，则由构建配置与保留策略决定。

声明注解与类型使用注解

声明注解描述一个程序元素，例如方法是否为路由。 类型使用注解（type-use annotation） 描述某次具体的类型出现，例如 List<@NonEmpty String> 中的类型实参。两者可能写在相近位置，却属于不同的反射模型。

Class、Method 和 Field 等对象实现 AnnotatedElement，用于查询声明注解。类型使用注解则通过 AnnotatedType、AnnotatedParameterizedType 等接口读取。只调用 method.getAnnotation(...) 不会遍历返回类型中的嵌套类型实参。

预定义注解

@Override 让编译器确认方法确实覆盖或实现了可覆盖声明，能在重命名或签名写错时阻止编译。@FunctionalInterface 确认接口符合函数式接口规则，但没有它的合格接口仍可作为 lambda 目标。

@Deprecated 标出不建议继续使用的 API；since 记录进入弃用状态的版本，forRemoval 表示未来版本存在移除意图。公开 API 通常还应在 Javadoc 的 @deprecated 标签中说明替代方案。

@SuppressWarnings 只影响编译器诊断，不修复类型安全问题。应把它放在能覆盖问题的最小声明上，并使用目标编译器识别的具体警告名。@SafeVarargs 更是一项由作者作出的安全断言；编译器不会证明方法体没有污染可变参数数组。

示例

以下四个示例依次展示运行时读取、可重复注解、继承边界和类型使用位置。输出来自本地 OpenJDK 21.0.12 对相同源文件的实际编译与运行；示例只使用 Java 21 与 Java 25 都支持的语义。

定义并读取运行时注解

第一个示例把路由方法与路径作为元数据，再按方法名排序后读取。method 有缺省值，调用方只需为非 GET 路由显式提供它。

@Retention(RUNTIME) 是反射读取成功的必要条件，@Target(METHOD) 则让编译器拒绝把 @Route 放到字段上。排序不是注解机制的一部分；getDeclaredMethods() 不承诺返回声明顺序，因此需要稳定输出时必须显式排序。

真实路由器还要处理重复路径、参数绑定、可访问性和调用异常。注解只提供注册所需的描述，不能替代这些运行时策略。

正确展开可重复注解

可重复注解（repeatable annotation） 需要一个容器注解，其 value() 返回重复注解数组。读取逻辑应调用 getAnnotationsByType(Role.class)，让反射 API 统一处理单个注解与容器形式。

import java.lang.annotation.*;
import java.util.Arrays;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Repeatable(Roles.class)
@interface Role {
    String value();
}

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

@Role("reader")
@Role("auditor")
class ReportService {}

public class RepeatableAnnotations {
    public static void main(String[] args) {
        Role[] roles = ReportService.class.getAnnotationsByType(Role.class);
        System.out.println(Arrays.stream(roles)
                .map(Role::value)
                .toList());
        System.out.println(ReportService.class.getAnnotation(Role.class));
        System.out.println(ReportService.class.getAnnotation(Roles.class) != null);
    }
}

[reader, auditor]
null
true

当同一位置写了两个 @Role 时，类文件以容器形式表示它们，所以单数查询 getAnnotation(Role.class) 返回 null。按类型查询会展开容器并保持定义顺序；直接查询容器也能看到它，但会让调用代码依赖存储形式。

容器和重复注解的保留策略与目标必须兼容。只给 Role 写 RUNTIME 而遗漏容器的 RUNTIME 会被编译器拒绝，而不是在运行时悄悄丢失一半契约。

验证 @Inherited 的边界

@Inherited 只改变类上注解的查询规则。它不让实现类继承接口注解，也不让覆盖方法继承父类方法上的注解。

import java.lang.annotation.*;

@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Audited {}

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@interface Operation {}

@Audited
class BaseService {
    @Operation
    public void run() {}
}

class ChildService extends BaseService {
    @Override
    public void run() {}
}

@Audited
interface AuditedContract {}

class ContractService implements AuditedContract {}

public class InheritedAnnotations {
    public static void main(String[] args) throws Exception {
        System.out.println("class: "
                + ChildService.class.isAnnotationPresent(Audited.class));
        System.out.println("interface: "
                + ContractService.class.isAnnotationPresent(Audited.class));
        System.out.println("method: "
                + ChildService.class.getMethod("run")
                        .isAnnotationPresent(Operation.class));
    }
}

class: true
interface: false
method: false

ChildService 没有直接声明 @Audited，但类查询沿直接父类链找到了它。ContractService 的接口路径不参与该规则；ChildService.run() 覆盖方法也需要自己声明 @Operation，除非框架明确实现另一套合并算法。

框架常会扫描接口、桥接方法、父类方法和元注解，从而提供比核心反射更丰富的语义。不要把某个框架的合并规则误写成 Java 语言或 AnnotatedElement 的通用规则。

读取嵌套类型使用注解

最后一个示例把 @NonEmpty 放在 List 的类型实参上。读取路径从方法的带注解返回类型进入参数化类型，再查询第一个类型实参。

import java.lang.annotation.*;
import java.lang.reflect.AnnotatedParameterizedType;
import java.lang.reflect.AnnotatedType;
import java.lang.reflect.AnnotatedElement;
import java.lang.reflect.Method;
import java.util.List;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE_USE)
@interface NonEmpty {}

class MessageApi {
    public List<@NonEmpty String> labels() {
        return List.of("urgent");
    }
}

public class TypeUseAnnotations {
    public static void main(String[] args) throws Exception {
        Method method = MessageApi.class.getMethod("labels");
        AnnotatedType result = method.getAnnotatedReturnType();
        AnnotatedType argument = ((AnnotatedParameterizedType) result)
                .getAnnotatedActualTypeArguments()[0];

        System.out.println(result.getType().getTypeName());
        System.out.println(annotationNames(argument));
        System.out.println(method.getDeclaredAnnotations().length);
    }

    static List<String> annotationNames(AnnotatedElement element) {
        return List.of(element.getAnnotations()).stream()
                .map(annotation -> annotation.annotationType().getSimpleName())
                .toList();
    }
}

java.util.List<java.lang.String>
[NonEmpty]
0

方法声明自身没有注解，所以 getDeclaredAnnotations() 的长度为 0。元数据位于返回类型内部；如果只检查 Method，验证器会漏掉它。

@NonEmpty 仍然不会自动检查列表元素。静态分析器、字节码工具或运行时验证器必须定义并实现其语义，才能把这个类型限定变成诊断或行为。

陷阱

把注解当成行为

修复方法： 找出负责解释注解的具体编译器、处理器、框架组件或应用代码，并为它写一个失败用例。安全控制必须验证未授权请求确实被拒绝，不能只断言反射能看到注解。

忘记缺省保留策略是 CLASS

修复方法： 运行时消费者需要 RUNTIME；只做编译期处理时优先选择 SOURCE 或明确需要的策略。测试消费者所在阶段的可见性，不要只测试源码中存在 @ 标记。

混淆直接、继承与按类型查询

修复方法： 在消费者契约中明确是否接受间接存在、@Inherited 与重复容器。分别测试零个、一个、多个注解，以及父类、接口和覆盖方法边界。

用过宽的目标和警告抑制

修复方法： 只列出消费者真正扫描的 ElementType，并把警告抑制缩到最小声明。每个抑制都应对应一个已理解且无法在该边界消除的警告。

假定处理器会自动运行

修复方法： 在构建中显式配置处理器路径或模块路径，并用 -processor、-proc:full 或 -proc:only 表达处理意图。持续集成应清理生成目录后编译，并断言预期文件或错误确实产生。

随意演进公开注解接口

修复方法： 把注解接口当作公开 API 演进。新增元素通常提供语义安全的缺省值；同时用旧使用方、新使用方、处理器和运行时读取器做兼容性测试。

延伸阅读

• Java 语言规范 25：注解接口
• Java 语言规范 25：注解
• Java 语言规范 25：预定义注解接口
• Java SE 25 API：java.lang.annotation
• Java SE 25 API：AnnotatedElement
• Java SE 25 javac 文档