1. 从“注释”到“注解”一个容易被忽略的认知缺口做技术评审做久了我经常发现一个很有意思的现象很多Java开发同学写Override、Autowired、Transactional非常熟练可一旦被问到“这些注解是怎么被定义出来的”“为什么有的注解在反射里能拿到、有的拿不到”就开始含糊其辞。要么说“元注解就是定义注解的注解”然后一个字也讲不出来要么把Retention三个枚举值背得滚瓜烂熟却不知道默认值是CLASS这个坑。这篇源码解读我打算把JDK自带的五个常用元注解——Retention、Target、Documented、Inherited、Repeatable从源码定义到字节码表现再到框架里的实际解析方式完整拆一遍。看完之后你不仅能写出规范的自定义注解还能真正理解Spring那些“组合注解”为什么能生效以及反射读取注解时的各种边界问题。先说清楚一个概念层面的问题标题里写的是“元注释”但在Java语境中我们常说的“注释”一般指//和/* */这种代码注释而打头的Annotation更准确的译法叫“注解”。很多老教材把Annotation翻译成“注释”于是“元注释”“注解元数据”这类词混在一起理解成本直接翻倍。我建议统一用“注解”来区分元注解就是“注解的注解”专门用来约束一个自定义注解的保留时机、目标位置、文档行为、继承行为和重复使用行为。为什么需要元注解做个假设如果Java没有元注解机制那么Permission(role ADMIN)这种注解你没法控制它到底能标在类上还是方法上也没法控制它能不能被运行时反射读到更没法约束子类继承时会不会带上。元注解就是一套“给注解定规矩”的语法层约束通道。它最精妙的设计在于元注解本身也是普通注解只是它们的Target值都是ElementType.ANNOTATION_TYPE表示它们只能出现在“注解声明”上。理解了这一层再看框架源码里的各种自造注解你会觉得整个世界都通透了。还有一个背景要知道JDK 5第一次引入注解时元注解只有Retention、Target、Documented、Inherited这四个JDK 8为了支持重复注解新增了Repeatable。所以现在标准的元注解其实是五个。下面我按它们在JDK源码里的真实样貌逐个拆解。2. 五把钥匙的源码解读JDK里元注解到底写了什么2.1 Retention字节码里决定生死的“保留策略”打开JDK源码里java.lang.annotation.Retention这个接口你会看到这样一段定义Documented Retention(RetentionPolicy.RUNTIME) Target(ElementType.ANNOTATION_TYPE) public interface Retention { RetentionPolicy value(); }这里有三层信息值得细品。第一Retention本身也是个注解而且它的Target是ElementType.ANNOTATION_TYPE也就是说只有注解声明才能使用它普通类、方法、字段上标Retention编译器会直接报错。第二它的唯一成员value()的类型是RetentionPolicy枚举。这个枚举一共只有三个常量SOURCE注解只存在于源码阶段编译成.class文件时直接被丢弃。CLASS注解会写进.class字节码但JVM加载类的时候不保留运行时反射拿不到。RUNTIME注解不仅写进字节码JVM运行期也会保留可以通过getAnnotation()、getAnnotations()等反射API读取。第三Retention自己用的保留策略是RUNTIME这保证了我们后续通过反射读取其他注解时也能看到Retention本身的信息。不要小看这个递归设计很多框架就是靠扫描“注解上的注解”来识别扩展点的。这里必须强调一个实战里最常见的坑**自定义注解不写Retention时默认值是CLASS不是RUNTIME。**也就是说你辛辛苦苦定义了一个注解也标到了类上但想在运行时用反射去读结果是null。很多人排查半天找不到原因其实就是这四个字母的差距。2.2 Target用ElementType枚举圈定使用范围再看java.lang.annotation.Target的源码Documented Retention(RetentionPolicy.RUNTIME) Target(ElementType.ANNOTATION_TYPE) public interface Target { ElementType[] value(); }注意value()的类型是ElementType[]是个数组不是单个值。为什么设计成数组因为一个注解完全有可能既允许标在类上又允许标在方法上。比如Spring的Transactional可以同时用在类级别和方法级别靠的就是Target({ElementType.TYPE, ElementType.METHOD})。ElementType枚举在JDK 8之前只有八种取值枚举值限制位置TYPE类、接口、枚举、注解类型FIELD字段、枚举常量METHOD方法PARAMETER方法参数、构造器参数CONSTRUCTOR构造器LOCAL_VARIABLE局部变量ANNOTATION_TYPE注解类型PACKAGE包JDK 8新增了TYPE_PARAMETER泛型类型参数和TYPE_USE类型使用处JDK 9加入MODULEJDK 16又加了RECORD_COMPONENT对应record组件的声明位置。这说明元注解的设计是跟着语言特性走的新增的类型使用场景都会反映到ElementType里。还有一种容易被忽略的情况如果自定义注解完全不写Target那么它可以被用在几乎所有位置。这种“无限自由”其实很危险等于把校验责任全部推给使用者。一个成熟的注解设计应该用Target把目标位置收窄让编译器帮你提前拦截错误用法。2.3 Documented与Inherited两个容易被低估的空注解Documented的源码简单得让人怀疑它是来凑数的Documented Retention(RetentionPolicy.RUNTIME) Target(ElementType.ANNOTATION_TYPE) public interface Documented { }一个成员方法都没有标注任何业务信息都不行。那它起什么作用作用发生在Javadoc生成阶段如果自定义注解标了Documented那么当它出现在某个类或方法上时Javadoc生成的API文档里会把这个注解展示出来如果不标文档里就看不到它。很多开源库作者喜欢在自定义注解上加Documented就是为了让使用者在查看API文档时能直观地看到哪些注解是框架支持的。java.lang.annotation.Inherited也是个空注解Documented Retention(RetentionPolicy.RUNTIME) Target(ElementType.ANNOTATION_TYPE) public interface Inherited { }它的语义稍微绕一些如果一个注解被Inherited标注并且被用在某个父类上那么子类继承父类时会自动“继承”父类上的这个注解。这里有两个硬边界必须记住第一它的作用域只针对“类”这个级别准确说是ElementType.TYPE第二对接口、方法、字段全部无效。我见过不少同学在接口方法上标了带Inherited的注解指望实现类方法自动继承结果运行时怎么都读不到。这是对Inherited语义最典型的误读后面我会专门演示验证过程。2.4 Repeatable让同一个注解可以出现多次JDK 8新增的Repeatable源码定义如下Documented Retention(RetentionPolicy.RUNTIME) Target(ElementType.ANNOTATION_TYPE) public interface Repeatable { Class? extends Annotation value(); }它的价值在于让同一个注解可以在同一个目标上重复声明。比如Schedule(day MON) Schedule(day FRI)放在同一个方法上。JVM底层会把多个重复注解塞进一个容器注解里容器注解必须用value()方法返回原始注解类型的数组。设计时少有人注意的一点容器注解的Target和Retention范围必须能覆盖原始注解。比如原始注解允许标在TYPE和METHOD上容器注解却不允许METHOD那么一旦在方法上重复标注编译器就会直接报错。源码层面的Target(ANNOTATION_TYPE)只是约束Repeatable本身而它背后的“容器注解校验规则”才是真正决定能否编译通过的根因。3. RetentionPolicy的源码级对比SOURCE、CLASS、RUNTIME的边界与取舍3.1 三个枚举值在字节码层面到底差在哪儿很多文章讲Retention只停留在“源码里有没有、字节码里有没有”的层面这不够。我建议你亲手做一次反编译验证感受会更深。先准备三个注解保留策略分别对应SOURCE、CLASS、RUNTIMERetention(RetentionPolicy.SOURCE) public interface SourceLevel { } Retention(RetentionPolicy.CLASS) public interface ClassLevel { } Retention(RetentionPolicy.RUNTIME) public interface RuntimeLevel { }然后写一个使用类SourceLevel ClassLevel RuntimeLevel public class DemoModel { }编译之后执行命令javap -v DemoModel.class | grep -A2 -i annotation输出会清晰地展示差异SourceLevel在字节码里完全找不到对应属性像是从未存在过。ClassLevel出现在RuntimeInvisibleAnnotations属性里说明它存在于字节码中但JVM运行时不可见。RuntimeLevel出现在RuntimeVisibleAnnotations属性里JVM运行期会保留反射可以正常读取。理解这一层你才能明白为什么Lombok能把Getter、Setter设为SOURCE它们只在编译期起作用让注解处理器生成代码所以产物字节码里干干净净。而业务运行时需要反射读取的注解比如Spring的Transactional、MyBatis的Select、JUnit的Test清一色都是RUNTIME。3.2 实践中的取舍原则我自己的选择习惯基本可以浓缩成一张表保留策略源码阶段字节码阶段运行时反射典型使用场景SOURCE有无拿不到编译期注解处理器、Lombok风格工具注解CLASS有有拿不到字节码增强工具但实战频率很低RUNTIME有有能拿到Spring、MyBatis、业务自定义注解这其中CLASS是一个比较尴尬的中间档。愿意为“字节码处理工具”专门设计自定义注解的场景其实不多而只要你想运行时读注解CLASS就必然拿不到。所以绝大多数业务自定义注解请直接显式写成Retention(RetentionPolicy.RUNTIME)不要依赖默认值也不要为了省一行代码留隐患。顺带说一个性能相关的认知RUNTIME注解能为反射读到是因为JVM在类加载阶段为它维护了对应的注解元数据这确实有一点内存和扫描成本但这个成本远远没有你想象中那么大。实践中真正影响反射性能的是频繁使用getDeclaredField、setAccessible(true)这类操作而不是注解本身。合理的做法是做好缓存比如把注解元数据在静态Map里存一份避免每次校验都重新反射。4. 从源码走向实战用元注解设计一个“必填字段校验”注解源码讲再多不如写一个能跑的案例。假设有这样一个业务场景接口入参对象RegisterRequest里有username、email、phone三个字段我们希望表达“这三个字段至少要有一个不能为空”。用自定义注解来建模。4.1 第一步定义带Repeatable的RequiredField注解首先定义校验限制注解并让它可重复使用Documented Retention(RetentionPolicy.RUNTIME) Target(ElementType.TYPE) Repeatable(RequiredFields.class) public interface RequiredField { String field(); String message() default 字段不能为空; }这里我用了一套组合Retention(RUNTIME)保证运行时可反射读取Target(TYPE)表示注解只能标在类上避免被误用到方法或字段上Repeatable(RequiredFields.class)表示允许一个类上同时声明多个RequiredField。4.2 第二步定义容器注解Documented Retention(RetentionPolicy.RUNTIME) Target(ElementType.TYPE) public interface RequiredFields { RequiredField[] value(); }容器注解的value()必须返回原始注解类型的数组这一点可以从Repeatable源码里的Class? extends Annotation value()直接推出来。容器注解的Retention和Target范围要大于等于原始注解否则编译期就会报错。4.3 第三步实现基于反射的校验器校验器核心逻辑很简单先拿到类上所有的RequiredField注解再逐个检查指定字段是否为空。这里的关键在于JDK 8之后可以直接用getAnnotationsByType来拿到展开后的重复注解它会在底层自动解析容器注解代码不需要手动去拆RequiredFields数组。public class RepeatableValidator { public static ListString validate(Object obj) throws Exception { ListString errors new ArrayList(); Class? clazz obj.getClass(); RequiredField[] rules clazz.getAnnotationsByType(RequiredField.class); for (RequiredField rule : rules) { String fieldName rule.field(); Field field clazz.getDeclaredField(fieldName); field.setAccessible(true); Object value field.get(obj); if (value null || value.toString().trim().isEmpty()) { errors.add(fieldName rule.message()); } } return errors; } }4.4 第四步验证与边界观察构造带注解的请求类RequiredField(field username, message 用户名不能为空) RequiredField(field email, message 邮箱不能为空) public class RegisterRequest { private String username; private String email; }写一段测试调用RegisterRequest request new RegisterRequest(); request.email testexample.com; ListString errors RepeatableValidator.validate(request); System.out.println(errors); // 输出[username 用户名不能为空]如果你把username和email都设为空错误列表就会有两条。再把Target(ElementType.TYPE)改成Target(ElementType.FIELD)标在类上时编译期直接报错。这种把错误前移到编译期的能力就是Target最现实的价值。这个例子还可以继续扩展支持嵌套对象递归校验、支持把校验规则集中到注解接口上、结合Spring AOP在Controller入口统一执行。但不管怎么演进元注解的组合方式都离不开上面这一套。5. 框架世界里的元注解解读Spring等框架为什么能识别你的注解5.1 Spring的组合注解设计Spring源码里藏着大量元注解实践最典型的就是ServiceTarget(ElementType.TYPE) Retention(RetentionPolicy.RUNTIME) Documented Component public interface Service { }Service被Component修饰所以Spring的类路径扫描机制看到Service就等于看到了Component从而把它注册成Bean。这就是“组合注解”的雏形。RestController组合了Controller和ResponseBodySpringBootApplication组合了SpringBootConfiguration、EnableAutoConfiguration、ComponentScan。这里有一个很多人不知道的内部机制Spring在运行时读取注解并不依赖JDK的Inherited而是自己实现了完整的元注解合并逻辑。它通过AnnotatedElementUtils、MergedAnnotations这些工具一层层向上扫描“注解的注解”把组合注解里的所有元注解信息合并出来。这也是为什么你会看到“Inherited不生效但Spring依然能扫描到子类”的现象——两条解析路线完全独立不要混淆。再举个常见例子RequestMapping同时支持类级别和方法级别所以它的Target里包含了TYPE和METHOD。也正是因为元注解的配置够清晰Spring AOP才能在运行时决定到底匹配哪个切点。5.2 编译期注解处理另一条无需反射的路线看到Retention(SOURCE)别觉得它没用。在JDK源码体系里这种注解往往配合编译期注解处理器javax.annotation.processing工作。最典型的是Lombok它的Getter、Setter、Slf4j都是SOURCE保留还有MapStruct的Mapper、Mapping在javac编译阶段就被处理器消费掉直接生成实现类。这条路线最大的优势是运行时零反射开销性能好缺点是调试链路更深生成的代码和源文件可能“对不上”。所以当你只是想做一个开发期工具注解可以认真考虑SOURCE加APT而一旦注解代表的是业务运行时规则老老实实走RUNTIME加反射/切面是更稳妥的路径。5.3 其他框架里的元注解形态MyBatis的Select、Insert、Update、Delete都是Target(METHOD)、Retention(RUNTIME)明确只作用在Mapper接口方法上。JUnit 5的参数化测试注解ValueSource也用了可重复设计和对应的容器注解。你如果去翻这些框架源码会发现它们其实都在同一套元注解规则里演算。看多了之后遇到一个新注解基本扫一眼Target和Retention就能判断出它大概在什么阶段、什么位置被解析。6. 实践多年踩过的坑元注解使用中的常见误区与排查思路最后分享几个我在实际项目里踩过的坑按“现象-根因-解决”的方式还原方便你以后排查时对号入座。6.1 没写Retention导致运行时反射拿不到注解这个坑是我刚接触自定义注解时踩过的到现在记忆犹新。当时权限模块需要一个注解我的定义长这样public interface RequiresPermission { String value(); }没写Retention默认就变成了CLASS。业务代码里用反射去读Method method clazz.getMethod(deleteUser); RequiresPermission p method.getAnnotation(RequiresPermission.class); if (p null) { // 权限判断走到了异常分支导致接口直接被拒绝 }运行结果永远是null。排查了很久最后才发现问题出在保留策略上。解决方式极简补上Retention(RetentionPolicy.RUNTIME)。从那以后我给自己订了一条硬规则只要是给业务代码反射使用的注解一律显式声明RUNTIME永远不要依赖默认值。6.2 Inherited用在接口/方法上结果完全无效第二个高频误区把Inherited用在接口方法上期待实现类方法自动继承注解。比如Retention(RetentionPolicy.RUNTIME) Inherited public interface Auditable { } public interface OrderService { Auditable void createOrder(Order order); } public class OrderServiceImpl implements OrderService { Override public void createOrder(Order order) { // 实际执行体 } }运行时读取createOrder方法Auditable根本不存在。原因还是那句Inherited只对“类继承”这一条路径生效接口到实现类、方法到重写方法它一概不管。如果需要方法级注解自动跟随重写只能自己写工具从当前方法往父类方法或接口方法逐层向上找再合并注解集合。6.3 Target过宽AOP切入范围失控我在设计一个审计注解时一开始给了它Target({METHOD, FIELD, TYPE})结果团队里有同事把注解标在了字段上而AOP切面表达式同时又匹配了“带该注解的所有元素”。于是某些对象的字段初始化也触发了审计逻辑日志里一片噪音。虽然问题不难定位但这件事让我意识到Target不是写上去就完事的它代表的是使用契约。收窄Target就是在帮你自己的框架减少误用概率。后来我规定新增注解必须经过“最小目标审核”能用METHOD就不加TYPE能用FIELD就不加PARAMETER。6.4 Repeatable容器类写错编译直接报错Repeatable最常出现的编译错误来自容器注解的Target范围小于原始注解。比如原始注解允许标在TYPE和METHOD上容器注解却只写了Target(TYPE)这样一旦在方法上重复标注就会报错。解决办法是让容器注解的Target范围大于等于原始注解甚至直接省略Target让它能出现在原始注解能出现的任何地方。另一个细节是容器注解成员名必须叫value()返回原始注解类型的数组。我之前看到有人写成RequiredField[] values()编译直接提示找不到容器方法。这些约束都可以在Repeatable源码的文档注释里找到依据多读读JDK源码里的注释很多坑都能提前避掉。6.5 排查元注解问题的通用思路最后给一套我常用的排查顺序供参考先用javap -v 类名.class | grep -A2 -i annotation确认注解在字节码里的保留情况判断Retention是否写错。用反射打印目标元素上拿到哪些注解确认Target是否限定错了目标。如果需要“继承”语义确认你的注解是标在父类还是接口Inherited对后者完全无效。如果涉及重复注解先检查容器注解的定义是否合法再看读取时用的是getAnnotation还是getAnnotationsByType后者才是为重复注解设计的API。按照这个顺序排查绝大多数元注解相关问题都能在十分钟内定位。最后再分享一个我自己的小习惯写自定义注解前先在心里列一张三要素清单——保留策略选什么、目标位置有哪些、需不需要可重复/继承/文档化。有时候还会顺手用javap验证一下字节码结果。这套流程看着朴素但真的能保证你设计出来的注解既有章法又少踩坑。元注解之所以叫“元”就是因为它站在更高一层约束代码表达。把这把钥匙拿稳了以后再去读Spring、MyBatis、JUnit的各种注解设计你会发现一切都顺理成章。