元注解是框架配置体系的设计蓝图,通过@Target限定使用位置、@Retention控制生命周期、@Documented增强文档可见性、@Inherited支持类继承,共同构成可扩展的标签体系。

元注解是框架配置体系的“设计蓝图”,不是直接干活的工人,而是规定“谁能在哪干活、干到什么阶段、要不要留档、能不能传给下一代”的规则制定者。Spring 的 @Controller、@Service、@Configuration 等看似功能各异的标签,底层都靠几个 JDK 元注解统一约束行为——没有它们,框架就无法可靠识别、读取和复用注解信息。
@Target 决定注解能贴在哪
它划清使用边界,避免误用。比如:
- @Controller 只允许标注在类上(ElementType.TYPE),不能加在方法参数里;
- @Value 必须能用于字段和参数(ElementType.FIELD, ElementType.PARAMETER);
- 自定义权限注解 @RequireRole 若只支持方法级控制,就明确限定为 ElementType.METHOD,防止开发者错误地贴到类上导致逻辑失效。
@Retention 控制注解何时可用
这是运行时能力的前提。框架绝大多数动态行为依赖反射读取注解,所以必须设为 RUNTIME:
- @Autowired、@RequestMapping 都需在容器启动或请求进来时通过反射获取,生命周期必须是 RetentionPolicy.RUNTIME;
- 若只做编译检查(如自定义 @ThreadSafe),用 CLASS 足够;
- @Target 和 @Retention 是唯二不可省略的元注解——缺一个,注解就失去实际工程价值。
@Documented 和 @Inherited 提升可维护性
它们不参与核心逻辑,但影响协作质量:
- @Documented 让自定义注解自动出现在 Javadoc 中,团队成员看文档就能明白 @RetryOnFailure 的语义和用法,不用翻源码;
- @Inherited 仅对类级注解生效,比如你定义了 @TransactionalDomain 并加上它,子类继承父类时会自动获得该事务域标记,减少重复标注;
- Spring 自身的 @Configuration 就带 @Inherited,确保配置类的子类仍被识别为配置来源。
组合元注解构建可扩展标签体系
Spring 的分层组件注解(@Controller / @Service / @Repository)本质是同一套元注解模板的语义变体:
- 都用 @Target(ElementType.TYPE) + @Retention(RetentionPolicy.RUNTIME);
- 都继承自 @Component,而 @Component 本身也是用元注解定义的;
- 这种“元注解打底 → 基础注解封装 → 语义化注解派生”的三层结构,让框架既能统一管理 Bean 生命周期,又能支持业务侧自由扩展新标签(如 @ScheduledJob、@CachedResult)。










