Spring中的全局异常处理：@ControllerAdvice与@ExceptionHandler

开场白

大家好，欢迎来到今天的Spring技术讲座！今天我们要聊的是一个非常实用的话题——如何在Spring中优雅地处理全局异常。相信很多同学在开发过程中都遇到过这样的问题：当用户输入了错误的参数，或者数据库查询失败时，系统会抛出各种各样的异常。如果我们不妥善处理这些异常，用户可能会看到一些莫名其妙的错误信息，甚至导致整个应用崩溃。那么，如何才能让我们的应用更加健壮，给用户提供友好的提示呢？答案就是——使用@ControllerAdvice和@ExceptionHandler来实现全局异常处理！

什么是全局异常处理？

在传统的Web开发中，我们通常会在每个控制器方法中手动捕获异常，比如：

@GetMapping("/user/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    try {
        User user = userService.findById(id);
        if (user == null) {
            throw new UserNotFoundException("User not found");
        }
        return ResponseEntity.ok(user);
    } catch (Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
    }
}

这样做虽然可以捕获异常，但代码看起来很冗长，而且每个控制器方法都要重复类似的逻辑。想象一下，如果你有几十个、上百个控制器方法，那将是多么痛苦的一件事！

为了解决这个问题，Spring提供了@ControllerAdvice和@ExceptionHandler注解，它们可以帮助我们集中处理所有控制器中的异常，从而简化代码并提高可维护性。

@ControllerAdvice的作用

@ControllerAdvice是一个类级别的注解，它可以让Spring知道这个类是用来处理全局异常的。你可以把它理解为一个“异常处理中心”，所有的控制器都可以共享这个类中的异常处理逻辑。

举个例子，假设我们有一个简单的用户管理模块，可能会抛出以下几种异常：

UserNotFoundException：当用户不存在时抛出。
InvalidRequestException：当请求参数无效时抛出。
DatabaseException：当数据库操作失败时抛出。

我们可以创建一个全局异常处理器类，使用@ControllerAdvice注解来捕获这些异常：

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleUserNotFoundException(UserNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }

    @ExceptionHandler(InvalidRequestException.class)
    public ResponseEntity<String> handleInvalidRequestException(InvalidRequestException ex) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(ex.getMessage());
    }

    @ExceptionHandler(DatabaseException.class)
    public ResponseEntity<String> handleDatabaseException(DatabaseException ex) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("Database error occurred");
    }

    // 可以继续添加更多的异常处理方法
}

为什么使用@ControllerAdvice？

集中管理：所有异常处理逻辑都集中在@ControllerAdvice标注的类中，避免了在每个控制器中重复编写异常处理代码。
灵活性：你可以根据不同的异常类型返回不同的HTTP状态码和响应内容，甚至可以根据异常的不同来源（如控制器、服务层等）进行不同的处理。
可扩展性：如果将来需要添加新的异常处理逻辑，只需要在@ControllerAdvice类中新增一个方法即可，而不需要修改现有的控制器代码。

@ExceptionHandler的作用

@ExceptionHandler是一个方法级别的注解，它用于指定某个方法应该处理哪种类型的异常。你可以将它与@ControllerAdvice结合使用，也可以单独用在某个控制器类中。

1. 全局异常处理

当我们把@ExceptionHandler放在@ControllerAdvice标注的类中时，它就会成为全局异常处理器，捕获所有控制器中抛出的异常。例如，上面的例子中，handleUserNotFoundException方法会捕获所有控制器中抛出的UserNotFoundException异常，并返回404状态码和相应的错误信息。

2. 局部异常处理

如果你只想在某个特定的控制器中处理异常，可以在该控制器类中使用@ExceptionHandler。这种方式适用于那些只在特定场景下才会发生的异常。例如：

@RestController
@RequestMapping("/api/users")
public class UserController {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleUserNotFoundException(UserNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }

    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        User user = userService.findById(id);
        if (user == null) {
            throw new UserNotFoundException("User not found");
        }
        return ResponseEntity.ok(user);
    }
}

在这个例子中，handleUserNotFoundException方法只会捕获UserController类中抛出的UserNotFoundException异常，而不会影响其他控制器。

3. 多个异常处理

你还可以在一个方法中处理多个异常类型。例如：

@ExceptionHandler({UserNotFoundException.class, InvalidRequestException.class})
public ResponseEntity<String> handleExceptions(Exception ex) {
    if (ex instanceof UserNotFoundException) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body("User not found");
    } else if (ex instanceof InvalidRequestException) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Invalid request");
    }
    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("Unknown error");
}

这种方式可以减少代码的冗余，尤其是在多个异常处理逻辑相似的情况下。

返回自定义错误响应

除了简单的字符串响应，我们还可以返回更复杂的错误信息。例如，返回一个包含错误代码、错误消息和详细描述的JSON对象。为了实现这一点，我们可以定义一个自定义的错误响应类：

public class ErrorResponse {
    private int code;
    private String message;
    private String description;

    // Getters and Setters
}

然后在异常处理方法中返回这个对象：

@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<ErrorResponse> handleUserNotFoundException(UserNotFoundException ex) {
    ErrorResponse error = new ErrorResponse();
    error.setCode(404);
    error.setMessage("User not found");
    error.setDescription(ex.getMessage());

    return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
}

这样，客户端接收到的响应将是一个结构化的JSON对象，而不是简单的字符串。这对于前端开发人员来说非常友好，因为他们可以根据错误代码和消息来做出相应的处理。

日志记录

在实际项目中，除了返回友好的错误信息给用户，我们还需要记录异常的日志，以便后续排查问题。Spring为我们提供了方便的日志记录工具，比如org.slf4j.Logger。我们可以在异常处理方法中添加日志记录逻辑：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@ControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger logger = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleUserNotFoundException(UserNotFoundException ex) {
        logger.error("User not found: {}", ex.getMessage(), ex);
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }

    // 其他异常处理方法...
}

通过这种方式，我们可以在控制台或日志文件中记录每次异常的发生情况，帮助我们更好地调试和优化系统。

异常优先级

有时候，你可能会遇到多个异常处理方法都能捕获同一个异常的情况。那么，Spring是如何决定哪个方法应该优先执行呢？

根据Spring的文档，异常处理方法的优先级是按照以下顺序排列的：

局部异常处理：如果在当前控制器中定义了@ExceptionHandler方法，那么它会优先于全局异常处理器。
具体异常类型：如果多个全局异常处理方法都能捕获同一个异常，那么最具体的异常类型会被优先执行。例如，@ExceptionHandler(UserNotFoundException.class)会优先于@ExceptionHandler(Exception.class)。
顺序声明：如果两个异常处理方法的优先级相同，那么Spring会按照它们在类中声明的顺序来执行。先声明的方法会优先执行。

因此，在设计异常处理逻辑时，我们应该尽量遵循从具体到一般的顺序，确保最合适的处理方法能够被优先执行。

总结

通过今天的讲座，我们学习了如何使用@ControllerAdvice和@ExceptionHandler来实现Spring中的全局异常处理。相比于传统的逐个捕获异常的方式，这种方式不仅简化了代码，还提高了系统的可维护性和扩展性。我们还讨论了如何返回自定义的错误响应、记录异常日志以及异常处理的优先级问题。

希望今天的分享对大家有所帮助！如果有任何问题，欢迎在评论区留言交流。谢谢大家！

参考资料：

Spring Framework Documentation
Spring Boot Reference Guide
Effective Java by Joshua Bloch

祝大家 coding 愉快！