注解失效的根本原因在于未正确配置元注解：必须使用@retention(retentionpolicy.runtime)才能被反射读取，@target需匹配实际使用位置，且需有对应处理器（如aop、beanpostprocessor）消费该注解，否则仅为静态元数据。
Java 注解不是“写个标签就完事”，高频痛点都集中在“写了但没用上”“用了但不生效”“生效了但出错”这三类。核心不在语法，而在理解注解的生命周期、作用域和被谁消费。
注解写了却没被框架识别？检查元注解和保留策略
很多开发者定义了自定义注解，加在方法上，却发现 Spring 或其他框架完全无反应——大概率是 @Retention 设错了。
-
@Retention(RetentionPolicy.SOURCE)：仅保留在源码阶段，编译后丢弃（如
@Override），运行时反射读不到； - @Retention(RetentionPolicy.CLASS)：保留在字节码中，但 JVM 不加载到内存，反射也读不到；
- @Retention(RetentionPolicy.RUNTIME)：唯一能让框架（如 Spring、MyBatis、Fastjson）通过反射读取的策略，必须选它。
同时确认 @Target 是否匹配使用位置（比如注解标在字段上，但声明只允许用在方法上，就会静默失效）。
注解生效了，但逻辑没执行？看清楚谁在“消费”它
注解本身不干活，它只是“信息卡片”。真正干活的是解析它的处理器——可能是 Spring AOP、BeanPostProcessor、Jackson 序列化器，或你手写的反射工具类。
- 比如
@JSONField只对 Fastjson 生效，换成 Jackson 就无效； -
@NeedLogin这类权限注解，若没配 AOP 切面或拦截器，它就是一段静态文本； - 自定义
@EnumDesc工具类若没调用EnumDescUtil.getDesc()，字段上的注解永远只是元数据。
编译期/运行期行为混用，导致预期不符
不同注解作用时机不同，混用会引发奇怪问题：
-
@Override编译期校验：写错方法签名，IDE 直接报错，不进 JVM； -
@Transactional运行期代理增强：私有方法上加它无效（Spring 代理不生效）； -
@Value启动时注入：配置未加载完成就访问，可能为 null； -
@Scheduled容器启动后才注册：若 Bean 初始化失败，定时任务根本不会注册。
IDEA 中注解提示异常或红色波浪线？优先排查 SDK 和插件
不是代码错，而是环境没认全：
- 确认项目 SDK 是 JDK 8+（低版本不支持某些注解特性）；
- 检查 Lombok 插件是否启用（
@Data等注解依赖它生成字节码）； - 若用 MapStruct，需安装对应插件并开启 annotation processing；
- 修改
.vmoptions后重启 IDEA，避免因内存不足导致注解解析器加载失败。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
