健壮的框架注解需合理组合元注解：@target明确作用域（如method或type+method），@retention设为runtime以支持反射，@inherited仅对类注解生效且需显式声明，@repeatable需配套容器注解，@documented提升文档可见性。
设计一个健壮的框架注解，核心在于合理组合 Java 提供的元注解（@Target、@Retention、@Documented、@Inherited、@Repeatable），明确其作用范围、生命周期、可见性与复用规则，而非堆砌所有元注解。
明确注解的使用目标（@Target）
必须指定 @Target，否则编译器允许该注解被误用在任意位置，导致运行时行为不可控。应严格限定作用域，避免宽泛声明。
- 若仅用于标记方法（如自定义 RPC 调用入口），用
@Target(ElementType.METHOD) - 若需同时支持类和方法（如统一配置开关），写成
@Target({ElementType.TYPE, ElementType.METHOD}) - 禁止使用
ElementType.ANNOTATION_TYPE以外的通配（如ElementType.TYPE_USE）除非真有类型使用场景，否则增加理解成本和误用风险
控制注解的生命周期（@Retention）
根据框架实际需要选择保留策略，多数自定义框架注解应设为 RetentionPolicy.RUNTIME，确保可通过反射读取。
-
SOURCE：仅保留在源码阶段，适合生成代码或 IDE 提示类注解（如 Lombok 的@Getter），框架逻辑无法感知 -
CLASS：编译后仍在字节码中，但反射不可见；适用于字节码增强工具（如 AspectJ 编译期织入），非主流反射驱动框架 -
RUNTIME：反射可读，是 Spring、Dubbo 等主流框架的基础要求；若注解需参与 Bean 创建、代理生成、参数校验等运行时逻辑，必须选此项
保证注解语义的可传播性（@Inherited 与 @Repeatable）
这两个元注解解决不同问题，不能混用，需按需启用。
-
@Inherited仅对 类级别注解 生效，且子类继承父类注解时，父类必须显式声明该元注解；接口、方法、字段上的注解不继承 -
@Repeatable允许同一位置多次声明同名注解（如@Route(path="/v1")和@Route(path="/v2")），但需配套定义容器注解（如@Routes），并确保容器注解本身标注@Target和@Retention - 二者互不影响：一个注解可同时标注
@Inherited和@Repeatable，但需确认业务逻辑是否真正需要这种组合（例如：可继承的、允许多次声明的配置类注解）
提升注解的文档可用性（@Documented）
添加 @Documented 后，Javadoc 会将该注解及其属性纳入生成文档，对团队协作和框架使用者至关重要。
- 框架公开 API 注解（如
@RpcService、@ValidatedGroup）务必加上，方便开发者查阅用途和参数含义 - 内部中间件使用的私有注解（如模块间通信标记）可省略，但建议统一规范，降低维护门槛
- 它不影响运行时行为，纯属“契约可视化”，成本极低，收益明确
不复杂但容易忽略。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
