高可维护注解体系的关键在于合理使用五个标准元注解：@Target限定作用位置，@Retention控制生命周期，@Documented保障文档可见性，@Inherited约定类继承行为，@Repeatable支持重复使用。

设计一个高可维护的注解体系，关键不在堆功能，而在于用好五个标准元注解——它们共同构成一套清晰、可控、可演进的契约。每个元注解都解决一个明确问题：作用位置、生命周期、文档可见性、继承行为、重复使用能力。把这五点理清楚，自定义注解就不会失控。

@Target：精准划定注解的“适用边界”

它不是可有可无的装饰，而是编译期的第一道防线。不加 @Target，注解默认只能用于类/接口/枚举（ElementType.TYPE），容易导致误用却无报错。

• 按语义选 ElementType：方法级增强用 METHOD，字段映射用 FIELD，参数绑定用 PARAMETER，泛型约束用 TYPE_USE
• 多目标需显式声明：@Target({METHOD, CONSTRUCTOR}) 比单值更灵活，但避免过度宽泛（如全选 TYPE、METHOD、FIELD）
• ANNOTATION_TYPE 必须包含：若你的注解本身还要被其他注解修饰（比如元注解组合），就得加上它

@Retention：明确注解的“存活期限”

这个选择直接决定你能否在运行时读到它。绝大多数框架级注解（如 Spring 的 @Service、自定义校验注解）必须是 RUNTIME；仅用于编译检查的（如 Lombok 的 @Data）用 SOURCE 就够了。

Java Maven Common

Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。

下载

• RUNTIME 是最常用也最重的策略：反射读取开销小，但所有注解信息都会进字节码，影响类加载体积
• CLASS 策略适合字节码工具（如 ASM 增强）：注解存在但不进 JVM 运行时，对性能敏感场景更轻量
• 别依赖默认值：@Retention 默认是 CLASS，若你需要反射读取，必须显式写 @Retention(RetentionPolicy.RUNTIME)

@Documented 与 @Inherited：约定元数据的“传播规则”

这两个不改变逻辑，但极大影响协作体验和框架行为的一致性。

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

• @Documented 是给团队看的：只要注解有业务含义（如 @ApiNote、@DeprecatedSince），就该加上，让 Javadoc 自动生成说明
• @Inherited 只对类生效：它不会让子类自动获得父类方法上的注解，只影响 getAnnotation() 在子类 Class 对象上的查找行为
• 慎用 @Inherited：它隐含“策略继承”语义，若框架未按此约定处理（比如 AOP 切面没做向上查找），就会产生预期外行为

@Repeatable：解耦重复使用的“容器负担”

Java 8 引入它，本质是语法糖，背后仍靠容器注解承载数组。要真正可用，必须满足三要素：

• 被标记注解需声明 @Repeatable(Container.class)
• Container 注解的 value 属性必须返回原注解类型数组
• 两者 @Target 和 @Retention 必须完全一致，否则编译失败
• 典型用法：@RolesAllowed("ADMIN") @RolesAllowed("USER") → 底层由 @RolesAllowed.List(value = {...}) 聚合