Spring @Async方法抛出异常的处理方案咨询

问题背景 #

在Spring Boot应用中，给调用SendGrid API的邮件发送方法添加@Async实现异步调用后，该方法抛出的异常无法被@ControllerAdvice全局异常处理器捕获，导致无法向客户端返回500 HTTP状态码；但移除@Async改为同步调用时，异常处理器可正常工作。

原代码示例：

public class EmailService {

    @Async
    public void send(String address, String subject, String body) {
        // 调用SendGrid的API
    }
}

public class PasswordService {

    @Autowired
    private EmailService emailService;

    public void resetAll(List<String> emailAddresses) {
        emailAddresses.forEach(email -> {
            emailService.send(email, "Your new password is", "open-sesame");   
        });
    }
}

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public void handleException(Exception ex) {
        ex.printStackTrace();
    }
}

解决方案 #

方法1：自定义异步未捕获异常处理器 #

Spring提供AsyncUncaughtExceptionHandler接口，专门处理异步方法抛出的未捕获异常，可通过配置绑定到异步任务执行器。

1. 实现自定义异常处理器：

@Component
public class CustomAsyncExceptionHandler implements AsyncUncaughtExceptionHandler {

    @Override
    public void handleUncaughtException(Throwable ex, Method method, Object... params) {
        // 复用全局异常处理逻辑或直接处理异常
        ex.printStackTrace();
        // 注意：异步线程脱离原请求上下文，无法直接修改响应，若需通知客户端可通过WebSocket、消息队列等方式
    }
}

2. 配置异步任务执行器并绑定处理器：

@Configuration
@EnableAsync
public class AsyncConfig implements AsyncConfigurer {

    @Autowired
    private CustomAsyncExceptionHandler asyncExceptionHandler;

    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(25);
        executor.setThreadNamePrefix("EmailAsync-");
        executor.initialize();
        return executor;
    }

    @Override
    public AsyncUncaughtExceptionHandler getAsyncUncaughtExceptionHandler() {
        return asyncExceptionHandler;
    }
}

方法2：让异步方法返回CompletableFuture，在调用方捕获异常 #

修改异步方法返回CompletableFuture，在调用方等待所有异步任务完成并重新抛出异常，让全局异常处理器捕获。

1. 修改EmailService的异步方法：

public class EmailService {

    @Async
    public CompletableFuture<Void> send(String address, String subject, String body) {
        try {
            // 调用SendGrid的API
            return CompletableFuture.completedFuture(null);
        } catch (Exception e) {
            return CompletableFuture.failedFuture(e);
        }
    }
}

2. 在调用方统一处理异常：

public class PasswordService {

    @Autowired
    private EmailService emailService;

    public void resetAll(List<String> emailAddresses) {
        List<CompletableFuture<Void>> futures = emailAddresses.stream()
                .map(email -> emailService.send(email, "Your new password is", "open-sesame"))
                .collect(Collectors.toList());

        // 等待所有异步任务完成，捕获异常后重新抛出
        try {
            CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
        } catch (CompletionException e) {
            throw new RuntimeException(e.getCause());
        }
    }
}

这种方式下，异常会被抛回原请求线程，触发@ControllerAdvice的全局异常处理器，返回500状态码。

关键注意点 #

• 异步线程默认脱离原请求上下文，只有在调用方同步等待异步任务完成并重新抛出异常时，才能通过全局异常处理器返回HTTP状态码。
• 若无需同步等待，可通过日志记录、告警触发等方式处理异常，或通过其他机制通知客户端。

内容的提问来源于stack exchange，提问作者Dónal