Spring Boot REST API错误处理指南

墨蓝 2022-06-09 11:51 149阅读 0赞

原文地址：http://geek.csdn.net/news/detail/235057

摘要：本文通过实例介绍了使用Spring Boot在设计API的时候如何正确地对异常进行处理。以下是译文

API在提供错误消息的同时进行适当的错误处理，是一个非常有用的功能，因为这能让API客户端对问题进行正确地响应。API处理错误的默认行为通常是返回难以理解的堆栈跟踪，而这些对API客户端来说并没有什么用。将错误信息切分成多个字段可以方便API客户端的解析，以此向用户提供更加友好的错误消息。本文将介绍在使用[Spring Boot][]构建REST API的时候如何进行合适的错误处理。

![Person confused about a cryptic and long error message][]

在过去几年里，使用Spring构建REST API已经成为Java开发人员的标准方法。而使用Spring Boot则有助于API的构建，因为它删除了大量的样板代码，并实现了各种组件的自动化配置。我们假设你对利用这些技术进行API开发的基础知识已经非常了解。如果你对如何开发基本的REST API并不熟悉，那么你应该先阅读这篇关于[Spring MVC][]的文章或另一篇有关[构建Spring REST服务][Spring REST]的文章。

## 让错误响应更清晰 ##

在本文中，我们将实现一个通过REST API来检索鸟类（代表一个对象）的应用程序，[代码托管在GitHub上][GitHub]。这个示例包含了本文描述的所有功能，以及比较多的错误处理场景。以下是该程序实现的端点URL：

<table style="border-spacing:0px; border-collapse:collapse; width:890px; margin:5px 0px; color:rgb(51,51,51); font-family:'microsoft yahei',arial; font-size:16px; line-height:27.2px; text-align:justify"> 
 <thead style=""> 
  <tr style=""> 
   <th style="padding:2px 9px; text-align:left; font-size:14px">&nbsp;</th> 
   <th style="padding:2px 9px; text-align:left; font-size:14px">&nbsp;</th> 
  </tr> 
 </thead> 
 <tbody style=""> 
  <tr style=""> 
   <td style="padding:2px 9px; font-size:14px"><code style="font-family:'Source Code Pro',monospace; font-size:12.6px; padding:2px 4px; color:rgb(63,63,63); white-space:nowrap">GET /birds/{birdId}</code></td> 
   <td style="padding:2px 9px; font-size:14px">获取鸟的相关信息，如果没有找到，则抛出异常。</td> 
  </tr> 
  <tr style=""> 
   <td style="padding:2px 9px; font-size:14px"><code style="font-family:'Source Code Pro',monospace; font-size:12.6px; padding:2px 4px; color:rgb(63,63,63); white-space:nowrap">GET /birds/noexception/{birdId}</code></td> 
   <td style="padding:2px 9px; font-size:14px">这个调用也可以获取鸟的相关信息，但是即使没有找到相应的鸟，也不会抛出异常。</td> 
  </tr> 
  <tr style=""> 
   <td style="padding:2px 9px; font-size:14px"><code style="font-family:'Source Code Pro',monospace; font-size:12.6px; padding:2px 4px; color:rgb(63,63,63); white-space:nowrap">POST /birds</code></td> 
   <td style="padding:2px 9px; font-size:14px">创建一只鸟。</td> 
  </tr> 
 </tbody> 
</table>

Spring框架的MVC模块在错误处理方面提供了一些很不错的功能，但是这些功能需要由开发人员主动调用，才能返回对API客户端的有具体意义的响应。

我们来看一下这个Spring Boot默认响应的例子。当我们向`/birds`发送一个HTTP POST的时候，消息内容是下面这个JSON对象，字段“mass”的值是字符串“aaa”，这个字段本应该填一个整数：

{
     "scientificName": "Common blackbird",
     "specie": "Turdus merula",
     "mass": "aaa",
     "length": 4
    }

Spring Boot的默认响应，没有正确的处理错误：

{
     "timestamp": 1500597044204,
     "status": 400,
     "error": "Bad Request",
     "exception": "org.springframework.http.converter.HttpMessageNotReadableException",
     "message": "JSON parse error: Unrecognized token 'three': was expecting ('true', 'false' or 'null'); nested exception is com.fasterxml.jackson.core.JsonParseException: Unrecognized token 'aaa': was expecting ('true', 'false' or 'null')\n at [Source: java.io.PushbackInputStream@cba7ebc; line: 4, column: 17]",
     "path": "/birds"
    }

呃…… 响应消息里有一些很有用的字段，但它里面有关异常的内容太多了。 顺便说一句，这是Spring Boot中`DefaultErrorAttributes`类的内容。 `timestamp`字段是一个整数，不携带什么度量单位的时间戳信息。`exception`字段只有Java开发人员会感兴趣，该消息使API消费者迷失在与它们无关的细节中。是否有更多的细节可以从错误产生的异常中提取出来呢？ 下面，我们来学习如何正确地处理这些异常，并将它们包装成更好的JSON表示形式，让API客户端更容易识别。

由于我们要使用Java 8的日期和时间类，因此首先需要为Jackson JSR310转换器添加一个Maven依赖关系。这个包使用注解`@JsonFormat`将Java 8的日期和时间类转换为JSON：

<dependency>
       <groupId>com.fasterxml.jackson.datatype</groupId>
       <artifactId>jackson-datatype-jsr310</artifactId>
    </dependency>

好的，我们来定义一个表示API错误的类。 我们将创建一个名为`ApiError`的类，该类用于保存REST调用期间发生错误的相关信息。

class ApiError {
    
       private HttpStatus status;
       @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "dd-MM-yyyy hh:mm:ss")
       private LocalDateTime timestamp;
       private String message;
       private String debugMessage;
       private List<ApiSubError> subErrors;
    
       private ApiError() {
           timestamp = LocalDateTime.now();
       }
    
       ApiError(HttpStatus status) {
           this();
           this.status = status;
       }
    
       ApiError(HttpStatus status, Throwable ex) {
           this();
           this.status = status;
           this.message = "Unexpected error";
           this.debugMessage = ex.getLocalizedMessage();
       }
    
       ApiError(HttpStatus status, String message, Throwable ex) {
           this();
           this.status = status;
           this.message = message;
           this.debugMessage = ex.getLocalizedMessage();
       }
    }

*  `status`属性保存了操作调用的状态。 比如，4xx表示客户端错误，5xx意味着服务器错误。 比较常见的情况是：http返回码400表示BAD\_REQUEST，例如，客户端发送了格式不正确的字段（如无效的电子邮件地址）。
 *  `timestamp`属性保存了发生错误的日期时间。
 *  `message`属性保存了对用户友好的错误信息。
 *  `debugMessage`属性更详细地描述了错误。
 *  `subErrors`属性保存了发生的子错误的数组。 这用于表示在单个调用中出现的多个错误。比如，校验的时候有多个字段验证失败。用`ApiSubError`类进行封装。

abstract class ApiSubError {
    
    }
    
    @Data
    @EqualsAndHashCode(callSuper = false)
    @AllArgsConstructor
    class ApiValidationError extends ApiSubError {
       private String object;
       private String field;
       private Object rejectedValue;
       private String message;
    
       ApiValidationError(String object, String message) {
           this.object = object;
           this.message = message;
       }
    }

`ApiValidationError`是类`ApiSubError`的扩展类，表示REST调用时遇到的校验问题。

下面，你将看到几个JSON响应的例子，这些响应根据我们上面的描述做了改进。

以下这个JSON是在调用URL`GET /birds/2`后找不到实体的时候返回的：

{
     "apierror": {
       "status": "NOT_FOUND",
       "timestamp": "18-07-2017 06:20:19",
       "message": "Bird was not found for parameters {id=2}"
     }
    }

下面是调用`POST /birds`时传入了无效值后返回的JSON示例：

{
     "apierror": {
       "status": "BAD_REQUEST",
       "timestamp": "18-07-2017 06:49:25",
       "message": "Validation errors",
       "subErrors": [
         {
           "object": "bird",
           "field": "mass",
           "rejectedValue": 999999,
           "message": "must be less or equal to 104000"
         }
       ]
     }
    }

## Spring Boot 错误处理 ##

我们来探讨一些用于异常处理的Spring注解。

[`RestController`][RestController]是用于REST操作类的最基本的注解。

[`ExceptionHandler`][ExceptionHandler]这个Spring注解提供了一种机制，用来处理在执行程序期间抛出的异常。此注解将作为处理此控制器中抛出的异常的入口点。总而言之，最常见的方法是在`@ControllerAdvice`类的方法上使用`@ExceptionHandler`，以便将异常处理应用于全局或控制器的子集。

[`ControllerAdvice`][ControllerAdvice]是Spring 3.2中引入的注解，顾名思义，它是多控制器的“建议”。它使得单个`ExceptionHandler`应用于多个控制器上。这样我们可以在一个地方定义如何处理这样的异常，当`ControllerAdvice`覆盖的类抛出异常时，这个处理程序就会被调用。受影响的控制器子集可以在`@ControllerAdvice`上使用以下选择器进行定义：`annotations()`，`basePackageClasses()`和`basePackages()`。如果没有提供选择器，则`ControllerAdvice`将应用于全局所有的控制器。

所以，通过使用`@ExceptionHandler`和`@ControllerAdvice`，我们可以定义一个用于处理异常的中心点，并将异常包装在`ApiError`对象中，这比Spring Boot默认的错误处理机制更好。

## 处理异常 ##

![Representation of what happens with a successful and failed REST client call][]

下一步是创建处理异常的类。为了简单起见，我们称之为`RestExceptionHandler`，它必须继承自Spring Boot的`ResponseEntityExceptionHandler`。我们也将从`ResponseEntityExceptionHandler`继承，因为它已经提供了对Spring MVC异常的一些基本处理方法，所以，我们将改进现有的异常处理手段，并同时添加针对新异常的处理。

如果看一下`ResponseEntityExceptionHandler`的源代码，你会看到有很多方法名为`handle******()`，像`handleHttpMessageNotReadable()`或`handleHttpMessageNotWritable()`。我们来看看如何对`handleHttpMessageNotReadable()`进行扩展来处理`HttpMessageNotReadableException`异常。我们只需要在`RestExceptionHandler`类中重写方法`handleHttpMessageNotReadable()`：

@Order(Ordered.HIGHEST_PRECEDENCE)
    @ControllerAdvice
    public class RestExceptionHandler extends ResponseEntityExceptionHandler {
        
    
       @Override
       protected ResponseEntity<Object> handleHttpMessageNotReadable(HttpMessageNotReadableException ex, HttpHeaders headers, HttpStatus status, WebRequest request) {
           String error = "Malformed JSON request";
           return buildResponseEntity(new ApiError(HttpStatus.BAD_REQUEST, error, ex));
       }
    
       private ResponseEntity<Object> buildResponseEntity(ApiError apiError) {
           return new ResponseEntity<>(apiError, apiError.getStatus());
       }
    
       //other exception handlers below
    
    }

如果抛出一个`HttpMessageNotReadableException`，则错误消息将是“Malformed JSON request（格式错误的JSON请求）”，该错误封装在`ApiError`对象内。下面我们可以看到新的应答：

{
     "apierror": {
       "status": "BAD_REQUEST",
       "timestamp": "21-07-2017 03:53:39",
       "message": "Malformed JSON request",
       "debugMessage": "JSON parse error: Unrecognized token 'aaa': was expecting ('true', 'false' or 'null'); nested exception is com.fasterxml.jackson.core.JsonParseException: Unrecognized token 'aaa': was expecting ('true', 'false' or 'null')\n at [Source: java.io.PushbackInputStream@7b5e8d8a; line: 4, column: 17]"
     }
    }

### 处理自定义异常 ###

现在，我们来看看如何创建一个方法来处理没有在Spring Boot的`ResponseEntityExceptionHandler`中声明的异常。

Spring程序处理数据库调用的一个常见场景是使用库类通过id去查找记录。但是，如果研究一下`CrudRepository.findOne()`方法，我们会发现，如果找不到对象，它将返回`null`。这意味着如果我们的服务只是调用这个方法并直接返回给控制器，那么即使找不到资源，我们也会得到HTTP返回码200（OK）。实际上，正确的方法是返回[HTTP/1.1规范][HTTP_1.1]中指定的HTTP返回码404（NOT FOUND）。

为了处理这种情况，我们将创建一个名为`EntityNotFoundException`的自定义异常。它与`javax.persistence.EntityNotFoundException`不同，因为它提供的一些构造函数可以用来选择以不同的方式处理`javax.persistence`异常。

![Example of a failed REST call][]

也就是说，我们可以在`RestExceptionHandler`类中为这个新创建的`EntityNotFoundException`创建一个`ExceptionHandler`。为此，创建一个名为`handleEntityNotFound()`的方法，并使用`@ExceptionHandler`对其进行注释，将类对象`EntityNotFoundException.class`传递给它。这表示每次抛出`EntityNotFoundException`的时候，Spring应该调用此方法来处理它。当用`@ExceptionHandler`注释一个方法时，它将接受各种自动注入的参数，如`WebRequest`、`Locale`，以及在[这里][ExceptionHandler]提到的其他参数。我们将提供异常`EntityNotFoundException`本身作为`handleEntityNotFound`方法的参数。

@Order(Ordered.HIGHEST_PRECEDENCE)
    @ControllerAdvice
    public class RestExceptionHandler extends ResponseEntityExceptionHandler {
        
    
       //other exception handlers
    
       @ExceptionHandler(EntityNotFoundException.class)
       protected ResponseEntity<Object> handleEntityNotFound(
               EntityNotFoundException ex) {
           ApiError apiError = new ApiError(NOT_FOUND);
           apiError.setMessage(ex.getMessage());
           return buildResponseEntity(apiError);
       }
    }

太好了！我们在`handleEntityNotFound()`方法里将HTTP状态代码设置为`NOT_FOUND`，并使用了新的异常消息。以下是`GET /birds/2`的响应示例：

{
     "apierror": {
       "status": "NOT_FOUND",
       "timestamp": "21-07-2017 04:02:22",
       "message": "Bird was not found for parameters {id=2}"
     }
    }

## 结论 ##

对异常处理的控制非常重要，所以我们需要将这些异常正确映射到`ApiError`对象上，以提供给API客户端一些重要的信息，让它们知道发生了。接下来的步骤就是为抛出的异常创建更多的处理方法（带有@ExceptionHandler的方法）。你可以在[GitHub代码仓库][GitHub]中找到更多的示例。

这里另外还有一些资源，可对本文起到补充作用：

*  Baeldung - [使用Spring对REST进行错误处理][Spring_REST]
 *  Spring Blog - [Spring MVC中的异常处理][Spring MVC 1]

[Spring Boot]: https://www.toptal.com/spring
[Person confused about a cryptic and long error message]: /images/20220609/d57db809645845a8aeba541c8f78b2cc.png
[Spring MVC]: https://www.toptal.com/spring/beginners-guide-to-mvc-with-spring-framework
[Spring REST]: https://spring.io/guides/gs/rest-service/
[GitHub]: https://github.com/brunocleite/spring-boot-exception-handling
[RestController]: https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/RestController.html
[ExceptionHandler]: https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/ExceptionHandler.html
[ControllerAdvice]: https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/ControllerAdvice.html
[Representation of what happens with a successful and failed REST client call]: /images/20220609/561c83cc4ec74f74aa12657cfd34a5d2.png
[HTTP_1.1]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
[Example of a failed REST call]: /images/20220609/583521ea0fb94e24b43a9290c39a77e3.png
[Spring_REST]: http://www.baeldung.com/exception-handling-for-rest-with-spring
[Spring MVC 1]: https://spring.io/blog/2013/11/01/exception-handling-in-spring-mvc