如何用 Spring 和 Spring Boot 实现 REST API 的自定义异常

介绍

本文将演示如何使用 Spring 和 Spring Boot 中实现 REST API 的异常处理，并了解不同版本引入了哪些新功能。
在 Spring 3.2 之前，在 Spring MVC 中处理异常的两种主要方法是：HandlerExceptionResolver 或 @ExceptionHandler 注解。 这两种方法都有一些明显的缺点。
从 3.2 开始，我们就使用 @ControllerAdvice 注解来解决前两种方案的局限性， 并在整个应用程序中促进统一的异常处理。
现在，Spring 5 引入了 ResponseStatusException 类： REST API 中快速处理基本异常的方法。
最后，我们将看到 Spring Boot 带来了什么，以及如何配置它以满足我们的需要。

方案 1 — Controller 级别的 @ExceptionHandler

第一个解决方案在 Controller 级别工作——我们将定义一个处理异常的方法，并使用 @ExceptionHandler 注释它：

public class FooController{
     
    //...
    @ExceptionHandler({ CustomException1.class, CustomException2.class })
    public void handleException() {
        //
    }
}

这种方法有一个主要的缺点—— @ExceptionHandler注释方法只对特定的 Controller，而不是对整个应用程序全局。当然，将它添加到每个控制器并不适合一般的异常处理机制。
我们可以通过让所有的 Controller 扩展一个 Base Controller 来绕过这个限制 —— 但是，对于应用程序来说，无论出于什么原因，这都可能是一个问题。例如，控制器可能已经从另一个基类扩展而来，这个基类可能在另一个 jar 中，或者不能直接修改，或者它们本身不能直接修改。
接下来，我们将研究解决异常处理问题的另一种方法—一种全局的方法。

方案 2 — HandlerExceptionResolver

第二个解决方案是定义一个 HandlerExceptionResolver —— 它将解决应用程序抛出的任何异常。它还允许我们在 REST API 中实现统一的异常处理机制。
在使用自定义解析器之前，让我们回顾一下现有的实现。

ExceptionHandlerExceptionResolver

该解析器是在 Spring 3.1 中引入的，默认情况下在 DispatcherServlet 中启用。 这实际上是前面介绍的 @ExceptionHandler 机制如何工作的核心组件。

DefaultHandlerExceptionResolver

这个解析器是在 Spring 3.0 中引入的，在 DispatcherServlet 中默认启用它。它用于解决相应 HTTP 状态码的标准 Spring 异常，即客户端异常 - 4xx 和服务器异常 - 5xx 状态码。下面是它处理的 Spring 异常的完整列表：

Exception	HTTP Status Code
BindException	400 (Bad Request)
ConversionNotSupportedException	500 (Internal Server Error)
HttpMediaTypeNotAcceptableException	406 (Not Acceptable)
HttpMediaTypeNotSupportedException	415 (Unsupported Media Type)
HttpMessageNotReadableException	400 (Bad Request)
HttpMessageNotWritableException	500 (Internal Server Error)
HttpRequestMethodNotSupportedException	405 (Method Not Allowed)
MethodArgumentNotValidException	400 (Bad Request)
MissingServletRequestParameterException	400 (Bad Request)
MissingServletRequestPartException	400 (Bad Request)
NoSuchRequestHandlingMethodException	404 (Not Found)
TypeMismatchException	400 (Bad Request)

虽然它确实正确地设置了响应的状态代码，但有一个限制是它没有为响应的主体设置任何内容。对于 REST API —— 状态代码实际上并没有足够的信息提供给客户端 —— 响应也必须有一个主体，以允许应用程序提供关于故障的附加信息。
这可以通过配置视图解析和通过 ModelAndView 呈现异常内容来解决，但是这个解决方案显然不是最优的。这就是为什么 Spring 3.2 引入了一个更好的选项，我们将在下面讨论。

ResponseStatusExceptionResolver

这个解析器也是在 Spring 3.0 中引入的，并在 DispatcherServlet 中默认启用。它的主要职责是使用自定义异常上可用的 @ResponseStatus 注解，并将这些异常映射到HTTP状态码。
这样的自定义异常如下所示：

@ResponseStatus(value = HttpStatus.NOT_FOUND)
public class MyResourceNotFoundException extends RuntimeException {
    public MyResourceNotFoundException() {
        super();
    }
    public MyResourceNotFoundException(String message, Throwable cause) {
        super(message, cause);
    }
    public MyResourceNotFoundException(String message) {
        super(message);
    }
    public MyResourceNotFoundException(Throwable cause) {
        super(cause);
    }
}

与 DefaultHandlerExceptionResolver 一样，这个解析器在处理响应主体的方式上是有限的——它确实将状态代码映射到响应上，但是响应的主体仍然是空的。

SimpleMappingExceptionResolver 和 AnnotationMethodHandlerExceptionResolver

SimpleMappingExceptionResolver 已经出现了很长一段时间了——它来自于旧的 Spring MVC 模型，并且与 REST 服务无关。我们基本上使用它来映射异常类名来查看名称。
在 Spring 3.0 中引入了 AnnotationMethodHandlerExceptionResolver 来通过 @ExceptionHandler 注释处理异常，但是从 Spring 3.2 开始， ExceptionHandlerExceptionResolver 就不再支持它了。

Custom HandlerExceptionResolver

DefaultHandlerExceptionResolver 和 ResponseStatusExceptionResolver 的组合在为 Spring RESTful 服务提供良好的异常处理机制方面走了很长的路。缺点是 —— 如前所述一样无法控制响应的主体。
这种方法是 Spring REST 服务异常处理的一致且易于配置的机制。但是，它确实有局限性：它与低级别的 HtttpServletResponse 交互，并且它适合使用 ModelAndView 的旧 MVC 模型 —— 所以仍然有改进的空间。

方案 3 — @ControllerAdvice

Spring 3.2 通过 @ControllerAdvice 注释为全局 @ExceptionHandler 带来了支持。这使得一种机制能够脱离旧的 MVC 模型，利用 ResponseEntity 以及 @ExceptionHandler 的类型安全和灵活性：

@ControllerAdvice
public class RestResponseEntityExceptionHandler 
  extends ResponseEntityExceptionHandler {
 
    @ExceptionHandler(value 
      = { IllegalArgumentException.class, IllegalStateException.class })
    protected ResponseEntity