Spring Boot 异常处理：如何让你的应用在异常面前依然优雅地跳舞？

🏆本文收录于「滚雪球学SpringBoot」专栏(全网一个名)，手把手带你零基础入门Spring Boot，从入门到就业，助你早日登顶实现财富自由🚀；同时，欢迎大家关注&&收藏&&订阅！持续更新中，up！up！up！！

环境说明：Windows 10 + IntelliJ IDEA 2021.3.2 + Jdk 1.8

前言：

每当我们的应用遇到错误或异常时，处理这些异常的方式直接影响到用户体验以及应用的稳定性。作为开发者，我们必须了解并掌握如何在 Spring Boot 中优雅地处理这些异常。

Spring Boot 提供了一整套丰富且灵活的异常处理机制，从全局异常处理到精细化的局部异常捕获，再到针对 REST API 的错误响应格式化，每一项都能帮助你提升应用的鲁棒性和易用性。

在这篇文章中，我将带你深入理解 Spring Boot 中的异常处理机制，讲解如何通过全局异常处理、@ControllerAdvice、@ExceptionHandler 等注解轻松捕获并处理异常，甚至如何通过自定义异常类与错误响应格式让错误处理更符合你项目的需求。更进一步，我们还将探讨如何支持国际化的错误消息，让全球的用户都能收到他们理解的错误提示。

🔥 Spring Boot 的全局异常处理

在任何应用中，异常的出现都是不可避免的。为了避免每次异常发生时都手动处理，Spring Boot 提供了非常强大的全局异常处理机制。全局异常处理让我们能够集中处理应用中的所有异常，而无需在每个 Controller 中重复代码。

1. 使用 @ControllerAdvice 实现全局异常处理

@ControllerAdvice 是 Spring 提供的一个用于集中处理异常的注解。它可以用来定义全局异常处理逻辑，并且可以捕获到应用中的所有异常。通常，@ControllerAdvice 会与 @ExceptionHandler 注解结合使用，用于指定具体如何处理不同类型的异常。

以下是一个使用 @ControllerAdvice 处理异常的基本示例：

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(Exception.class)
    public ResponseEntity<String> handleException(Exception e) {
        return new ResponseEntity<>("Global error: " + e.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

在这个例子中，@ControllerAdvice 注解使得 GlobalExceptionHandler 成为一个全局异常处理器。@ExceptionHandler 注解指定了当系统抛出 Exception 类型的异常时，应该调用 handleException 方法进行处理。

2. 处理特定类型的异常

当然，我们不希望所有的异常都通过一个统一的处理方法来处理。我们可以通过 @ExceptionHandler 注解为不同的异常类型提供不同的处理方法。例如，处理 NullPointerException 和 ArithmeticException：

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(NullPointerException.class)
    public ResponseEntity<String> handleNullPointerException(NullPointerException e) {
        return new ResponseEntity<>("Null pointer exception occurred: " + e.getMessage(), HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(ArithmeticException.class)
    public ResponseEntity<String> handleArithmeticException(ArithmeticException e) {
        return new ResponseEntity<>("Arithmetic exception occurred: " + e.getMessage(), HttpStatus.BAD_REQUEST);
    }
}

通过这种方式，我们可以根据异常的类型来选择不同的响应处理逻辑，使得异常处理更加灵活和精准。

🛠️ @ControllerAdvice 与 @ExceptionHandler 的使用

1. @ControllerAdvice 注解的作用

@ControllerAdvice 主要用于全局处理 Spring MVC 层的异常。它的作用范围不仅限于 @RestController 或 @Controller，而是能够全局捕获应用中所有 Controller 层抛出的异常。它相当于对应用中所有 Controller 的全局配置。

2. @ExceptionHandler 注解的作用

@ExceptionHandler 注解与 @ControllerAdvice 配合使用，用于指定捕获某个特定异常类型并定义其处理逻辑。你可以在 @ControllerAdvice 类中使用多个 @ExceptionHandler 方法，以便针对不同的异常类型进行不同的处理。

例子：

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleResourceNotFound(ResourceNotFoundException ex) {
        ErrorResponse errorResponse = new ErrorResponse("RESOURCE_NOT_FOUND", ex.getMessage());
        return new ResponseEntity<>(errorResponse, HttpStatus.NOT_FOUND);
    }

    @ExceptionHandler(ValidationException.class)
    public ResponseEntity<ErrorResponse> handleValidationException(ValidationException ex) {
        ErrorResponse errorResponse = new ErrorResponse("VALIDATION_ERROR", ex.getMessage());
        return new ResponseEntity<>(errorResponse, HttpStatus.BAD_REQUEST);
    }
}

这里，我们为 ResourceNotFoundException 和 ValidationException 定义了不同的处理方法。在异常发生时，Spring Boot 会自动调用相应的处理方法。

🧩 自定义异常类与错误响应格式

1. 自定义异常类

在实际开发中，我们经常需要根据业务需求自定义异常类，以便更加灵活地处理不同场景下的异常。例如，我们可以定义一个 ResourceNotFoundException 类，来表示找不到资源的异常。

public class ResourceNotFoundException extends RuntimeException {

    public ResourceNotFoundException(String message) {
        super(message);
    }
}

2. 错误响应格式

为了保持错误响应的一致性，我们可以定义一个统一的错误响应格式。通常，我们会使用一个 ErrorResponse 类来封装错误的详细信息，如错误代码、错误消息等。

public class ErrorResponse {

    private String errorCode;
    private String errorMessage;

    // 构造函数、getters 和 setters
}

然后，在异常处理器中使用该类来返回统一的错误响应格式：

@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ErrorResponse> handleResourceNotFound(ResourceNotFoundException ex) {
    ErrorResponse errorResponse = new ErrorResponse("RESOURCE_NOT_FOUND", ex.getMessage());
    return new ResponseEntity<>(errorResponse, HttpStatus.NOT_FOUND);
}

这样，所有的错误响应就会遵循统一的格式，增强了系统的可维护性和一致性。

🌐 REST API 异常处理

当我们在构建 RESTful API 时，错误响应不仅仅是为了服务端调试，更多的是为了客户端处理错误并给用户提供友好的提示。因此，设计一个清晰且一致的错误响应格式是非常重要的。

1. 标准化错误响应格式

为了确保 API 的一致性，我们应该为 API 设计一个统一的错误响应格式。例如，我们可以定义一个包含错误代码、错误信息和时间戳的响应体。

{
    "status": "error",
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found",
    "timestamp": "2023-09-16T12:34:56Z"
}

2. 处理 REST API 中的常见异常

在 RESTful API 中，我们通常会遇到一些常见的异常，如资源未找到 (404)，请求参数错误 (400) 等。这些异常都应该被精确捕获，并返回统一格式的错误响应。

@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<Map<String, Object>> handleResourceNotFound(ResourceNotFoundException ex) {
    Map<String, Object> response = new HashMap<>();
    response.put("status", "error");
    response.put("code", "RESOURCE_NOT_FOUND");
    response.put("message", ex.getMessage());
    response.put("timestamp", LocalDateTime.now());
    return new ResponseEntity<>(response, HttpStatus.NOT_FOUND);
}

3. 使用 ResponseEntity 处理错误响应

ResponseEntity 是 Spring 提供的一个通用类，用于封装 HTTP 响应。它不仅可以设置响应体，还可以设置 HTTP 状态码，非常适合用于 RESTful API 的错误处理。

@ExceptionHandler(ValidationException.class)
public ResponseEntity<Map<String, Object>> handleValidationException(ValidationException ex) {
    Map<String, Object> response = new HashMap<>();
    response.put("status", "error");
    response.put("code", "VALIDATION_ERROR");
    response.put("message", ex.getMessage());
    response.put("timestamp", LocalDateTime.now());
    return new ResponseEntity<>(response, HttpStatus.BAD_REQUEST);
}

🌍 统一错误处理与国际化支持

1. 统一错误处理

在 Spring Boot 中，我们可以通过 @ControllerAdvice 进行全局异常处理，但如何处理多语言环境下的错误信息呢？这就需要用到国际化支持。

2. 国际化错误消息

Spring Boot 提供了非常方便的国际化支持，我们可以通过 MessageSource 来加载不同语言的错误消息。例如，定义 messages.properties 和 messages_zh.properties 两个文件，分别用于默认和中文的错误消息。

# messages.properties
error.resourceNotFound=Resource not found

# messages_zh.properties
error.resourceNotFound=资源未找到

然后，在异常处理中使用国际化消息：

@Autowired
private MessageSource messageSource;

@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<Map<String, Object>> handleResourceNotFound(ResourceNotFoundException ex, Locale locale) {
    Map<String, Object> response = new HashMap<>();
    response.put("status", "error");
    response.put("code", "RESOURCE_NOT_FOUND");
    response.put("message", messageSource.getMessage("error.resourceNotFound", null, locale));
    response.put("timestamp", LocalDateTime.now());
    return new ResponseEntity<>(response, HttpStatus.NOT_FOUND);
}

通过 locale 参数，我们可以根据用户的语言环境返回相应的错误消息，实现国际化的错误处理。

结语：

今天，我们深入探讨了 Spring Boot 中的异常处理机制，从全局异常处理、局部异常捕获，到 RESTful API 中的错误响应格式，再到国际化支持，涵盖了异常处理的方方面面。

无论是简单的异常处理，还是复杂的自定义异常类和多语言错误响应，Spring Boot 都提供了非常灵活且易于使用的解决方案。掌握这些技巧，你的应用将能更好地应对各种异常情况，提供稳定、友好的用户体验。

希望通过本文，你能对 Spring Boot 的异常处理有更深的理解，并能将其应用到你的项目中。记住，异常不可避免，但优雅地处理异常是每个开发者的责任！✨

🧧福利赠与你🧧

  无论你是计算机专业的学生，还是对编程有兴趣的小伙伴，都建议直接毫无顾忌的学习此专栏「滚雪球学SpringBoot」专栏(全网一个名)，bug菌郑重承诺，凡是学习此专栏的同学，均能获取到所需的知识和技能，全网最快速入门SpringBoot，就像滚雪球一样，越滚越大， 无边无际，指数级提升。

  最后，如果这篇文章对你有所帮助，帮忙给作者来个一键三连，关注、点赞、收藏，您的支持就是我坚持写作最大的动力。

  同时欢迎大家关注公众号:「猿圈奇妙屋」 ，以便学习更多同类型的技术文章，免费白嫖最新BAT互联网公司面试题、4000G pdf电子书籍、简历模板、技术文章Markdown文档等海量资料。

✨️ Who am I?

我是bug菌(全网一个名)，CSDN | 掘金 | InfoQ | 51CTO | 华为云 | 阿里云 | 腾讯云 等社区博客专家，C站博客之星Top30，华为云多年度十佳博主/价值贡献奖，掘金多年度人气作者Top40，掘金等各大社区平台签约作者，51CTO年度博主Top12，掘金/InfoQ/51CTO等社区优质创作者；全网粉丝合计 30w+；更多精彩福利点击这里；硬核微信公众号「猿圈奇妙屋」，欢迎你的加入！免费白嫖最新BAT互联网公司面试真题、4000G PDF电子书籍、简历模板等海量资料，你想要的我都有，关键是你不来拿。

-End-