Spring@ControllerAdvice用CompletableFuture处理异常未返回预期响应问题

出现这个问题的核心是异步场景下的异常处理逻辑没有适配CompletableFuture的特性，具体原因分以下几点：

1. CompletableFuture封装了异常状态，未被正确解包 #

同步方法抛出PasswordMismatchException时，异常会直接被APIExceptionHandler捕获并转换为APIResponse。但异步方法返回的是CompletableFuture对象，当内部逻辑抛出异常时，异常不会直接抛到处理器层面，而是被封装到CompletableFuture的异常完成状态中。如果你的处理器仍按同步逻辑处理，就会把CompletableFuture本身的状态信息（比如CompletableFuture[Completed exceptionally]）当成响应返回，而非预期的APIResponse。

2. 普通异常处理器不支持异步方法的异常捕获 #

多数框架（如Spring）的默认@ExceptionHandler是为同步方法设计的，无法自动解析CompletableFuture内部的异常。如果没有配置专门的异步异常处理逻辑，框架会把异常状态的CompletableFuture直接作为返回值，而不是触发你的APIExceptionHandler来生成响应。

3. 手动使用CompletableFuture时未处理内部异常 #

如果是你手动在业务方法中构建CompletableFuture（比如CompletableFuture.supplyAsync(...)），却没有通过exceptionally()或handle()方法处理内部异常，那么当Future异常完成时，返回的就是一个携带异常的Future实例，而非转换后的APIResponse。

• 在Future链内提前处理异常：在构建CompletableFuture时，通过exceptionally()将异常转换为APIResponse，示例：

  return CompletableFuture.supplyAsync(() -> {
      // 业务逻辑，可能抛出PasswordMismatchException
  }).exceptionally(ex -> {
      if (ex.getCause() instanceof PasswordMismatchException) {
          return new APIResponse(HttpStatus.BAD_REQUEST.value(), "密码不匹配");
      }
      return new APIResponse(HttpStatus.INTERNAL_SERVER_ERROR.value(), "系统异常");
  });
  

• 配置异步专属异常处理器：以Spring为例，实现AsyncConfigurer接口，重写getAsyncUncaughtExceptionHandler()方法，在处理器内捕获异步方法抛出的异常并生成APIResponse。
• 适配处理器方法签名：确保异常处理器的方法返回CompletableFuture<APIResponse>，而非直接返回APIResponse，让框架能正确处理异步场景的响应封装。

内容的提问来源于stack exchange，提问作者Aman Agarwal