如果说注解是Java/Android开发里的一把瑞士军刀那Retention就是这把刀的保险栓。我在系列前两篇聊过注解的基本语法和Target的作用范围后台收到不少留言问得最多的就是“明明加了注解反射却拿不到”、“同事的注解在编译期能跑我的怎么老报错”。这些问题的根源十有八九都出在Retention上。这篇就来把Retention彻底讲透。它决定了一个注解能活多久、能被谁看到、在什么阶段生效是所有自定义注解框架的基石。无论你是刚接触注解的初中级开发者还是正在封装基础库、写注解处理器的高级工程师理解这一层你才能从“会用注解”变成“会设计注解”。1. Retention是什么注解的“保质期”和“曝光度”先别急着背概念。Retention英文直译是“保留”在Java注解体系里它标注的是这个注解能存活到哪个阶段。你可以把它理解成食品包装上的保质期只有三个阶段源码期、编译期、运行期。1.1 三个取值一次讲清楚Java给Retention定义了三个枚举常量分别对应三个生命周期RetentionPolicy.SOURCE注解只保留在源代码里编译后就被丢弃。字节码文件.class里完全没有它的痕迹。RetentionPolicy.CLASS注解会保留到字节码文件里但JVM加载类时不会把它加载进内存运行时通过反射拿不到。RetentionPolicy.RUNTIME注解不仅进字节码还会在运行时被JVM读取反射可以完整拿到注解信息。一句话概括SOURCE是最短命RUNTIME是最长命CLASS是个中间态。这里必须强调一个老生常谈但反复有人踩的坑Retention的默认值是CLASS不是RUNTIME。很多人自定义注解时写完就忘了标Retention结果反射死活拿不到注解折腾半天发现是默认值在作怪。1.2 深入JVM层面看Retention的真实作用只看枚举定义不够得往字节码层面看一眼。如果用javap -v查看一个标有MyAnnotation的类字节码你会看到RuntimeVisibleAnnotations和RuntimeInvisibleAnnotations这两个属性。名字翻译过来就是“运行时可见注解”和“运行时不可见注解”。Retention(RUNTIME)的注解会进入RuntimeVisibleAnnotationsJVM在类加载时会解析保存反射APIgetAnnotation、getAnnotations能读取到。Retention(CLASS)的注解则进入RuntimeInvisibleAnnotations它存在于class文件里但JVM运行时不会保留反射看不到。Retention(SOURCE)则彻底不写入这些属性class文件里直接消失。理解了这一层你就明白为什么说Retention是“曝光度”了——它决定了注解信息在哪个环节对谁可见。1.3 Android环境下Retention的特殊考量理论上Java和Android的注解机制一致但Android的构建链路更长混淆、资源压缩、多模块编译、R8优化都会介入所以Retention的选型在Android上更敏感。举两个场景如果你的注解是给注解处理器AnnotationProcessor或KSP在编译期消费的那用SOURCE或CLASS都行选了RUNTIME反而会让无用的注解信息进入APK增大包体积。如果你的注解需要在运行时通过反射读取那必须用RUNTIME否则R8在开启资源缩减时很可能把RuntimeInvisibleAnnotations直接剥离掉你就会遇到“debug包正常、release包反射返回null”的经典问题。提示Android里混淆规则要额外注意-keepattributes *Annotation*。但即使保留了注解属性CLASS策略的注解依然无法被反射读取这两者的区别很多人混淆。2. 实战中到底怎么选一张决策表搞定八成选型我自己写框架和工具类时有一个简单的决策流程分享给大家这个注解是给谁看的给IDE看、给编译器做语法检查 →SOURCE给字节码工具、插桩框架、代码生成器看 →CLASS给运行时、反射、动态代理看 →RUNTIME这个注解需要进APK吗不需要 →SOURCE优先需要但不用反射 →CLASS需要反射 →RUNTIME2.1 SOURCE只在源码期工作的注解SOURCE级别的注解编译后灰飞烟灭适合做“代码标注型”和“编译期检查型”功能。最经典的例子是Java标准库里的Override和SuppressWarnings它们是源码期注解编译器看到Override会检查父类方法是否真的存在看到SuppressWarnings就压制对应警告但产物里完全不存在这些注解。Android开发中IntDef和StringDef也是SOURCE策略的典型。它们用来替代枚举提供编译期常量检查但不会像Enum那样带来额外的内存开销。比如你定义一个状态值IntDef({STATUS_IDLE, STATUS_LOADING, STATUS_SUCCESS, STATUS_ERROR}) Retention(RetentionPolicy.SOURCE) public interface LoadStatus {} public static final int STATUS_IDLE 0; public static final int STATUS_LOADING 1; public static final int STATUS_SUCCESS 2; public static final int STATUS_ERROR 3;然后在方法参数上标注LoadStatusIDE和编译器就会帮你检查传入的值是否合法但编译产物里不会留下任何注解信息零运行时开销。2.2 CLASS字节码时代的注解CLASS策略比较特殊它保留到class文件但运行时反射不可见。这就导致它在纯Java环境下既不能给编译器当“一次性工具”又不能给反射当“运行期数据源”看起来有点尴尬。实际上CLASS的主要消费方是字节码操作框架比如ASM、Javassist、AspectJ、Lancet这类工具。它们在编译期或打包期直接读写字节码从RuntimeInvisibleAnnotations里读取注解信息进而修改字节码或动态生成代码。举一个真实场景很多性能监控SDK会定义一个TraceMethod注解标记需要插桩的方法。这个注解放在CLASS级别编译完成后Gradle插件里的Transform或ASM在扫描字节码时找到这些注解标记然后往方法体里插入耗时统计代码。等App运行时注解的信息已经被“翻译”成实际代码逻辑了不需要反射参与效率更高。2.3 RUNTIME运行时反射的最后一张牌RUNTIME是大家最熟悉的级别因为你要用反射API读取注解就必须用它。但它的代价也很清晰注解信息会常驻内存反射读取有一定性能开销。经典案例就是各种依赖注入框架、ORM框架、事件总线框架。比如ButterKnife虽然现在不太用了、Retrofit的接口注解、Room的实体注解很多都是RUNTIME策略。这些框架需要运行时候读取注解里的参数生成对应的调用逻辑。不过要注意Android上运行时反射有性能损耗尤其是启动阶段要是几百个类都去反射读注解会造成明显的卡顿。这也是为什么现在很多新框架开始偏向编译期注解处理KSP/APT把注解处理前置到编译期运行时不再依赖反射。我见过不少项目组图省事把自定义注解一律标成RUNTIME最后卡顿排查发现是反射读注解太多导致的。所以我的建议是能编译期处理就不要拖到运行时。2.4 选型对比表为了方便对照我整理了一张表大家可以直接抄作业策略存活范围反射可见包体积影响典型应用场景SOURCE源码期否无Override、IntDef、IDE提示、编译期校验CLASS字节码期否JVM加载后不可见保留在class中ASM插桩、字节码增强、代码生成RUNTIME运行期是完整保留反射框架、依赖注入、运行时动态逻辑3. 坑与排查Retention相关的高频问题实录这块是我最想写的全是实际工程里摔过的跤。很多问题表面上看是“注解不好使”排查到最后都是Retention选错了或者细节没注意。3.1 反射拿不到注解先看Retention是不是RUNTIME现象自定义了一个注解按网上教程写了反射读取的代码结果运行起来getAnnotation始终返回null。排查思路很简单先看注解定义有没有加Retention(RetentionPolicy.RUNTIME)。没加就是默认的CLASS反射必拿不到。再看注解是否标在了正确位置。比如Target限定的是FIELD你却标在方法上那肯定也读不到。最后看是不是混淆把注解类干掉了。release包反射失效多半是R8的问题记得在proguard-rules.pro里加-keep interface 你的注解类同时保留注解属性。我自己踩过最隐蔽的一个坑注解类被混淆时改了包名而反射代码里写的是硬编码的字符串类名结果不仅返回null还直接ClassNotFoundException。3.2 编译警告“部分重新编译的编译结果可能不准确”标题热词里有一条错误信息“java: jps 增量注解进程已禁用”。这个在Android Studio的Gradle构建里很常见尤其是JDK版本升级或注解处理器配置有问题时。这个警告的意思其实就是jpsJava Virtual Machine Process Status Tool的增量编译注解处理被禁用可能造成注解处理结果不准确。表面上看只是警告但如果你的项目依赖注解处理器生成代码比如dagger、room、butterknife编译器就可能导致“明明编译通过但运行时找不到生成的类”这种诡异问题。处理办法在gradle.properties里检查是否误关了增量编译比如android.enableJetifier之类的配置不要乱动。升级或统一JDK版本避免多个JDK混用。如果用了KAPTKotlin注解处理在build.gradle里可以显式配置kapt.useBuildCache true并清理构建缓存。注意这个警告和Retention本身关系不大但它是“注解相关构建问题”的高频元凶我把它放进来是想提醒大家注解工作流不光是写代码构建配置也是重灾区。3.3 R8/ProGuard对Retention的影响前面提过混淆是Android特有的大坑。我在项目里遇到过这种场景一个PermissionNeed注解用于标记需要动态申请权限的方法。debug包一切正常release包反射注解直接返回空。查了半天发现两个原因叠加一是R8默认会移除未被使用的注解属性除非你配置-keepattributes *Annotation*。二是注解类本身被混淆类名变了反射代码如果按原类名查找就会失败。正确的混淆规则应该长这样-keepattributes *Annotation* # 保留自定义注解类防止混淆类名 -keep interface com.yourpackage.annotation.*如果你的注解是RUNTIME策略且需要被外部SDK读取建议把它放在独立的module或jar里并在消费方的混淆配置中也加上对应的-keep规则。3.4 框架源码里的Retention默认值为什么很多框架都标RUNTIME很多人看Retrofit、EventBus这类框架源码时会发现它们内部自定义的一堆注解好多都标了RUNTIME于是形成惯性思维“框架注解就是RUNTIME”。这里要辩证看。Retrofit的方法注解GET、POST确实有大量RUNTIME因为它的ServiceMethod需要运行时解析接口方法上的注解来构建请求。但注解解析不是每次都发生的而是create()时缓存好的所以性能问题被缓解了。EventBus的Subscribe则比较特殊早期版本通过反射扫描注解后来版本改成了编译期注解处理器。这正体现了一种演进趋势能用编译期解决的绝不拖到运行时。所以我给大家一个更细致的建议组件内部自己消费的注解优先源码期/编译期。需要提供给外部开发者配置参数的注解可以考虑运行时。如果框架在运行时有复杂的动态逻辑合理使用缓存别每次都反射扫描。4. 深入一步Retention选型后的实战设计最后环节我拿两个真实的自定义注解例子把前面讲的概念串起来跑一遍。4.1 案例一实现一个LogMethod方法耗时注解RUNTIME实战需求给目标方法标一个LogMethod注解运行时输出该方法的执行耗时。这种功能用RUNTIME最直接。注解定义Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) public interface LogMethod { String tag() default MethodMonitor; boolean printParams() default false; }使用示例public class UserService { LogMethod(tag UserService, printParams true) public String getUserInfo(int userId) { // 模拟耗时操作 try { Thread.sleep(200); } catch (InterruptedException e) { e.printStackTrace(); } return User userId; } }通过代理或反射工具调用来读取注解并统计耗时public class MethodLogger { public static Object invoke(Object target, Method method, Object... args) throws Exception { LogMethod logMethod method.getAnnotation(LogMethod.class); long start System.currentTimeMillis(); try { return method.invoke(target, args); } finally { if (logMethod ! null) { long cost System.currentTimeMillis() - start; Log.i(logMethod.tag(), method.getName() cost: cost ms); } } } }这样设计的好处是清晰、直观、无侵入。坏处是必须走反射调用没法直接作用于项目里已有的直接调用点。如果你想拦截已有方法就得考虑字节码插桩这时注解就要换成CLASS策略。4.2 案例二配合注解处理器生成代码SOURCE/CLASS实战编译期注解处理器是现在更推荐的做法。以GenerateFactory为例让注解处理器在编译期自动生成工厂类代码源码阶段就完成逻辑运行时零反射开销。Target(ElementType.TYPE) Retention(RetentionPolicy.SOURCE) public interface GenerateFactory { String name(); }处理器里通过AbstractProcessor捕获标有GenerateFactory的类然后生成对应的工厂代码。整个流程中注解只活在编译期打包后彻底消失。这种方案在性能敏感的大型项目里越来越主流。有很多人问我SOURCE和CLASS在这种场景下怎么选。我的经验是如果注解处理器在process()阶段已经把信息消费完之后不需要读取class文件里的注解那用SOURCE就够了还能减少class文件体积如果你的注解除了处理器要用还有其他字节码工具在后续阶段要用比如Transform插桩那就选CLASS。4.3 案例三自定义注解属性与SpEL表达式有些框架比如Spring的注解属性支持SpEL表达式比如EventListener(condition #root.args.length 1)。这在Android里不常见但思路可以借鉴。核心就是把字符串表达式写在注解属性里运行时用表达式引擎解析。要做这个功能注解必须是RUNTIME因为你运行时还要读取属性值再解析。这也是一个典型的“选型由消费时机决定”的例子——消费发生在运行期所以必须让注解活到运行期。不过表达式解析本身有开销建议在反射读取时做一次缓存比如用MapMethod, Expression缓存编译后的表达式对象避免每次调用都重新解析。在Android项目中如果想引入类似能力可以集成轻量级表达式引擎或者自己写一个简单的解析器。整体思路就是注解负责描述“规则”运行时引擎负责“解释规则”。4.4 关于注解处理器与KSP的补充Hilt、Room、Compose编译器这些框架都在从KAPT迁移到KSP本质上是提升了注解处理的效率。KSP直接分析Kotlin语法树性能比KAPT生成Java stub再走APT好很多。但不管APT还是KSP都属于编译期注解处理注解的Retention通常设为SOURCE或CLASS。很多开发者以为“编译期处理注解设不设Retention无所谓”这不对。虽然注解处理器确实能扫到源码里的注解但如果你希望IDE在检查错误、甚至其他编译插件在后续阶段也能读取注解保留CLASS会稳妥一些。5. 关于Retention的几条最终经验做了这么多年框架和SDK开发我总结几条Retention相关的硬经验大家直接拿走拿不准的时候先看注解的消费者是谁千万不要因为“写着方便”而选RUNTIME。反射读取注解一定要做缓存尤其是框架型代码。Class和Method的元数据是稳定的缓存掉不会出错。Android项目编译期处理注解时留意KAPT/KSP的配置以及增量编译是否被禁用。干净的构建往往能消除一大批“诡异问题”。混淆规则必须和注解定义同步维护。不要等到release包出问题再补规则而是在提交自定义注解代码的同时就把-keep规则写好。Retention看起来只是注解定义上方的一行标注但它决定了你整套注解机制在哪个环节“活”、在哪个环节“死”。把这个维度和之前聊的Target注解能标在哪结合起来你对自定义注解的设计能力就能有一个肉眼可见的跨越。下一篇我会继续聊注解处理器的完整实现流程包括如何发布一个自己的编译期注解库感兴趣的话可以接着看。
