UndeclaredThrowableException 是 JDK 动态代理因远程接口未声明受检异常而包装抛出的 RuntimeException，提示契约失配；根本原因是 RMI 要求显式声明 throws RemoteException，但服务端抛出如 TimeoutException 等未声明的受检异常，代理层校验失败后将其封装为此异常，需通过 getCause() 获取原始异常并修复接口声明。
UndeclaredThrowableException 不是原始异常，而是 JDK 动态代理机制自动包装出来的 RuntimeException。它本身不表示业务问题，而是暴露了一个契约失配：远程方法调用中抛出了未在接口中声明的受检异常（checked exception），代理层无法直接透传，只能用它包裹后向上抛出。
根本原因：RMI 接口契约被打破
RMI 要求所有远程方法必须显式声明 throws RemoteException，这是协议强制约定。但很多开发者只关注业务逻辑，忽略了——如果服务端实际抛出了其他受检异常（比如 TimeoutException、SQLException、IOException 等），而这些异常并未出现在接口方法的 throws 子句中，JDK 代理就会拒绝原样传递，转而封装成 UndeclaredThrowableException。
- 例如接口定义为：
String getData() throws RemoteException - 但服务端实现里写了：
throw new TimeoutException("call timeout"); - 这个
TimeoutException是受检异常，又不在接口声明范围内 → 触发包装
为什么不是直接抛出原异常？
动态代理生成的代理类（如 $Proxy2）在执行 invoke() 时，会校验：若 handler 抛出的异常类型不能赋值给方法签名中声明的异常列表，就禁止抛出。这是 Java 反射和代理的安全设计，防止调用方因未声明异常而缺少 try-catch 或 throws 声明，导致编译期契约失效。
-
UndeclaredThrowableException继承自RuntimeException，所以无需声明即可抛出 - 原始异常可通过
getCause()或getUndeclaredThrowable()取出 - 它本质是一个“兜底容器”，不是错误，而是提示“你漏声明了”
常见触发场景与对应修复方式
这类异常多出现在 RMI、EJB、或基于 JDK Proxy 的 RPC 框架（如老版本 Dubbo）中。典型情况包括：
-
超时异常未声明：RPC 客户端底层网络超时抛出
SocketTimeoutException，但接口没声明它 → 在接口中补充throws SocketTimeoutException（不推荐）或统一转为RemoteException子类再抛 -
序列化失败引发的异常：参数含非
Serializable对象，RMI 序列化阶段抛NotSerializableException→ 该异常属于底层通信错误，应归入RemoteException体系，服务端捕获后包装为RemoteException再抛出 -
业务异常设计不当：自定义业务异常继承
Exception（受检），但接口未声明 → 改为继承RuntimeException，或在接口中明确throws YourBizException
最佳实践建议
不要在应用层 catch UndeclaredThrowableException 并吞掉，那只是掩盖问题。应该从契约源头治理：
- 远程接口方法签名中，除
RemoteException外，只声明真正需要由调用方决策处理的业务受检异常 - 所有底层通信异常（超时、断连、序列化失败等）应在服务端或框架层统一捕获，转换为
RemoteException或其子类后再抛出 - 客户端收到
UndeclaredThrowableException时，优先检查getCause()，记录完整堆栈，用于定位是哪个环节漏了声明 - 使用 IDE 的“Implement Methods”功能生成接口实现时，注意补全
throws子句，别手动删掉
