选错@retention策略会导致注解在目标阶段不可见:source仅存于源码,编译后消失;class保留在字节码但反射不可见;runtime是唯一支持反射的策略,三者间无隐式升级。

选错 @Retention 策略,注解就“看不见”——不是代码写错了,而是生命周期根本没走到那一步。SOURCE、CLASS、RUNTIME 不是简单的“保留时间长短”,而是作用域的硬性断层:每个策略对应一个不可跨越的阶段边界,跨阶段访问必然失败。
SOURCE:只活在.java文件里,编译完就清零
注解仅存在于源码阶段,javac 编译时直接丢弃,字节码中完全不存在。它不参与后续任何环节,连.class文件都搜不到痕迹。
- 适用场景:纯编译期检查或代码生成,比如
@Override、@SuppressWarnings、Lombok 的@Getter - 关键判断:如果你不需要在编译后做任何事(不读取、不增强、不反射),就用 SOURCE
- 常见误用:想用注解驱动构建流程却设为 SOURCE——构建工具根本看不到它
CLASS:进得了.class,进不了JVM内存
注解被写入字节码文件,可通过二进制工具(如 javap)查看,但 JVM 加载类时不会将其加载进运行时元数据。反射调用 getAnnotation() 或 isAnnotationPresent() 必定返回 null 或 false。
- 适用场景:需要在编译后、运行前介入的流程,例如 APT(Annotation Processing Tool)、字节码增强工具(如某些 AOP 框架预处理)、构建时校验
- 关键判断:你依赖的是构建工具或字节码操作库(如 ASM、Byte Buddy),而不是 Java 反射
- 典型信号:IDE 提示 “Annotation is not retained for reflective access” 就是 CLASS 策略的明确标识
RUNTIME:唯一能被反射捕获的注解生命态
注解完整保留在 JVM 运行时的类元数据中,只有 RUNTIME 才支持 Class.getAnnotation()、Method.isAnnotationPresent() 等反射操作。Spring 的 @Autowired、JUnit 的 @Test、自定义定时任务注解都必须走这条路。
- 适用场景:框架动态行为、运行时配置注入、AOP 切面织入、序列化策略控制
- 关键代价:带来额外的内存占用与类加载开销;若注解高频存在且无需运行时访问,应避免滥用 RUNTIME
- 硬性要求:只要反射逻辑存在,注解声明中
@Retention(RetentionPolicy.RUNTIME)就不可省略或替换
三个策略之间没有隐式升级路径。设成 CLASS,不会因为“我后面想反射”就自动变成 RUNTIME;设成 SOURCE,也不会因为“构建工具想扫它”就突然出现在字节码里。断层就是断层,越界即失效。










