异常工具 - ExceptionUtil

简介

ExceptionUtil 是 Hutool 提供的异常处理工具类，封装了常见的异常操作，例如将受检异常转换为运行时异常、获取异常的详细信息、从异常链中提取特定类型的异常等。该工具类极大简化了异常处理逻辑，适用于开发中的各种场景。

1. 使用场景

• 受检异常转换：在代码中，如果不希望处理受检异常，可以使用 ExceptionUtil 将其转换为运行时异常。
• 异常信息获取：在调试或日志记录时，ExceptionUtil 提供了获取异常完整信息和堆栈信息的简便方法。
• 异常链分析：在处理复杂异常链时，ExceptionUtil 可以帮助快速定位和提取特定类型的异常。

2. 主要方法

2.1 包装异常

ExceptionUtil 提供了 wrap 方法，可以将任意异常包装为指定类型的异常，例如将 IOException 包装为 RuntimeException。

示例：将受检异常包装为运行时异常

import cn.hutool.core.exceptions.ExceptionUtil;
import cn.hutool.core.io.IORuntimeException;

import java.io.IOException;

public class ExceptionUtilExample {
    public static void main(String[] args) {
        try {
            // 模拟抛出一个受检异常
            throw new IOException("文件读取错误");
        } catch (IOException e) {
            // 将受检异常包装为运行时异常
            IORuntimeException wrappedException = ExceptionUtil.wrap(e, IORuntimeException.class);
            throw wrappedException;
        }
    }
}

• 方法签名：
  • public static <T extends Throwable> T wrap(Throwable throwable, Class<T> wrapType)：将异常包装为指定类型的异常。
• 参数说明：
  • throwable: 需要包装的原始异常。
  • wrapType: 包装后的异常类型。
• 返回值：包装后的异常。
• 作用：在不希望处理受检异常时，将其包装为运行时异常，简化代码结构。
• 实际开发场景：在开发中，如果希望忽略某些异常的处理，或者不希望在每个方法中捕获和处理受检异常，可以使用该方法将异常转换为运行时异常。

2.2 获取入口方法

ExceptionUtil 提供了 getRootStackElement 方法，可以获取异常栈中的入口方法（即最初发生异常的位置）。

示例：获取入口方法

import cn.hutool.core.exceptions.ExceptionUtil;

public class ExceptionUtilExample {
    public static void main(String[] args) {
        try {
            // 模拟抛出一个异常
            throw new RuntimeException("测试异常");
        } catch (RuntimeException e) {
            // 获取异常的入口方法
            StackTraceElement rootElement = ExceptionUtil.getRootStackElement(e);
            System.out.println("入口方法: " + rootElement.getMethodName());
            // 输出结果: main
        }
    }
}

• 方法签名：
  • public static StackTraceElement getRootStackElement(Throwable throwable)：获取异常栈中的入口方法。
• 参数说明：
  • throwable: 要分析的异常。
• 返回值：StackTraceElement，异常栈中的入口方法。
• 作用：在调试或日志记录时，快速定位最初发生异常的位置。
• 实际开发场景：在分析复杂异常链或多层次的异常时，获取入口方法可以帮助快速确定问题源头。

2.3 异常转换

ExceptionUtil 提供了 convertFromOrSuppressedThrowable 方法，可以将异常链中指定类型的异常提取并返回。

示例：从异常链中提取指定类型的异常

import cn.hutool.core.exceptions.ExceptionUtil;

import java.io.IOException;

public class ExceptionUtilExample {
    public static void main(String[] args) {
        // 创建一个包含多个异常的异常链
        IOException ioException = new IOException("IO 异常");
        IllegalArgumentException argumentException = new IllegalArgumentException(ioException);

        // 提取链中的 IOException
        IOException extractedException = ExceptionUtil.convertFromOrSuppressedThrowable(argumentException, IOException.class, true);
        System.out.println("提取的异常: " + extractedException.getMessage());
        // 输出结果: IO 异常
    }
}

• 方法签名：
  • public static <T extends Throwable> T convertFromOrSuppressedThrowable(Throwable throwable, Class<T> targetType, boolean includeSuppressed)：从异常链中提取指定类型的异常。
• 参数说明：
  • throwable: 要分析的异常。
  • targetType: 目标异常类型。
  • includeSuppressed: 是否包含被抑制的异常（suppressed）。
• 返回值：提取到的目标异常。
• 作用：在处理复杂异常链时，可以提取指定类型的异常，便于后续处理。
• 实际开发场景：在框架或工具开发中，可能需要对异常链进行深入分析，并提取其中的特定异常进行进一步处理。

2.4 其他常用方法

• getMessage(Throwable e)：获取异常的完整消息，包括异常类型。
• wrapRuntime(Throwable throwable)：将受检异常包装为运行时异常。
• getCausedBy(Throwable throwable, Class<? extends Throwable> causeClass)：获取由指定类型引起的异常。
• isCausedBy(Throwable throwable, Class<? extends Throwable>... causeClasses)：判断异常是否由指定类型引起。
• stacktraceToString(Throwable throwable)：将异常堆栈信息转换为字符串，便于日志记录或调试。

3. 实际应用场景

• 受检异常转运行时异常：在开发中，如果希望统一处理异常或简化异常处理，可以使用 ExceptionUtil 将受检异常包装为运行时异常。
• 日志记录和调试：在记录日志或调试时，使用 ExceptionUtil 可以方便地获取异常的完整堆栈信息或入口方法。
• 异常链分析：在处理复杂异常链时，可以通过 ExceptionUtil 快速提取和分析特定类型的异常，帮助定位问题。

4. 注意事项

• 在使用 convertFromOrSuppressedThrowable 方法时，确保异常链中存在目标异常类型，否则返回值可能为 null。
• 包装异常时，注意不要丢失原始异常的堆栈信息，确保异常处理的上下文完整。