java元注解共五个：@target限定作用位置，@retention控制生命周期（source/class/runtime），@documented使注解出现在javadoc中，@inherited支持类级注解继承，@repeatable实现同一位置重复使用注解。
注解本身不执行逻辑，但它是架构设计的“声明式契约”。真正支撑多维度规范落地的，是元注解——它们像交通规则一样，定义注解在哪能用、什么时候有效、能否继承、是否可见、能不能重复，从而让注解从随意标签变成可管控、可演进、可协作的设计单元。
作用域精准控制：@Target 决定“谁可以被标记”
@Target 不是可选项，而是安全边界。宽泛声明（比如只写 @Target(ElementType.TYPE) 却用在方法上）会导致编译期无法拦截误用，运行时行为不可控。
- 日志或事务类注解，应限定为 @Target(ElementType.METHOD)，避免污染类或字段
- 配置开关类注解（如 @FeatureToggle），需同时支持类和方法：@Target({ElementType.TYPE, ElementType.METHOD})
- 字段校验注解（如 @NotBlank）必须含 ElementType.FIELD，否则反射取不到目标字段
- 若需标注泛型类型参数（如 List），要额外加上 ElementType.TYPE_USE
生命周期明确划分：@Retention 定义“注解活到哪一阶段”
选错保留策略，注解就等于没写。多数框架级注解必须走 RUNTIME，但不是所有场景都需要它。
- RetentionPolicy.RUNTIME：Spring AOP、Dubbo 服务暴露、Hibernate 校验等依赖反射的场景必备
- RetentionPolicy.CLASS：适用于编译期字节码增强（如某些 AspectJ 织入），不进 JVM，但保留在 class 文件中
- RetentionPolicy.SOURCE：仅用于 IDE 提示或代码生成（如 Lombok 的 @Getter），编译后彻底消失，零运行开销
语义可传播与可叠加：@Inherited 和 @Repeatable 各司其职
这两个元注解解决不同维度的问题，不能混用，但可共存。
- @Inherited 只对 类级别注解 生效，且仅在 class 继承链 中传递（接口实现不继承）。适合统一行为策略，例如父类加 @Auditable，子类自动启用审计
-
@Repeatable 解决同一位置需多个同类配置的场景。比如方法上同时需要缓存、重试、链路追踪：
@Cacheable(key = "user")
@Retryable(maxAttempts = 3)
@Traceable
public void updateUser() { ... }
这要求配套定义容器注解（如 @Cacheables），并确保容器 value() 返回注解数组
文档与协作可见性：@Documented 提升团队契约质量
注解是公开 API 的一部分。不加 @Documented，Javadoc 就不会展示它的存在和含义，使用者只能翻源码猜意图。
- 框架对外暴露的注解（如 @RpcService、@ValidatedGroup）务必加上 @Documented
- 内部中间件私有注解可省略，但建议统一纳入规范，降低新成员理解成本
- 配合清晰的注解属性命名（如 enabled() 而非 flag()）和默认值设计，进一步降低误用率
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
