Spring Boot 配置全局异常通用返回

在Spring Boot开发中，异常处理是一个非常重要的部分。良好的异常处理能够提升系统的健壮性，提升用户体验，并帮助开发者在系统运行过程中快速定位问题。在Spring Boot项目中，我们不仅需要捕获异常，还需要为前端返回一个友好且规范的错误信息。本文将详细讲解如何配置Spring Boot中的全局异常处理，并展示通用的异常返回机制。

目录

1. Spring Boot异常处理概述
2. 全局异常处理的作用和意义
3. Spring Boot异常处理的方式
   • 3.1 使用 @ControllerAdvice 注解
   • 3.2 使用 @ExceptionHandler 注解
   • 3.3 使用 @ResponseStatus 注解
4. 创建一个通用的异常返回体
5. 全局异常处理案例
   • 5.1 自定义异常类
   • 5.2 配置 @ControllerAdvice
   • 5.3 异常返回封装类
   • 5.4 完整示例
6. 异常处理常见场景与实例
   • 6.1 参数校验失败的处理
   • 6.2 业务逻辑异常的处理
   • 6.3 系统异常的处理
7. 总结与建议

Spring Boot 异常处理概述

在开发过程中，我们难免会遇到一些异常（例如请求参数错误、数据库连接失败等）。如果没有有效的异常处理机制，系统很容易暴露出不友好的错误信息，甚至导致程序崩溃。因此，我们需要在Spring Boot项目中对这些异常进行有效的捕获和处理，并返回给用户一个标准化、易于理解的错误信息。

Spring Boot提供了多种异常处理的方式，可以通过配置全局异常处理来实现对系统中所有异常的统一处理。通过全局异常处理，可以减少代码的冗余性，并确保不同类型的异常得到合理的处理。

全局异常处理的作用和意义

1.1 增强系统健壮性

通过全局异常处理，我们可以有效地捕获系统中的各种异常，避免系统崩溃或返回无意义的错误信息。例如，如果有一个数据库连接失败的异常，系统可以返回一个友好的错误提示，而不是直接抛出堆栈跟踪。

1.2 统一异常格式

在没有全局异常处理机制的情况下，不同模块或不同层次的异常处理可能会返回不同格式的错误信息，造成前端或其他调用方的不便。而全局异常处理可以统一返回的格式，使得接口调用者更加容易理解和处理错误。

1.3 业务异常与系统异常分离

在全局异常处理中，我们可以将业务逻辑异常和系统异常进行区分，并为它们定义不同的返回信息。这样可以帮助前端开发者更准确地处理错误，例如业务异常可以引导用户进行正确的操作，而系统异常则可能需要开发者介入。

1.4 改进用户体验

全局异常处理还能够提升用户体验。如果系统捕获到异常并返回了清晰、明确的错误信息，用户就能够理解发生了什么问题，并采取相应的措施。与之相对的是，如果返回的是堆栈信息或其他难以理解的信息，用户就很难解决问题。

Spring Boot 异常处理的方式

Spring Boot提供了几种方式来处理异常，主要有以下几种：

2.1 使用 @ControllerAdvice 注解

@ControllerAdvice 是Spring MVC提供的一个注解，它允许你定义全局的异常处理逻辑，并将其应用到所有的控制器。使用@ControllerAdvice，你可以统一处理控制器中的异常，避免每个控制器都重复写异常处理代码。

2.2 使用 @ExceptionHandler 注解

@ExceptionHandler注解可以用于处理特定控制器内的异常。当控制器中发生异常时，@ExceptionHandler会捕获该异常并执行相应的处理逻辑。可以在控制器内部使用这个注解，也可以通过@ControllerAdvice结合@ExceptionHandler来处理全局的异常。

2.3 使用 @ResponseStatus 注解

@ResponseStatus注解用于设置HTTP响应状态码。它可以与异常类一起使用，在异常抛出时自动返回指定的HTTP状态码。这种方式适用于异常处理返回的状态码与特定的异常类型相关联的场景。

创建一个通用的异常返回体

为了使异常返回格式统一，我们通常需要封装一个标准的返回体，确保每次返回给前端的错误信息都包括错误码、错误信息和时间戳等关键信息。一个常见的返回体通常包括以下字段：

• code：错误码，用于标识错误类型
• message：错误信息，描述错误发生的原因
• timestamp：发生异常的时间戳，便于后续问题定位

javaCopy Code
public class ErrorResponse {
    private int code;
    private String message;
    private long timestamp;

    // 构造方法，getter和setter
}

例如，我们可以定义几个常见的错误码来表示不同类型的错误：

• 400: 请求参数错误
• 401: 用户未授权
• 500: 系统内部错误

这样，前端开发者就可以根据返回的code字段来处理不同的错误情形。

全局异常处理案例

下面，我们来具体实现一个Spring Boot的全局异常处理机制。

4.1 自定义异常类

首先，我们可以定义几个常见的业务异常类，例如参数验证异常和用户未授权异常。

javaCopy Code
public class CustomException extends RuntimeException {
    private int code;

    public CustomException(int code, String message) {
        super(message);
        this.code = code;
    }

    public int getCode() {
        return code;
    }
}

4.2 配置 @ControllerAdvice

然后，我们通过@ControllerAdvice注解来处理全局异常。

javaCopy Code
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(CustomException.class)
    public ResponseEntity<ErrorResponse> handleCustomException(CustomException ex) {
        ErrorResponse response = new ErrorResponse();
        response.setCode(ex.getCode());
        response.setMessage(ex.getMessage());
        response.setTimestamp(System.currentTimeMillis());
        return new ResponseEntity<>(response, HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGeneralException(Exception ex) {
        ErrorResponse response = new ErrorResponse();
        response.setCode(500);
        response.setMessage("系统内部错误");
        response.setTimestamp(System.currentTimeMillis());
        return new ResponseEntity<>(response, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

4.3 异常返回封装类

接下来，我们定义一个统一的错误返回体类ErrorResponse，用于封装异常信息并返回给前端。

javaCopy Code
public class ErrorResponse {
    private int code;
    private String message;
    private long timestamp;

    // 构造方法，getter和setter
}

4.4 完整示例

javaCopy Code
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
public class SpringBootExceptionHandlingApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringBootExceptionHandlingApplication.class, args);
    }
}

@RestController
class MyController {

    @GetMapping("/error")
    public String throwError() {
        throw new CustomException(400, "请求参数错误");
    }
}

4.5 测试与效果

启动Spring Boot应用程序并访问/error接口，可以看到系统返回以下错误信息：

jsonCopy Code
{
    "code": 400,
    "message": "请求参数错误",
    "timestamp": 1634267284000
}

异常处理常见场景与实例

5.1 参数校验失败的处理

在很多情况下，接口接收到的请求参数可能不符合预期，这时我们可以通过@Valid注解对请求参数进行校验，并使用全局异常处理来捕获参数校验失败的异常。

javaCopy Code
@Valid
public class User {
    @NotNull(message = "用户名不能为空")
    private String username;

    @Min(value = 18, message = "年龄必须大于18岁")
    private int age;

    // Getter和Setter
}

5.2 业务逻辑异常的处理

在业务逻辑层，某些特定的业务