Java动态代理无法直接抛出未在接口声明的受检异常，否则会包装为UndeclaredThrowableException；根本原因是JVM字节码校验要求抛出的受检异常必须出现在接口方法throws子句中。
Java 动态代理（基于 InvocationHandler）默认无法直接抛出受检异常（checked exception），因为 invoke 方法签名只声明抛出 Throwable，而 JVM 字节码层面要求代理方法抛出的受检异常必须在接口方法声明中显式列出。若目标接口方法没声明该异常，代理调用时即使实际抛出，也会被包装为 UndeclaredThrowableException —— 这是核心限制。
理解根本原因：接口契约与字节码校验
动态代理生成的代理类实现的是你提供的接口。JVM 在调用代理方法时，会严格检查：实际抛出的受检异常是否在接口方法的 throws 子句中声明。如果没有，就违反契约，JVM 强制将其转为运行时异常。
- 接口方法签名决定代理能“合法”抛出什么异常
-
InvocationHandler.invoke()中 throw 的受检异常，若未在接口中声明，会被自动封装进UndeclaredThrowableException - 这不是代理框架的 bug，而是 Java 类型系统和字节码验证机制的设计约束
解决方案一：在接口方法中声明受检异常
最直接、符合 Java 设计原则的方式：让接口方法明确支持你要抛的异常。
例如：
立即学习“Java免费学习笔记（深入）”；
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
public interface Service {
String doSomething() throws IOException; // 显式声明
}
代理的 invoke 中可直接 throw IOException，调用方能正常捕获。
- 适用于你有权限修改接口定义的场景
- 语义清晰，类型安全，调用方编译期就能处理异常
- 避免所有包装/解包开销和异常链污染
解决方案二：统一转换为运行时异常（推荐用于无权改接口）
若接口已固定且不能添加 throws，应在 invoke 中主动拦截并转换：
public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
try {
return method.invoke(target, args);
} catch (IllegalAccessException | IllegalArgumentException e) {
throw new RuntimeException(e);
} catch (InvocationTargetException e) {
Throwable cause = e.getCause();
if (cause instanceof IOException) {
throw new RuntimeException("I/O error in proxy", cause); // 包装为 RuntimeException
}
throw cause; // 其他异常原样抛出（如 unchecked 或已声明的 checked）
}
}
- 调用方用
try-catch RuntimeException捕获，或依赖上层统一错误处理 - 保留原始异常的 cause，便于日志和调试
- 避免
UndeclaredThrowableException的间接包裹，控制更明确
不推荐的做法：反射绕过检查（危险且无效）
有人尝试用 sun.misc.Unsafe 或字节码工具强行注入异常声明 —— 这不仅破坏 JVM 安全模型，而且在现代 JDK（尤其是模块化后）基本不可行，还会导致 NoSuchMethodError 或 VerifyError。不要尝试。
受检异常的处理本质是 API 契约问题，不是技术障碍。设计阶段明确接口的异常边界，比事后补救更可靠。
