Java高级注解元数据设计：元注解的应用设计原则-java教程-PHP中文网

元注解是行为契约：@target限定适用位置，@retention决定生命周期，@documented控制文档生成，@inherited影响继承传递，@repeatable支持重复使用；缺一不可，误用将导致功能失效或设计混乱。

java高级注解元数据设计：元注解的应用设计原则

元注解不是装饰品，是行为契约

元注解不是为了“看起来完整”而堆砌的标签，而是对自定义注解行为边界的明确声明。每个元注解都在回答一个关键问题：@Target 回答“它能贴在哪”，@Retention 回答“它能活多久”，@Documented 回答“要不要写进文档”，@Inherited 回答“子类能不能接着用”。漏掉任何一个，就等于没签清楚合同——运行时反射找不到、编译器不认、Javadoc不显示、子类意外失焦，都是常见后果。

@Target 要精确，避免过度开放

不要图省事写 @Target(ElementType.TYPE) 然后把注解到处乱打。如果注解只用于方法日志记录，就该限定为 @Target(ElementType.METHOD)；如果只修饰字段做校验，就选 ElementType.FIELD。过度宽泛会导致：

IDE 无法提供准确提示或错误检查
其他开发者误用（比如给局部变量加了本该作用于类的配置注解）
后续框架解析逻辑变复杂，需额外判断上下文

必要时可用数组组合多个目标，例如 @Target({ElementType.METHOD, ElementType.CONSTRUCTOR})，但前提是这两处语义一致。

deep-java-review

Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...

下载

@Retention 必须匹配使用场景

生命周期不是越长越好。选错策略会直接导致功能失效或性能浪费：

SOURCE：仅编译期生效，适合 Lombok 风格的代码生成或 Checkstyle 规则。运行时反射拿不到，别指望它驱动 Spring Bean 初始化
CLASS：字节码里有，但 JVM 不加载。适合 ASM 字节码增强工具，但普通反射调用 getAnnotation() 会返回 null
RUNTIME：唯一支持反射读取的策略，Spring、MyBatis 等主流框架依赖它。但注意：频繁反射读取可能带来开销，建议配合缓存（如 ConcurrentMap 存储已解析结果）

慎用 @Inherited 和 @Repeatable

这两个元注解容易引发隐式行为，设计前先问自己是否真需要：

@Inherited 只对 类继承 生效，且仅限 Class 级注解。它不会传递到方法、字段或接口实现上。如果父类加了 @Transactional，子类方法默认不继承事务——因为 @Transactional 本身没加 @Inherited，这是有意为之的设计
@Repeatable 要求配套定义容器注解（如 @Schedules 容纳多个 @Schedule）。若业务上天然不允许重复（比如一个类只能有一个主配置），强行加 @Repeatable 反而破坏约束力