(六讲)Spring Boot REST API异常处理指南

能够正确的处理REST API程序抛出的异常以及返回友好的异常信息是一件非常重要的事情，因为它可以帮助API客户端正确的对服务端的问题作出正确的响应。这有助于提高REST API的服务质量。Spring Boot默认返回的异常信息对于API客户端来说是晦涩难懂的，只有开发者才会关注那些堆栈异常报告。在本讲中，将对如何处理好Spring REST API异常信息做一个梳理。

最近一段时间，Spring Boot成为了Java开发圈子的网红，越来越多的开发者选择Spring Boot来构建REST API。使用Spring Boot，能够帮助开发者减少模板代码和配置文件的编写工作量。Spring Boot开箱即用的特性，受到广大开发者的热宠。在本讲中，通过一个精简的Demo项目，着重介绍一些Spring Boot REST API的异常处理技巧。

如果你不想阅读本次内容，只是想快速获得相关的源码，那你可以直接跳转到文章的结尾，找到Gihub仓库链接，通过该链接，你可以轻松的获得本次内容的全部源码。

1. 定义明确的异常信息

当程序发送错误时，不应该将晦涩的堆栈报告信息返回给API客户端，从某种意义将，这是一种不礼貌的和不负责任的行为。现在，我们将模拟这样一个需求，API客户端可以向服务端发送请求以获取一个或者多个用户信息，同时还可以发送请求创建一个新的用户信息。下面是大致的一个API信息：

API 名称	说明
GET /users/{userId}	根据用户ID检索用户信息，如果没有找到，则返回用户未找到异常信息
GET /users	根据传入的ID集合，检索用户信息，若未找到，返回未找到用户异常信息
POST /users	创建一个新的用户

Spring MVC为我们提供了一些很有用的功能，以帮助我们解决系统的异常信息，并将有用的提示信息返回给API客户端。

以 POST /users 创建一个新用户为例，当我们提供正常的用户数据并请求此接口时，REST API将返回如下的提示信息：

{
  "id": 2,
  "username": "wukong",
  "age": 52,
  "height": 170
}

现在，将用户年龄修改为200岁，身高修改为500厘米，用户名为rulai ,在此请求此REST API，观察API的返回信息：

{
  "restapierror": {
    "status": "BAD_REQUEST",
    "timestamp": "2019-05-19 06:04:47",
    "message": "Validation error",
    "subErrors": [
      {
        "object": "user",
        "field": "height",
        "rejectedValue": 500,
        "message": "用户身高不能超过250厘米"
      },
      {
        "object": "user",
        "field": "age",
        "rejectedValue": 200,
        "message": "用户年龄不能超过120岁"
      }
    ]
  }
}

如上所示，当API客户端提供不正确的数据时，REST API返回了格式良好的异常提示信息，timestamp由原来的整形时间戳格式化为一个可读的日期+时间，同时还详细列举了详细的错误报告。

2. 包装异常信息

为了能够提供一个可读的JSON格式异常信息给API客户端，我们需要在项目中引入Jackson JSR 310的依赖包，使用其提供的@JsonFormat注解将Java中的日期和时间按照我们给定的日期和时间模板进行格式化。现在，将下面的依赖包加入的Maven pom.xml文件中：

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

依赖就绪后，我们需要提供一个异常信息的包装类：RestApiError。它将负责对REST API抛出的异常信息进行封装：

public class RestApiError {

    private HttpStatus status;

    @JsonFormat(shape = JsonFormat.Shape.STRING,pattern = "yyyy-MM-dd hh:mm:ss")
    private LocalDateTime timestamp;

    private String message;

    private String debugMessage;

    private List<RestApiSubError> subErrors;

    private RestApiError(){
        timestamp = LocalDateTime.now();
    }

    RestApiError(HttpStatus status){
        this();
        this.status = status;
    }

    RestApiError(HttpStatus status,Throwable ex){
        this();
        this.status = status;
        this.message = "Unexpected error";
        this.debugMessage = ex.getLocalizedMessage();
    }

    RestApiError(HttpStatus status,String message,Throwable ex){
        this();
        this.status = status;
        this.message = message;
        this.debugMessage = ex.getLocalizedMessage();
    }
}

status 属性用于记录响应状态。它沿用了HttpStatus的所有状态吗，如4xx和5xx。
timestamp属性用于记录发送错误的时间
message属性用于记录自定义的异常消息，通常是对API客户端友好的提示信息
debugMessage属性用于记录更为详细的错误报告
subErrors属性用于记录异常附带的子异常信息，如用户实体中字段校验信息等

RestApiSubError类用于记录更为细致的异常信息，通常为实体类中字段校验失败的异常报告：

abstract class RestApiSubError{}
@Data
@EqualsAndHashCode(callSuper = false)
@AllArgsConstructor
class RestApiValidationError extends RestApiSubError{
    private String object;
    private String field;
    private Object rejectedValue;
    private String message;

    RestApiValidationError(String object,String message){
        this.object = object;
        this.message = message;
    }
}

RestApiSubError类是一个抽象的空类，具体的扩展将在RestApiValidationError中进行实现。RestApiValidationError类将记录实体类中（如本讲中的User对象）属性校验失败报告。

现在，我们来校验GET /users/1 API,检索用户ID为1的用户信息：

{
  "id": 1,
  "username": "ramostear",
  "age": 28,
  "height": 170
}

REST API成功的返回了用户信息，接下来我们传入一个系统不存在的用户ID，看看REST API返回什么信息：

GET /users/100

{
  "restapierror": {
    "status": "NOT_FOUND",
    "timestamp": "2019-05-19 06:31:17",
    "message": "User was not found for parameters {id=100}"
  }
}

通过上述的JSON信息我们可以看到，检索不存在的用户信息，REST API返回了友好的提示信息。在一开始的时候我们测试提供不合符规范的用户年龄和身高信息，接下来我们在来测试一下提供一个空的用户名，观察REST API返回的信息：

{
  "restapierror": {
    "status": "BAD_REQUEST",
    "timestamp": "2019-05-19 06:37:46",
    "message": "Validation error",
    "subErrors": [
      {
        "object": "user",
        "field": "username",
        "rejectedValue": "",
        "message": "不能为空"
      }
    ]
  }
}

3. Spring Boot 处理异常信息的流程

Spring Boot 处理REST API异常信息将会涉及到三个注解：

@RestController : 负责处理REST API具体操作逻辑的注解
@ExceptionHandler : 负责处理@RestController标注的类中抛出的异常的注解
@ControllerAdvice : 能够将@ExceptionHandler标注的方法集中到一个地方进行处理的注解

@ControllerAdivice注解是在Spring 3.2版本中新增的一个注解，它能够将单个由@ExceptionHandler注解标注的方法应用到多个控制器中。使用它的好处是我们可以在一个统一的地方同时处理多个控制器抛出的异常，当控制器有异常抛出时，ControllerAdvice会根据当前抛出的异常类型，自动匹配对应的ExceptionHandler;当没有特定的Exception可用时，将调用默认的异常信息处理类来处理控制器抛出的异常（默认的异常信息处理类）。

下面，我们通过一张流程示例图，更为直观的了解Spring Application处理控制器异常信息的全部过程：

在图中，蓝色箭头表示正常的请求和响应过程，红色箭头表示发生异常的请求和响应过程。

4. 自定义异常信息处理类

Spring Framework自带的异常信息处理类往往不能满足我们实际的业务需求，这就需要我们定义符合具体情况的异常信息处理类,在自定义异常信息处理类中，我们可以封装更为详细的异常报告。

自定义异常信息处理类，我们可以站在“巨人”的肩膀上，快速封装自己的异常信息处理类，而不必要从头开始造“轮子”。现在，为了快熟实现自定义异常信息处理类，并让其正常工作，我们可以直接扩展Spring 提供的ResponseEntityExceptionHandler类来定义用户异常信息处理类。ResponseEntityExceptionHandler已经提供了很多可用的功能，我们只需要扩展该类或者覆盖其提供的方法即可。

打开ResponseEntityExceptionHandler类，我们可以看到如下的源码：

public abstract class ResponseEntityExceptionHandler {
    
 //不支持的HTTP请求方法异常信息处理方法
 protected ResponseEntity<Object> handleHttpRequestMethodNotSupported(...){...}
//不支持的HTTP媒体类型异常处理方法
 protected ResponseEntity<Object> handleHttpMediaTypeNotSupported(...){...}   
//不接受的HTTP媒体类型异常处方法
 protected ResponseEntity<Object> handleHttpMediaTypeNotAcceptable(...){...}
 //请求路径参数缺失异常处方法
 protected ResponseEntity<Object> handleMissingPathVariable(...){...}   
 //缺少servlet请求参数异常处理方法   
 protected ResponseEntity<Object> handleMissingServletRequestParameter(...){...}
 //servlet请求绑定异常
 protected ResponseEntity<Object> handleServletRequestBindingException(...){...}   
//不支持转换
 protected ResponseEntity<Object> handleConversionNotSupported(...){...}
 //类型不匹配
 protected ResponseEntity<Object> handleTypeMismatch(...){...}
 //消息无法检索
 protected ResponseEntity<Object> handleHttpMessageNotReadable(...){...}
 //HTTP消息不可写
 protected ResponseEntity<Object> handleHttpMessageNotWritable(...){...}
 //方法参数无效
 protected ResponseEntity<Object> handleMethodArgumentNotValid(...){...}
 //缺少servlet请求部分
 protected ResponseEntity<Object> handleMissingServletRequestPart(...){...}
 //绑定异常
 protected ResponseEntity<Object> handleBindException(...){...}
 //没有发现处理程序异常
 protected ResponseEntity<Object> handleNoHandlerFoundException(...){...}   
 //异步请求超时异常   
 @Nullable
 protected ResponseEntity<Object> handleAsyncRequestTimeoutException(...){...}
 //内部异常
 protected ResponseEntity<Object> handleExceptionInternal(...){...}       
}

我们选择性的覆盖几个常用的异常处理方法，并添加我们自定义异常处理方法：

public class RestExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    protected ResponseEntity<Object> handleUserNotFound(UserNotFoundException ex){
        RestApiError apiError = new RestApiError(HttpStatus.NOT_FOUND);
        apiError.setMessage(ex.getMessage());
        return buildResponseEntity(apiError);
    }


    @Override
    protected ResponseEntity<Object> handleMissingServletRequestParameter(
            MissingServletRequestParameterException ex, HttpHeaders headers,
            HttpStatus status, WebRequest request) {
        String error = ex.getParameterName() + " parameter is missing";
        return buildResponseEntity(new RestApiError(BAD_REQUEST, error, ex));
    }



    @Override
    protected ResponseEntity<Object> handleHttpMediaTypeNotSupported(
            HttpMediaTypeNotSupportedException ex,
            HttpHeaders headers,
            HttpStatus status,
            WebRequest request) {
        StringBuilder builder = new StringBuilder();
        builder.append(ex.getContentType());
        builder.append(" media type is not supported. Supported media types are ");
        ex.getSupportedMediaTypes().forEach(t -> builder.append(t).append(", "));
        return buildResponseEntity(new RestApiError(HttpStatus.UNSUPPORTED_MEDIA_TYPE, builder.substring(0, builder.length() - 2), ex));
    }
    
    ...

}

UserNotFoundException类为我们自定义异常信息类，在执行GET /users/{userIds}或 GET /users请求时，如果数据库中不存在该ID的记录信息，将抛出UserNotFoundException异常信息,且将响应状态码设置为NOT_FOUND。UserNotFoundException源码如下：

public class UserNotFoundException extends Exception {

    public UserNotFoundException(Class clz,String...searchParams){
        super(UserNotFoundException.generateMessage(clz.getSimpleName(),toMap(String.class,String.class,searchParams)));
    }

    private static String generateMessage(String entity, Map<String,String> searchParams){
        return StringUtils.capitalize(entity)+
                " was not found for parameters "+
                searchParams;
    }

    private static <K,V> Map<K,V> toMap(Class<K> key,Class<V> value,Object...entries){
        if(entries.length % 2 == 1){
            throw new IllegalArgumentException("Invalid entries");
        }
        return IntStream.range(0,entries.length/2).map(i->i*2)
                .collect(HashMap::new,
                        (m,i)->m.put(key.cast(entries[i]),value.cast(entries[i+1])),Map::putAll);
    }
}

下图将更为直观的说明自定义异常处理的整个流程：

当UserService发生异常时，异常信息将向上传递到UserController,此时的异常信息被Spring所捕获，并将其跳转到UserNotFoundException处理方法中。UserNotFoundException将异常报告封装到RestApiError对象中，并回传给API Client。通过此方法，API客户端将获得一份逻辑清晰的响应报告。

本次课程的全部源码已经上传到 Github 仓库，你可以点击此链接获取源码：https://github.com/ramostear/...
原文：https://www.ramostear.com/art...

(六讲)Spring Boot REST API异常处理指南

1. 定义明确的异常信息

2. 包装异常信息

3. Spring Boot 处理异常信息的流程

4. 自定义异常信息处理类

谭朝红

引用和评论

CKEditor 5 + SpringBoot实战(四)：SpringBoot 实现文件上传

MyBatis-Plus结合Spring Boot实现数据权限

70k star，取代Postman！这款轻量级API工具，太香了！

Spring Integration 轻松实现服务间消息传递，真香！

Nginx转发WebSocket到Spring Cloud Gateway并路由到Spring Boot服务

Spring Cloud中MyBatis-Plus动态数据源刷新问题

Spring AI与DeepSeek实战一：快速打造智能对话应用