Class ExceptionUtil

java.lang.Object
cloud.opencode.base.core.exception.ExceptionUtil
public final class ExceptionUtil extends Object
Exception Utility - Exception chain analysis and handling utilities 异常工具类 - 异常链分析和处理工具

Provides exception chain analysis, stack trace handling and safe execution wrappers.

提供异常链分析、堆栈跟踪处理和安全执行包装器等功能。

Features | 主要功能:

  • Root cause extraction (getRootCause) - 根本原因提取
  • Stack trace to string (getStackTrace) - 堆栈跟踪转字符串
  • Exception chain traversal (getCausalChain) - 异常链遍历
  • Checked exception wrapping (wrapAndThrow) - 受检异常包装
  • Sneaky throw (bypass compilation check) - 静默抛出

Usage Examples | 使用示例:

Throwable root = ExceptionUtil.getRootCause(exception);
String stackTrace = ExceptionUtil.getStackTrace(exception);
List<Throwable> chain = ExceptionUtil.getCausalChain(exception);
ExceptionUtil.sneakyThrow(new IOException("test"));

Security | 安全性:

  • Thread-safe: Yes (stateless) - 线程安全: 是 (无状态)
  • Null-safe: Yes - 空值安全: 是
Since:
JDK 25, opencode-base-core V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • getRootCause

      public static Throwable getRootCause(Throwable throwable)
      Gets 获取异常的根本原因

      遍历异常链，返回最底层的异常（没有 cause 的异常）。

      Parameters:
      throwable - the exception | 异常
      Returns:
      the result | 根本原因，如果输入为 null 则返回 null

    • getStackTrace

      public static String getStackTrace(Throwable throwable)
      Gets 获取异常的堆栈跟踪字符串
      Parameters:
      throwable - the exception | 异常
      Returns:
      the result | 堆栈跟踪字符串，如果输入为 null 则返回空字符串

    • getCausalChain

      public static List<Throwable> getCausalChain(Throwable throwable)
      Gets 获取异常的因果链

      返回从当前异常到根本原因的所有异常列表。

      Parameters:
      throwable - the exception | 异常
      Returns:
      the result | 异常链列表（从当前异常到根本原因），如果输入为 null 则返回空列表

    • unwrap

      public static Throwable unwrap(Throwable throwable)
      Unwraps a nested exception 解包嵌套异常

      如果异常是包装类型（如 RuntimeException 包装了 IOException）， 则返回被包装的异常。

      Parameters:
      throwable - the exception | 异常
      Returns:
      the result | 解包后的异常，如果没有 cause 则返回原异常

    • unwrap

      public static <T extends Throwable> T unwrap(Throwable throwable, Class<T> exceptionType)
      Unwraps an exception of a specific type 解包特定类型的异常

      遍历异常链，找到并返回指定类型的异常。

      Type Parameters:
      T - the value | 异常类型
      Parameters:
      throwable - the exception | 异常
      exceptionType - the value | 目标异常类型
      Returns:
      the result | 找到的异常，如果未找到则返回 null

    • wrapAndThrow

      public static void wrapAndThrow(ExceptionUtil.CheckedRunnable runnable)
      Wraps 包装受检异常为运行时异常并抛出

      执行可能抛出受检异常的代码，如果发生异常则包装为 OpenException。

      Parameters:
      runnable - the value | 可能抛出受检异常的代码块
      Throws:
      OpenException - if the condition is not met | 如果发生异常

    • wrapAndReturn

      public static <T> T wrapAndReturn(ExceptionUtil.CheckedSupplier<T> supplier)
      Wraps 包装受检异常为运行时异常并返回结果
      Type Parameters:
      T - the value | 返回值类型
      Parameters:
      supplier - the value | 可能抛出受检异常的代码块
      Returns:
      the result | 执行结果
      Throws:
      OpenException - if the condition is not met | 如果发生异常

    • sneakyThrow

      public static <T extends Throwable> RuntimeException sneakyThrow(Throwable throwable) throws T
      Silently throws a checked exception 静默抛出受检异常

      利用泛型擦除机制，将受检异常作为运行时异常抛出， 而不需要在方法签名中声明。

      警告

      谨慎使用此方法，因为它绕过了编译器的异常检查。 仅在确实需要抛出原始受检异常时使用。
      Type Parameters:
      T - the value | 伪装的异常类型
      Parameters:
      throwable - the value | 要抛出的异常
      Returns:
      the result | 永不返回，仅用于满足返回类型要求
      Throws:
      T - if the condition is not met | 实际抛出的异常

    • contains

      public static boolean contains(Throwable throwable, Class<? extends Throwable> exceptionType)
      Checks 判断异常链中是否包含指定类型的异常
      Parameters:
      throwable - the exception | 异常
      exceptionType - the value | 目标异常类型
      Returns:
      the result | 如果包含则返回 true

    • getMessage

      public static String getMessage(Throwable throwable)
      Gets 获取异常消息，如果为 null 则返回异常类名
      Parameters:
      throwable - the exception | 异常
      Returns:
      the result | 异常消息或类名

    • getRootCauseMessage

      public static String getRootCauseMessage(Throwable throwable)
      Gets 获取根本原因的消息
      Parameters:
      throwable - the exception | 异常
      Returns:
      the result | 根本原因的消息