在 spring boot 中捕获 structuredtaskscope 异常，核心做法是结合全局异常处理器 @controlleradvice 与 java 21 的 structuredtaskscope.shutdownonfailure。由于 shutdownonfailure() 会包装原始异常为 executionexception，你需要在 @exceptionhandler 中通过 causeexceptionfinder 或手动遍历 throwable.getcause() 链来提取并处理底层的业务异常。
如何区分 ShutdownOnSuccess 和 ShutdownOnFailure 的异常表现
这两种模式在处理子任务异常时的行为截然不同，直接决定了你的异常处理逻辑需要针对哪种包装类型进行解包。在使用 ShutdownOnFailure 时，只要有一个子任务抛出异常，整个作用域就会立即关闭，且 get() 方法抛出的异常是一个包含所有失败原因的 ExecutionException；而 ShutdownOnSuccess 则会在找到一个成功结果后关闭其他任务，如果所有任务都失败，它也会抛出 ExecutionException，但其内部结构可能只包含部分失败信息或按特定顺序排列。
import java.util.concurrent.StructuredTaskScope;
import java.util.concurrent.ExecutionException;
public class ExceptionDemo {
public static void main(String[] args) throws Exception {
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
var sub1 = scope.fork(() -> { throw new RuntimeException("Task 1 Failed"); });
var sub2 = scope.fork(() -> "Success");
scope.join();
scope.close();
// 这里会抛出 ExecutionException
System.out.println(sub1.get());
}
}
}
运行上述代码，控制台将输出类似以下的堆栈信息，其中 Caused by: java.lang.RuntimeException: Task 1 Failed 清晰展示了原始异常的嵌套关系。开发者在编写 @ExceptionHandler 时，必须意识到 get() 返回的不是原始异常，而是 ExecutionException，因此不能直接将其作为业务异常处理。
如何在 ControllerAdvice 中精准提取底层异常
为了在全局异常处理中精准定位到具体的业务错误，推荐使用 java.util.concurrent.CauseExceptionFinder（Java 21+）或传统的递归查找方式。在 @ControllerAdvice 中，你可以定义一个专门处理 ExecutionException 的方法，利用 CauseExceptionFinder.find() 快速找到最深层的根异常，从而避免冗长的 if-else 判断链。
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.CauseExceptionFinder;
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ExecutionException.class)
public String handleStructuredException(ExecutionException ex) {
// 使用 CauseExceptionFinder 提取根异常
Throwable rootCause = CauseExceptionFinder.find(ex);
if (rootCause instanceof IllegalArgumentException e) {
return "Bad Request: " + e.getMessage();
} else if (rootCause instanceof RuntimeException e) {
return "Internal Error: " + e.getMessage();
}
return "Unknown Structured Task Error";
}
}
这段代码展示了如何处理由 StructuredTaskScope 引发的异常。当控制器中的异步任务抛出异常时，Spring 会捕获到 ExecutionException，然后进入 handleStructuredException 方法。通过 CauseExceptionFinder.find(ex)，我们直接获取到了原始的 IllegalArgumentException 或 RuntimeException，进而可以根据具体类型返回不同的 HTTP 状态码或错误消息。这种方法比手动调用 ex.getCause().getCause()... 更加健壮且易于维护。
当子任务抛出非运行时异常时如何处理
如果 StructuredTaskScope 的子任务中抛出了受检异常（Checked Exception），例如 IOException 或自定义的 BusinessException，处理方式依然遵循相同的解包逻辑，但需要在 lambda 表达式中明确声明或使用 throws 包装。由于 fork 方法接受的 Supplier extends T> 不允许抛出受检异常，你必须将这些异常包装为 RuntimeException 或在任务内部捕获并转换为运行时异常。
import java.io.IOException;
// 在任务中处理受检异常
var sub = scope.fork(() -> {
try {
// 模拟 IO 操作
throw new IOException("File not found");
} catch (IOException e) {
// 转换为运行时异常以便被 ShutdownOnFailure 捕获
throw new RuntimeException(e);
}
});
在这种情况下，全局异常处理器中的 CauseExceptionFinder 依然能正确找到最内层的 IOException。开发者需要注意，虽然 IOException 是受检异常，但在 StructuredTaskScope 的执行上下文中，它最终会被包装成 ExecutionException 的根源。因此，在 @ExceptionHandler 中检查 rootCause instanceof IOException 是完全可行的，这允许你对不同类型的底层异常进行细粒度的控制。
