当前位置：首页 > article >正文

Spring 中的 @ExceptionHandler 注解详解与应用

article 2025/1/5 11:44:25

在开发 Web 应用程序时，异常处理是一个至关重要的部分。无论是用户输入错误，还是系统内部错误，如何优雅地处理这些异常，直接影响到用户体验和系统的可靠性。Spring 提供了强大的异常处理机制，其中 @ExceptionHandler 注解就是一个核心组件。本文将详细介绍 @ExceptionHandler 注解的用法及其最佳实践。

一、什么是 `@ExceptionHandler` 注解？

@ExceptionHandler 是 Spring 提供的一个注解，用于在控制器类中处理特定类型的异常。当控制器中的某个方法抛出异常时，Spring 会根据异常的类型调用相应的异常处理方法。这种方式不仅简化了异常处理逻辑，还提升了代码的可读性和维护性。

二、基本用法

2.1 处理单一异常

让我们从一个简单的例子开始。在下面的代码中，我们创建了一个控制器，当 test 方法抛出 RuntimeException异常时，handleRuntimeException 方法将会被调用。

@RestController
public class MyController {

    @GetMapping("/test")
    public String test() {
        if (true) { // 模拟一个错误
            throw new RuntimeException("发生了一个错误！");
        }
        return "Success";
    }

    @ExceptionHandler(RuntimeException.class)
    public ResponseEntity<String> handleRuntimeException(RuntimeException ex) {
        // 自定义异常处理逻辑
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(ex.getMessage());
    }
}

在上面的例子中，@ExceptionHandler(RuntimeException.class) 注解的方法负责处理 RuntimeException。当这种异常发生时，用户将收到一个 HTTP 500 错误和错误信息。

2.2 处理多个异常

有时候，你可能希望一个方法处理多种类型的异常。这可以通过在 @ExceptionHandler 注解中传入多个异常类来实现：

@ExceptionHandler({IllegalArgumentException.class, NullPointerException.class})
public ResponseEntity<String> handleMultipleExceptions(Exception ex) {
    return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("错误: " + ex.getMessage());
}

这个方法可以同时处理 IllegalArgumentException 和 NullPointerException，并返回 HTTP 400 错误。

三、全局异常处理

在实际项目中，你可能希望将所有的异常处理逻辑集中在一个地方。为此，Spring 提供了 @ControllerAdvice 注解，它允许你定义全局异常处理器。

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(RuntimeException.class)
    public ResponseEntity<String> handleRuntimeException(RuntimeException ex) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(ex.getMessage());
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<String> handleGenericException(Exception ex) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("发生错误: " + ex.getMessage());
    }
}

在上面的例子中，GlobalExceptionHandler 类使用 @ControllerAdvice 注解，标记为一个全局的异常处理器。这样，整个应用程序中的所有控制器都可以使用这些异常处理方法。

四、结合 `@ResponseStatus` 注解

在某些情况下，你可能希望为异常处理方法指定一个特定的 HTTP 状态码。这可以通过在方法上使用 @ResponseStatus 注解来实现：

@ExceptionHandler(IllegalStateException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public String handleIllegalStateException(IllegalStateException ex) {
    return "非法状态: " + ex.getMessage();
}

这里，@ResponseStatus(HttpStatus.BAD_REQUEST) 指定了当 IllegalStateException 发生时，返回 HTTP 400 错误。

五、`@ExceptionHandler` 方法的参数

@ExceptionHandler 方法不仅可以接收异常对象本身，还可以接收其他参数，如 WebRequest 或 HttpServletRequest，以便访问请求的上下文信息。例如：

@ExceptionHandler(RuntimeException.class)
public ResponseEntity<String> handleRuntimeException(RuntimeException ex, WebRequest request) {
    String requestPath = request.getDescription(false);
    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("在 " + requestPath + " 发生错误: " + ex.getMessage());
}

在这个示例中，WebRequest 对象用于获取请求的描述信息，并在异常消息中返回。