📦 异常工具-ExceptionUtil

ExceptionUtil 是 Hutool 提供的异常处理工具类，封装了异常的捕获、转换、堆栈分析等功能，旨在简化 Java 异常处理的复杂性。

🔧 核心方法

1. 异常信息获取

// 获取完整异常消息，格式：异常类名: 异常消息
String message = ExceptionUtil.getMessage(new RuntimeException("test")); // "RuntimeException: test"

// 获取简单异常消息，仅包含异常消息内容
String simpleMessage = ExceptionUtil.getSimpleMessage(new RuntimeException("test")); // "test"

2. 异常转换与包装

// 将检查异常转换为运行时异常
IOException ioException = new IOException("IO error");
RuntimeException runtimeException = ExceptionUtil.wrapRuntime(ioException);

// 如果已经是运行时异常，直接返回
RuntimeException existingRuntimeException = new RuntimeException("Runtime error");
RuntimeException result = ExceptionUtil.wrapRuntime(existingRuntimeException); // 直接返回existingRuntimeException

// 将异常包装为指定类型的异常
IORuntimeException wrappedException = ExceptionUtil.wrap(ioException, IORuntimeException.class);

// 包装并抛出异常
ExceptionUtil.wrapAndThrow(ioException); // 抛出UndeclaredThrowableException

3. 运行时异常抛出

// 抛出运行时异常
ExceptionUtil.wrapRuntimeAndThrow("Error message"); // 抛出RuntimeException

// 带参数的运行时异常
ExceptionUtil.wrapRuntimeAndThrow("Error message: {}", "param"); // 抛出RuntimeException，消息为"Error message: param"

// 带cause和参数的运行时异常
ExceptionUtil.wrapRuntimeAndThrow(ioException, "Error message: {}", "param"); // 抛出RuntimeException，cause为ioException

4. 堆栈信息处理

// 获取当前栈信息
StackTraceElement[] stackElements = ExceptionUtil.getStackElements();

// 获取指定层的堆栈信息
StackTraceElement stackElement = ExceptionUtil.getStackElement(2);

// 获取入口方法堆栈信息
StackTraceElement rootStackElement = ExceptionUtil.getRootStackElement();

// 将堆栈转为完整字符串
String stacktrace = ExceptionUtil.stacktraceToString(ioException);

// 将堆栈转为单行字符串，便于日志输出
String oneLineStacktrace = ExceptionUtil.stacktraceToOneLineString(ioException);

// 限制堆栈字符串长度
String limitedStacktrace = ExceptionUtil.stacktraceToString(ioException, 1000);

5. 异常链分析

// 获取异常链中最尾端的异常（根本原因）
Throwable rootCause = ExceptionUtil.getRootCause(new RuntimeException(new IOException("Root cause"))); // 返回IOException

// 获取异常链上所有异常的集合
List<Throwable> throwableList = ExceptionUtil.getThrowableList(new RuntimeException(new IOException("Root cause")));
// 结果：[RuntimeException, IOException]

// 获取由指定异常类引起的异常
Throwable causedBy = ExceptionUtil.getCausedBy(new RuntimeException(new IOException("Root cause")), IOException.class); // 返回IOException

// 判断异常是否由指定类型引起
boolean isCausedBy = ExceptionUtil.isCausedBy(new RuntimeException(new IOException("Root cause")), IOException.class); // true

6. 异常判断

// 判断异常是否来自或者包含指定异常
IOException ioException = new IOException();
IllegalArgumentException argumentException = new IllegalArgumentException(ioException);
boolean isFromOrSuppressed = ExceptionUtil.isFromOrSuppressedThrowable(argumentException, IOException.class); // true

// 转化异常为指定类型，如果是或包含则返回，否则返回null
IOException converted = ExceptionUtil.convertFromOrSuppressedThrowable(argumentException, IOException.class); // 返回ioException

🎯 主要功能详解

1. 异常转换

ExceptionUtil 提供了多种异常转换方法，主要用于将检查异常转换为运行时异常，简化异常处理。

• wrapRuntime(Throwable throwable)：将检查异常转换为运行时异常
• wrap(Throwable throwable, Class<T> wrapThrowable)：将异常包装为指定类型的异常
• wrapAndThrow(Throwable throwable)：包装并抛出异常

这些方法可以大幅简化异常处理代码，避免在方法签名中声明大量检查异常。

2. 堆栈信息处理

堆栈信息是调试和日志记录的重要依据，ExceptionUtil 提供了强大的堆栈信息处理功能：

• getStackElements()：获取当前栈信息
• getStackElement(int i)：获取指定层的堆栈信息
• getRootStackElement()：获取入口方法堆栈信息
• stacktraceToString(Throwable throwable)：将堆栈转为完整字符串
• stacktraceToOneLineString(Throwable throwable)：将堆栈转为单行字符串

单行堆栈信息特别适合日志输出，可以减少日志行数，同时保留完整的堆栈信息。

3. 异常链分析

在复杂的调用链中，异常可能会被多次包装，ExceptionUtil 提供了智能的异常链分析功能：

• getRootCause(Throwable throwable)：获取异常链中最尾端的异常（根本原因）
• getThrowableList(Throwable throwable)：获取异常链上所有异常的集合
• getCausedBy(Throwable throwable, Class<? extends Exception>... causeClasses)：获取由指定异常类引起的异常
• isCausedBy(Throwable throwable, Class<? extends Exception>... causeClasses)：判断异常是否由指定类型引起

这些方法可以帮助开发者快速定位异常的根本原因，提高调试效率。

📋 方法列表

方法签名	功能描述
getMessage(Throwable e)	获得完整消息，包括异常名
getSimpleMessage(Throwable e)	获得简单消息，仅包含异常消息内容
wrapRuntime(Throwable throwable)	将检查异常转换为运行时异常
wrap(Throwable throwable, Class<T> wrapThrowable)	将异常包装为指定类型的异常
wrapAndThrow(Throwable throwable)	包装并抛出异常
wrapRuntimeAndThrow(String message, Object... params)	抛出运行时异常
getStackElements()	获取当前栈信息
stacktraceToString(Throwable throwable)	将堆栈转为完整字符串
stacktraceToOneLineString(Throwable throwable)	将堆栈转为单行字符串
getRootCause(Throwable throwable)	获取异常链中最尾端的异常
getThrowableList(Throwable throwable)	获取异常链上所有异常的集合
isCausedBy(Throwable throwable, Class<? extends Exception>... causeClasses)	判断异常是否由指定类型引起
getCausedBy(Throwable throwable, Class<? extends Exception>... causeClasses)	获取由指定异常类引起的异常

💡 注意事项

1. 异常转换的性能：异常转换会创建新的异常对象，影响性能，应避免在高性能场景下频繁使用
2. 堆栈信息的开销：获取完整堆栈信息会产生一定的开销，在高性能场景下应谨慎使用
3. 异常链的深度：异常链过深可能导致栈溢出，应避免无限递归的异常链
4. 运行时异常的使用：运行时异常不需要显式捕获，应合理使用，避免掩盖程序错误
5. 异常信息的安全性：异常信息可能包含敏感数据，在生产环境中应谨慎输出完整异常信息

通过 ExceptionUtil，可以大幅简化开发中的异常处理代码，提高代码的可读性和可维护性，同时提供更强大的异常分析能力。