Java元注解编程：构建优雅的代码声明式逻辑

Java元注解是让自定义注解具备可配置、可复用、可被正确处理能力的关键，核心包括@Target（指定使用位置）、@Retention（控制存活周期）、@Documented（生成Javadoc）、@Inherited（支持类继承），需配合处理器才能生效。

Java元注解不是用来“炫技”的，而是让自定义注解真正具备可配置、可复用、可被正确处理的能力。没用好元注解，自定义注解就只是个标签；用对了，它就能成为业务逻辑的声明式入口。

理解四大核心元注解的作用边界

@Target 指明注解能写在哪儿——是类上、方法上、参数里，还是连泛型参数都不放过？常用 ElementType.METHOD 和 ElementType.TYPE 最频繁，但别忽略 ElementType.PARAMETER（用于校验入参）和 ElementType.TYPE_PARAMETER（泛型类型占位符），它们在框架扩展中越来越关键。

@Retention 控制注解存活周期：SOURCE 仅编译期有效（如 @Override）；CLASS 是默认值，注解进字节码但不加载进 JVM；RUNTIME 才能让反射读取——只要需要用反射解析注解（比如 Spring AOP 或自定义拦截器），就必须设为 RUNTIME。

@Documented 让注解出现在生成的 JavaDoc 中。它不改变运行行为，但对团队协作很实在：别人看接口文档时，一眼就能看到 @NonNull、@Deprecated 等语义信息。

立即学习“Java免费学习笔记（深入）”；

@Inherited 允许子类继承父类的注解——但仅对类级别注解生效，且只作用于 extends 关系，不适用于实现接口或方法重写。注意：它不会让方法上的注解被子类方法自动继承。

组合元注解提升注解表达力

单个元注解能力有限，组合使用才能贴近真实场景。例如定义一个权限检查注解：

• @Target({ElementType.METHOD, ElementType.TYPE}) —— 支持加在控制器类或具体接口方法上
• @Retention(RetentionPolicy.RUNTIME) —— 运行时通过 AOP 切面读取并鉴权
• @Documented —— 在 Swagger 或 Javadoc 中显式暴露权限要求
• 不加 @Inherited —— 权限策略通常需显式声明，避免子类意外继承宽松策略

再比如一个配置绑定注解（类似 Spring 的 @ConfigurationProperties）：

• @Target(ElementType.TYPE) —— 只允许标注在配置类上
• @Retention(RetentionPolicy.RUNTIME) —— 需在启动时扫描并注入属性值
• @Repeatable(PropertySources.class) —— 允许同一类上多次声明不同配置源，增强灵活性

小心 @Repeatable 的两个隐性约束

要让注解支持重复声明，不能只加 @Repeatable，必须同时满足：

• 被标记的注解（如 @MyRole）需声明 @Repeatable(MyRoles.class)，其中 MyRoles 是容器注解
• 容器注解 MyRoles 必须有 value() 方法，且返回类型是该注解类型的数组（如 MyRole[]）

否则编译报错：“Repeatable annotation type must have a containing annotation type”。Spring 5+ 已广泛使用该机制（如 @Bean、@Scope），但手写时容易漏掉容器注解的规范定义。

避免常见误用：别把元注解当功能开关

元注解本身不执行逻辑——@Target 不会阻止你写错位置（IDE 或编译器才做检查），@Retention(RUNTIME) 也不等于“自动生效”。真正起作用的是你写的处理器：可能是一个 Aspect、一个 BeanPostProcessor、或者一段反射遍历+条件判断的代码。

典型反例：

• 定义了 @LogExecutionTime 并标了 @Retention(RUNTIME)，却没写 AOP 切面——注解存在，但日志永远不会打
• 给字段加了 @NotBlank，但没引入 Hibernate Validator 或没触发校验流程——空字符串照样入库

记住：元注解是“说明书”，不是“执行器”。声明之后，务必配套实现解析与响应逻辑。

不复杂但容易忽略。