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. 自定义注解设计
设计自定义注解,要同时设计配置和读取它的逻辑。动手之前先回答这几个问题:
- 谁读取这个注解:编译器插件、构建工具还是运行时框架?
- 标记放在哪些元素上?
- 注解元素表达的是稳定配置,还是本该由普通代码完成的业务逻辑?
- 重复使用、继承和组合时采用什么规则?
- 配置无效时在编译期还是运行时报告错误?
前两个问题直接决定 @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 注解可以继承另一个注解吗?
不能。注解类型用 @interface 声明,不能用 extends 继承别的注解。常见的替代做法是把注解标在另一个注解上,由框架递归读取这些标记,这就是组合注解。组合注解怎样解析,由框架自己规定。
7.3 修改注解值后,程序什么时候使用新配置?
源码里的注解值改了,正在运行的程序不会自动跟着变。需要重新编译,并让读取方使用新产物;具体生效时机取决于读取阶段:
- 编译期处理器读取的注解,要重新编译,才能生成使用新配置的代码。
- 启动时扫描并缓存注解的框架,要重启或重新扫描。
- 每次调用时都读取注解的代码,使用的是当前已加载的注解信息;只改源码不会改变这个结果。
7.4 @Inherited 为什么对接口无效?
因为 @Inherited 只查类的超类链,而超类链是单一的。一个类可以实现多个接口,接口还能继承多个接口;如果要合并这些接口上的注解,就得规定冲突时用哪一个、按什么顺序搜索。语言没有定义这些规则,交给框架自己决定。
8. 面试题卡片
9. 参考资料
- Java Language Specification:Annotation Interfaces
- Java API:Retention
- Java API:RetentionPolicy
- Java API:Target
- Java API:AnnotatedElement
- MapStruct:Reference Guide
- Lombok:Execution Path
来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明