Spring Boot 中如何统一处理全局异常？

Question

在Spring Boot应用开发中，如何实现全局异常的统一处理是构建健壮Web服务的关键之一。常见的问题是：如何通过@ControllerAdvice或@ExceptionHandler实现自定义异常处理机制，以统一返回结构清晰、格式一致的错误信息？开发者常面临如重复代码、异常捕获不全面、响应格式不统一等问题。此外，如何区分处理Controller层、Service层及系统级异常，并返回对应的HTTP状态码与错误描述，也是实际应用中常见的挑战。本文将围绕这些问题，深入探讨Spring Boot中统一处理全局异常的最佳实践。

Answer 1

一、理解Spring Boot异常处理机制

在Spring Boot中，异常处理是构建健壮Web服务的关键环节。默认情况下，Spring Boot已经提供了基本的异常处理机制，例如当Controller方法抛出异常时，会自动返回500错误。但这种默认机制往往无法满足企业级应用对错误信息结构化、状态码精确化、日志可追溯等方面的需求。

为实现统一的异常处理机制，Spring Boot提供了两种主要方式：

• @ExceptionHandler：用于单个Controller内部的异常处理。
• @ControllerAdvice：用于全局异常处理，适用于整个应用的所有Controller。

通常建议使用@ControllerAdvice来实现全局异常统一处理，避免重复代码，并提升系统的可维护性。

二、定义统一的错误响应结构

为了确保错误信息结构清晰、格式一致，首先应定义一个统一的错误响应实体类，例如：

public class ErrorResponse {
    private int status;
    private String message;
    private String timestamp;

    // 构造方法、Getter和Setter
}
    

该结构应包含：

• HTTP状态码
• 错误信息描述
• 时间戳

在实际开发中，还可以根据需要扩展字段，例如错误码、堆栈信息等。

三、使用@ControllerAdvice实现全局异常捕获

通过@ControllerAdvice可以创建一个全局异常处理器类，捕获来自各个Controller抛出的异常。

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity handleResourceNotFoundException(ResourceNotFoundException ex) {
        ErrorResponse error = new ErrorResponse();
        error.setStatus(HttpStatus.NOT_FOUND.value());
        error.setMessage(ex.getMessage());
        error.setTimestamp(LocalDateTime.now().toString());
        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity handleGeneralException(Exception ex) {
        ErrorResponse error = new ErrorResponse();
        error.setStatus(HttpStatus.INTERNAL_SERVER_ERROR.value());
        error.setMessage("Internal server error");
        error.setTimestamp(LocalDateTime.now().toString());
        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}
    

通过上述方式，可以针对不同类型的异常进行分类处理，返回不同的状态码和错误信息。

四、区分处理不同层级的异常

在实际项目中，异常可能来源于多个层级：

• Controller层：参数绑定错误、请求路径错误等。
• Service层：业务逻辑错误、资源未找到等。
• 系统级异常：数据库连接失败、第三方服务调用失败等。

为了统一处理这些异常，可以定义不同的自定义异常类，并在@ControllerAdvice中分别捕获处理。

异常类型	示例	HTTP状态码	处理方式
Controller层异常	MethodArgumentNotValidException	400	参数校验失败
Service层异常	ResourceNotFoundException	404	资源未找到
系统级异常	DataAccessException	500	数据库异常

五、结合Validation进行参数校验异常处理

在Spring Boot中，可以通过@Valid注解对Controller方法的参数进行校验。若校验失败，默认会抛出MethodArgumentNotValidException。

为了统一处理此类异常，可以在@ControllerAdvice中添加相应的处理逻辑：

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity handleValidationExceptions(MethodArgumentNotValidException ex) {
    String errorMessage = ex.getBindingResult()
            .getAllErrors()
            .stream()
            .map(ObjectError::getDefaultMessage)
            .collect(Collectors.joining(", "));
    ErrorResponse error = new ErrorResponse();
    error.setStatus(HttpStatus.BAD_REQUEST.value());
    error.setMessage(errorMessage);
    error.setTimestamp(LocalDateTime.now().toString());
    return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
}
    

通过这种方式，可以将参数校验错误以统一结构返回给前端，增强接口的健壮性和可读性。

六、异常处理流程图

以下是一个典型的Spring Boot全局异常处理流程图：

graph TD
            A[客户端请求] --> B[进入Controller方法]
            B --> C{是否发生异常?}
            C -->|是| D[进入@ExceptionHandler处理]
            D --> E[根据异常类型返回ErrorResponse]
            C -->|否| F[正常返回结果]
            D --> G[记录日志]
            E --> H[返回JSON格式错误信息]