1. 概述
本文将深入探讨 Java 在什么情况下会抛出 UndeclaredThrowableException。
先从理论讲起，再通过两个真实场景帮助你彻底理解这个异常的来龙去脉。✅
目标是让你下次在日志里看到这个异常时，不再一头雾水，而是能迅速定位问题根源。
2. 什么是 UndeclaredThrowableException
简单粗暴地说：当你在运行时抛出了一个“未声明的受检异常（checked exception）”，Java 就会用 UndeclaredThrowableException 把它包一层再抛出去。
⚠️ 注意关键词：“未声明” + “受检异常” + “运行时”。
我们知道，Java 编译器会严格检查受检异常是否被声明或捕获。比如下面这段代码根本过不了编译：
public void undeclared() {
throw new IOException();
}
编译器直接报错：
java: unreported exception java.io.IOException; must be caught or declared to be thrown
所以你可能会觉得：“这不就杜绝了嘛，怎么可能出现未声明的受检异常？”
❌ 错！编译期确实拦住了，但运行时依然可能绕过这个检查机制。
典型场景就是：动态代理或 AOP 切面中，偷偷抛了个受检异常，而原方法签名根本没声明 throws。
这时，JVM 不能直接把受检异常扔出去（会破坏方法契约），于是它做了一件事：
👉 把这个受检异常包装进 UndeclaredThrowableException（本身是个非受检异常），然后抛出包装后的异常。
这样一来，调用方看到的就不是原始的 IOException 或自定义受检异常，而是一个 UndeclaredThrowableException，其 cause 才是真正的异常。
3. Java 动态代理中的实际案例
动态代理是 UndeclaredThrowableException 的经典高发区。我们来看一个例子。
假设我们为 List<String> 创建一个代理，拦截所有方法调用。当调用 size() 时，我们故意抛出一个受检异常：
public class ExceptionalInvocationHandler implements InvocationHandler {
@Override
public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
if ("size".equals(method.getName())) {
throw new SomeCheckedException("Always fails");
}
throw new RuntimeException();
}
}
public class SomeCheckedException extends Exception {
public SomeCheckedException(String message) {
super(message);
}
}
✅ 关键点：
SomeCheckedException是受检异常。List.size()方法签名没有throws声明。- 代理在运行时抛了这个异常 → 违反了方法契约。
现在我们创建代理并调用 size()：
ClassLoader classLoader = getClass().getClassLoader();
InvocationHandler invocationHandler = new ExceptionalInvocationHandler();
List<String> proxy = (List<String>) Proxy.newProxyInstance(classLoader,
new Class[] { List.class }, invocationHandler);
assertThatThrownBy(proxy::size)
.isInstanceOf(UndeclaredThrowableException.class)
.hasCauseInstanceOf(SomeCheckedException.class);
结果正如预期：
- 抛出的是
UndeclaredThrowableException - 原始异常
SomeCheckedException被包装在cause中
⚠️ 踩坑提醒：很多同学看到 UndeclaredThrowableException 就懵了，其实只要 .getCause() 一看就知道真正的问题是什么。
再看另一个情况：调用 isEmpty()：
assertThatThrownBy(proxy::isEmpty).isInstanceOf(RuntimeException.class);
这次抛的是 RuntimeException（非受检异常），JVM 直接放行，不会包装。✅
4. Spring AOP 中的类似场景
Spring AOP 本质也是基于代理（JDK 动态代理或 CGLIB），所以同样会遇到这个问题。
假设我们写了个切面，想让某些方法执行时强制抛异常：
先定义一个注解：
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ThrowUndeclared {}
然后写一个环绕通知（@Around）：
@Aspect
@Component
public class UndeclaredAspect {
@Around("@annotation(undeclared)")
public Object advise(ProceedingJoinPoint pjp, ThrowUndeclared undeclared) throws Throwable {
throw new SomeCheckedException("AOP Checked Exception");
}
}
✅ 注意：
- 切面直接抛了
SomeCheckedException - 被增强的方法（advised method）可能根本没声明 throws
写个服务类测试：
@Service
public class UndeclaredService {
@ThrowUndeclared
public void doSomething() {}
}
doSomething() 是个干净的方法，无返回、无异常声明。
现在运行测试：
@RunWith(SpringRunner.class)
@SpringBootTest(classes = UndeclaredApplication.class)
public class UndeclaredThrowableExceptionIntegrationTest {
@Autowired private UndeclaredService service;
@Test
public void givenAnAspect_whenCallingAdvisedMethod_thenShouldWrapTheException() {
assertThatThrownBy(service::doSomething)
.isInstanceOf(UndeclaredThrowableException.class)
.hasCauseInstanceOf(SomeCheckedException.class);
}
}
结果再次验证：
❌ 实际抛出的不是 SomeCheckedException，而是被包装后的 UndeclaredThrowableException。
5. 总结
UndeclaredThrowableException 的出现，本质是 JVM 在代理场景下对“违反受检异常规则”的一种安全兜底机制。
关键点回顾：
- ✅ 它只在运行时发生，编译期无法触发
- ✅ 常见于动态代理、Spring AOP 等场景
- ✅ 受检异常被包装，非受检异常直接抛出
- ✅ 查看
getCause()是定位真实异常的唯一正确姿势
下次你在日志里看到 UndeclaredThrowableException，别慌，点开 cause 一看，真相大白。🔍
示例代码已托管至 GitHub：https://github.com/baeldung/tutorials/tree/master/spring-aop-2