java注解体系是元注解约束、内置注解奠基、自定义注解扩展、反射读取驱动的完整闭环；元注解决定注解存在性与作用范围，内置注解验证核心能力，自定义注解聚焦业务语义，反射读取确保能力落地。
Java注解体系不是零散功能的堆砌，而是一个由元注解约束、内置注解奠基、自定义注解扩展、反射读取驱动的完整闭环。真正落地的关键不在“能不能写”，而在“怎么让每个环节严丝合缝地协同工作”。
元注解是整个闭环的基石
没有正确配置的元注解，自定义注解就只是源码里的装饰符号，运行时根本不存在。
- @Target必须明确限定作用位置：比如权限校验注解只该加在方法上，就用@Target(ElementType.METHOD)；若还允许标注在类上统一开启权限检查，则写成@Target({ElementType.TYPE, ElementType.METHOD})
- @Retention必须设为RUNTIME：这是反射能读到注解的唯一前提。设成SOURCE或CLASS，编译后就没了，框架拦截器、AOP处理器全都会失效
- @Documented和@Inherited按需启用：生成公共SDK时加@Documented；需要子类自动继承父类行为标记（如@NeedAudit）时才用@Inherited，且仅对类注解生效
- @Repeatable用于支持叠加语义：比如一个方法既要缓存又要重试，就定义@Cacheable和@Retryable，并用@Repeatable(Cacheables.class)让它们可并列使用
内置注解是理解设计意图的入口
它们不是摆设，而是JDK对注解核心能力的最小可行验证。
- @Override强制编译期校验签名一致性——说明注解可参与静态检查
- @Deprecated触发编译警告——说明注解能影响开发体验与工具链
- @SuppressWarnings压制泛型警告——说明注解可干预编译器行为
- @FunctionalInterface保障接口契约——说明注解可用于约束抽象结构
自定义注解要聚焦业务语义而非技术细节
好注解的名字和属性应该让业务同学一眼看懂，而不是让开发者去翻源码。
- 属性命名直白：用
role()而不是value()，除非真只有一个主值；用timeoutMs()而不是timeout() - 默认值降低使用门槛：
String message() default "参数校验失败"比强制传参更友好 - 类型选实用的：优先用String、int、枚举、Class；避免复杂嵌套；数组属性支持单值简写（
roles = "admin"等价于roles = {"admin"}） - 避免过度设计：不需要运行时逻辑的注解，不硬加RUNTIME；纯生成代码的注解，SOURCE就够了
反射读取是闭环生效的最后也是最关键一环
注解本身不做事，所有能力都靠反射代码兑现。这步出错，前面全白搭。
- 先判断再获取：
if (method.isAnnotationPresent(MyLog.class)) { MyLog log = method.getAnnotation(MyLog.class); }比直接get更安全 - 目标对象要选对：查类注解用
clazz.getAnnotation(...)，查方法注解必须先拿到Method对象，字段同理 - 注意类加载时机：确保注解类已被ClassLoader加载，否则isAnnotationPresent返回false
- 批量处理推荐用AnnotatedElement：Spring的
AnnotationUtils、Guava的Annotations都封装了递归查找、继承合并等高频逻辑，别重复造轮子
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
