注解失效主因是字节码增强工具擦除元数据，需通过类名后缀、类加载器、javap比对确认增强影响；CGLIB默认不复制注解，Spring AOP需显式获取目标类，Lombok不影响运行时，ASM需手动保留注解结构。
注解本身不执行逻辑，失效往往不是注解写错了，而是它被“看不见”了——字节码增强工具（如 CGLIB、ASM、Byte Buddy、Lombok、Spring AOP 代理）在修改类结构时，可能意外擦除、错位或破坏注解的元数据。这类问题不会报编译错误，运行时也常静默失败，排查需聚焦字节码层面和增强行为本身。
确认是否真被增强过
先验证目标类是否已被动态代理或字节码改写：
- 打印类名：若出现
$$EnhancerByCGLIB$$、$$FastClassBySpringCGLIB$$、$$ByteBuddy$$或$$MockitoMock$$等后缀，说明已生成代理类，原始类上的注解默认不会自动复制到代理类上 - 检查类加载器：调用
target.getClass().getClassLoader()，对比原始类与运行时类的类加载器哈希值，不同说明可能来自不同增强路径 - 用
javap -v YourClass.class查原始 class 文件，确认RuntimeVisibleAnnotations是否存在且完整；再对运行时实际加载的类（如从target.getClass().getProtectionDomain().getCodeSource()定位 jar 或临时目录捞出）做同样检查，比对差异
识别增强工具对注解的处理策略
不同工具对注解的保留行为差异很大，不能假设“增强后注解还在”：
-
CGLIB：默认不复制注解；需手动调用
Enhancer.setUseCache(false)并重写copyConstructors或使用Enhancer.setCopyAnnotations(true)（3.3.0+ 支持） -
Spring AOP：JDK 动态代理仅作用于接口，注解必须加在接口方法上才可见；CGLIB 代理默认不继承目标类注解，需配合
@EnableAspectJAutoProxy(proxyTargetClass = true)并确保切面逻辑显式读取目标类（而非代理类）的注解，例如用AopUtils.getTargetClass(joinPoint.getTarget()) -
Lombok：只在编译期生成代码，不影响运行时注解；但若与 MapStruct 等 APT 工具混用，桥接方法可能携带残缺注解，导致反射读取时报
AnnotationFormatError -
Java Agent / ASM：若自定义字节码操作未调用
visitAnnotation()或遗漏copyAnnotation()逻辑，注解会直接丢失；尤其注意数组成员、嵌套注解、default 值等复杂结构是否被正确重建
验证注解是否还能被反射读取
不要依赖 IDE 提示或日志输出，要实测运行时反射行为：
立即学习“Java免费学习笔记（深入）”；
- 对目标对象，分别尝试：
obj.getClass().getAnnotation(YourAnn.class)（查代理类自身）AopUtils.getTargetClass(obj).getAnnotation(YourAnn.class)（查原始目标类，Spring 环境）obj.getClass().getDeclaredMethod("xxx").getAnnotation(YourAnn.class)（查方法级，注意是否是桥接方法） - 若返回
null，但原始 class 文件里确有注解 → 增强过程丢弃了注解
若抛AnnotationFormatError→ 字节码中注解结构已损坏（如枚举引用悬空、default 类型错位） - 用
javap -v对比增强前后 class 的RuntimeVisibleAnnotations区域，重点关注：
– 常量池中所有CONSTANT_Utf8_info是否指向有效类/枚举
– 注解成员的tag值是否合法（s表字符串，e表枚举，c表 Class，a表数组）
– 数组成员的num_values是否与后续元素数量一致
修复与规避建议
不靠“猜”，而靠可控的增强策略：
- 优先使用 Spring 的
@AliasFor或@Documented显式声明注解继承关系，避免依赖工具自动复制 - 对关键注解类启用
@Indexed（Spring 5.2+），让spring.components文件预注册，绕过运行时反射扫描 - 避免在代理类上调用
getAnnotation()，统一通过Advised接口或AopProxyUtils获取目标对象再读取 - 构建阶段加入字节码校验：Maven 使用
maven-enforcer-plugin+ 自定义规则，或 Gradle 配合byte-buddy的ClassFileLocator扫描注解完整性 - 升级工具链：CGLIB 至 3.3.0+，ASM 至 9.4+，确保兼容 JDK 17+ 的严格注解校验
