TypeNotPresentException发生在JVM解析字节码中泛型签名、注解等元数据阶段，即读取Signature属性时，而非类加载或实例化时；它是RuntimeException，与需显式处理的ClassNotFoundException有本质区别。

这个异常不是“类没找到”，而是 JVM 在解析泛型签名或注解元数据时，发现某个**已写死在字节码里的全限定类名**（比如 com.example.UserDto）在当前 ClassLoader 中根本不可见，于是主动尝试加载失败后抛出的运行时异常。

它发生在哪一阶段？

不是 new 实例时，也不是 Class.forName() 时，而是在读取 class 文件的 Signature 属性 阶段——也就是泛型、注解值、接口 default 方法返回类型这些元数据被首次解析的时候。此时 JVM 还没执行任何业务逻辑，甚至类都还没真正初始化。

• 调用 Method.getGenericReturnType()、Field.getGenericType() 等反射方法时容易触发
• 堆栈里常见 sun.reflect.generics.parser.SignatureParser 或 Reifier
• 异常消息中会明确写出缺失类型的全限定名，例如：Type com.example.MissingService not present

和 ClassNotFoundException 有什么区别？

ClassNotFoundException 是你主动去加载一个类（如 Class.forName("xxx")）失败才抛；TypeNotPresentException 是 JVM 被动解析元数据时“顺手”想把泛型里的类名也载入，结果发现找不到——它不关心你有没有用到那个类，只认字节码里写的名。

• 前者是检查异常（需 try-catch 或 throws），后者是 RuntimeException
• 前者发生在类加载入口点，后者发生在元数据解析环节
• catch ClassNotFoundException 对 TypeNotPresentException 完全无效

哪些地方最容易踩坑？

重点排查所有在编译期就固化了具体类名的位置：

• @ConditionalOnClass(MissingClass.class) —— Spring Boot 自动配置中最常见
• 自定义注解中声明了 Class> value() default Void.class; 类型属性，并传入了实际类
• 接口里写了 default List getData() { ... }
• Maven Shade 打包时排除了某些依赖，但泛型签名仍保留着被删类的引用
• 多模块项目中，A 模块升级删了某个 DTO，B 模块未重新编译，旧 class 文件里还存着它的泛型引用

怎么安全处理？

核心原则：别让它炸开，提前兜底。

• 对每个 getGenericXXX() 单独 try-catch TypeNotPresentException，不要用大范围 catch
• 捕获后退回到原始类型，例如：method.getGenericReturnType() 失败 → 改用 method.getReturnType()
• 避免 catch Throwable，防止吞掉 OOM、StackOverflow 等致命错误
• 工具类中封装成 SafeGenericTypes.safeGetParameterTypes(Method) 这样的静态方法，统一 fallback 行为