跳到主要内容
约 9 分钟3 张卡

Java 注解

注解(annotation)是附加在类、方法、字段等程序元素上的结构化元数据,也就是描述这些元素的额外信息,比如「调用这个方法需要 admin 角色」。注解只提供信息,编译器、字节码工具或框架读取后,才会执行相应的检查或操作。

因此,写了注解却没有生效时,要先查谁负责读取它,再查它是否保留到了读取的阶段。保留策略决定能不能读到,读取方的逻辑决定读到之后做什么。

1. 面试核心​

先记住这几条,再读正文
  • 注解只保存元数据,编译器、字节码工具或框架读取后才执行对应行为。卡 · 注解定义
  • SOURCE 注解只保留在源码中,CLASS 注解写入类文件,RUNTIME 注解还能在运行时通过反射读取。卡 · @Retention
  • 未声明 @Retention 时,保留策略默认为 CLASS;@Target 约束注解的使用位置。
  • @Inherited 只让类注解沿超类链被查到,接口和成员上的注解不在这个范围内。
  • getAnnotationsByType 会展开重复注解的容器,getAnnotation 不会。卡 · 重复注解的运行时读取

2. 注解定义​

自定义注解要先声明注解类型,再定义它能保存哪些配置。Java 用 @interface 定义注解类型:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Documented
public @interface RequiresRole {
String value();
}

注解元素是注解声明的配置项,value() 就声明了一个 String 类型的角色名称。开头的三个注解用于配置注解类型本身,称为元注解,具体规则见第 3 节。使用 RequiresRole 时,给 value 提供值:

@RequiresRole("admin")
public void deleteUser(long userId) {
// ...
}

这里的 "admin" 保存到 value 元素里。元素名为 value,并且其他元素都有默认值时,可以省略元素名,直接写值。

元素还可以声明默认值,使用方只需要填写想改的配置:

public @interface Retry {
int maxAttempts() default 3;
long delayMillis() default 100;
}

直接写 @Retry 不带参数时,maxAttempts 为 3,delayMillis 为 100。这个定义只展示默认值;如果后续要通过运行时反射读取,还需要声明 @Retention(RetentionPolicy.RUNTIME)。

注解元素的类型有限制:只能是基本类型、String、Class、枚举、注解,以及这些类型的一维数组。元素值和默认值都不能是 null,所以「可选」的配置要用一个明确的默认值来表达,比如空字符串或空数组。

3. 元注解​

元注解是标在注解类型上的注解,用来描述注解类型本身:它能放在哪里、保留到什么阶段、能不能重复使用。编译器和读取工具都依据这些信息处理注解。

3.1 @Target​

@Target 限制注解能用在哪些位置,用错地方编译器会直接报错。例如:

@Target({ElementType.TYPE, ElementType.METHOD})

它表示注解可以放在类型和方法上。其他常用目标还有字段、构造方法、参数、局部变量、类型参数和类型使用位置。

未声明 @Target 时,注解可以用在所有声明位置,包括类型参数声明,但不能用在类型使用位置,比如 List<@NotNull String> 里的元素类型;要用在这里,需要显式声明 TYPE_USE。明确写出目标,编译器才能尽早拦住误用。

3.2 @Retention​

@Retention 决定注解保留到哪个阶段。需要在运行时读取的注解,这样声明:

@Retention(RetentionPolicy.RUNTIME)

保留策略有三种:

策略源码中存在class 文件中存在运行时反射可见常见用途
SOURCE是否否编译检查、源码处理
CLASS是是否字节码分析和转换
RUNTIME是是是运行时框架读取

没有声明 @Retention 时,默认策略是 CLASS。

选哪种,取决于谁在什么时候读取注解。只供当前这次编译使用,SOURCE 就够了;后续还有工具要分析类文件,至少要保留到 CLASS;框架要在运行时通过反射读取,就必须用 RUNTIME。

例如,一个权限注解忘了声明 @Retention,它会按默认的 CLASS 写进类文件,反射却读不到。如果读取方约定「有注解才检查权限」,这次检查就会被跳过。

3.3 @Documented​

带 @Documented 的注解会出现在 Javadoc 等文档工具为被标注元素生成的公开文档里。它只影响文档,不改变运行时行为。

3.4 @Inherited​

@Inherited 让子类能查到父类上的类注解。注解同时保留到运行时,Class.getAnnotation 才会沿超类链往上找。

它的查找范围很窄:

  • 只对标在类上的注解有效。
  • 在实现类上查询时,会跳过接口上的注解,接口注解要由框架另外搜索。
  • 父类方法或字段上的注解仍然只属于原来的成员,子类里对应的成员要单独处理。
  • 用 getDeclaredAnnotation 查询时只看当前类,不沿超类查找。

框架要合并接口、方法和组合注解上的配置,需要自己实现搜索规则。

3.5 @Repeatable​

@Repeatable 允许在同一个程序元素上多次使用同一种注解。编译器会把这些注解实例放进一个容器注解里保存,所以要同时定义两种注解:

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

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

@Role("reader")
@Role("editor")
final class DocumentService {}

DocumentService 上写了两个 @Role,编译后实际保存的是一个 @Roles,它的 value 里装着这两个 Role。运行时怎样读取,见第 6 节。

4. 注解的处理阶段​

同一个注解有什么效果,完全取决于读取它的工具。按读取的时间,可以分成编译阶段、类文件处理阶段和运行阶段,每个阶段需要的保留策略不同。

4.1 编译阶段​

编译阶段可以根据注解检查源码,或者提前生成运行时需要的代码。比如 @Override 让编译器检查方法是否真的重写了父类方法,@SuppressWarnings 用来抑制指定的警告。注解处理器是挂在编译器上的插件,它可以读取程序元素、报告编译错误,或者生成新的源码和资源文件。

MapStruct 就用注解处理器生成映射代码。Lombok 也参与编译过程,但它修改的是编译器内部的语法树,也就是编译器表示源码的结构,而不是生成新文件。两者的区别见 Java 注解处理器。

@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
public @interface GenerateMapper {}

处理器只在编译时读取 @GenerateMapper,所以 SOURCE 就够了。生成的类会作为普通代码继续编译,运行时用不到这个标记。

4.2 class 文件处理阶段​

CLASS 注解写入类文件,供后续的字节码工具分析和修改代码,比如静态分析、插桩和字节码变换。插桩是往已有的字节码里插入额外逻辑,例如记录方法耗时。

类文件把运行时可见和不可见的注解分别存在不同的属性里。反射 API 只返回运行时可见的注解,所以 CLASS 注解只能由字节码工具解析对应的属性来读取。

4.3 运行阶段​

RUNTIME 注解可以在运行时通过反射读取。下面是框架读取 @RequiresRole 的简化写法:

Method method = UserService.class
.getDeclaredMethod("deleteUser", long.class);

RequiresRole rule = method.getAnnotation(RequiresRole.class);

if (rule != null) {
authorization.check(rule.value());
}

注解只提供了角色名称,真正做权限校验的是 authorization.check。如果没有任何代码读取这个注解,@RequiresRole 不会阻止任何人调用 deleteUser。

Spring 的 @Transactional 也是这样:框架读取注解里的配置,在代理调用中控制事务。具体过程见 Spring 事务。

5. 自定义注解设计​

设计自定义注解,要同时设计配置和读取它的逻辑。动手之前先回答这几个问题:

  1. 谁读取这个注解:编译器插件、构建工具还是运行时框架?
  2. 标记放在哪些元素上?
  3. 注解元素表达的是稳定配置,还是本该由普通代码完成的业务逻辑?
  4. 重复使用、继承和组合时采用什么规则?
  5. 配置无效时在编译期还是运行时报告错误?

前两个问题直接决定 @Retention 和 @Target 怎么写。注解适合表达简短、静态、和程序元素紧密相关的元数据;复杂条件、动态查询和控制流,用普通的对象和方法表达更清楚。

5.1 元数据与执行逻辑​

注解负责保存配置,读取方负责执行。以重试为例,注解声明最大尝试次数和间隔:

@Retry(maxAttempts = 3, delayMillis = 200)
void callPayment() {}

要让 callPayment 按这些配置重试,还得有拦截器或显式的调用器:它读取 @Retry,捕获允许重试的异常,等待 delayMillis 指定的间隔,再调用一次 callPayment。通过反射读取时,Retry 必须保留到运行时。

但注解里的两个数字不足以让重试安全,还要明确三条业务规则:

  • 操作是否幂等,也就是重复调用会不会产生额外的业务结果。比如扣款不幂等,重试可能扣两次。
  • 哪些异常可以重试。临时连接失败可以,参数错误重试多少次都一样失败。
  • 总超时是多少,等待时间和多次调用都要算进去。

5.2 注解默认值​

默认值会影响所有省略这个元素的使用点。业务源码一行没改,只要读取方换了新版本的注解、默认值变了,行为就跟着变。所以公开的注解要写清默认值的含义,危险的操作则不提供默认值,要求调用方显式配置。

6. 重复注解的运行时读取​

重复注解要用 getAnnotationsByType 读取。重复使用 @Role 时,编译器用 @Roles 保存多个实例,所以 Role 和 Roles 都要声明为 RUNTIME,运行时才读得到:

Role[] roles = DocumentService.class.getAnnotationsByType(Role.class);
System.out.println(roles.length); // 2

getAnnotationsByType(Role.class) 会把 @Roles 容器展开,所以无论元素上写了一个还是多个 @Role,都能用同一种方式读取。getAnnotation(Role.class) 不展开容器,对 DocumentService 来说,类上直接存在的只有 @Roles,它就找不到 Role。

7. 常见问题​

7.1 为什么反射获取不到自定义注解?​

先检查注解是否声明了 RetentionPolicy.RUNTIME,没有声明就是默认的 CLASS,反射读不到。再检查读取的元素对不对:类注解、方法注解和字段注解属于不同元素;父类、接口和重写方法上的注解,也不会按同一套规则自动继承下来。

7.2 注解可以继承另一个注解吗?​

7.3 修改注解值后,程序什么时候使用新配置?​

7.4 @Inherited 为什么对接口无效?​

8. 面试题卡片​

9. 参考资料​

来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明