Spring Boot 优雅的全局异常处理指南

在 Spring Boot 中实现全局异常处理可以提升应用的健壮性、维护性以及用户体验。以下是详细方案与最佳实践。

1. 使用 @ControllerAdvice 和 @ExceptionHandler

这是最常用的全局异常处理方式，通过统一捕获异常并返回结构化响应。

@RestControllerAdvice
public class GlobalExceptionHandler {

    // 处理业务异常
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ErrorResponse> handleBusinessException(BusinessException ex) {
        ErrorResponse errorResponse = new ErrorResponse(
            ex.getErrorCode(), 
            ex.getMessage(), 
            System.currentTimeMillis()
        );
        return new ResponseEntity<>(errorResponse, HttpStatus.BAD_REQUEST);
    }

    // 处理数据校验异常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationExceptions(MethodArgumentNotValidException ex) {
        List<String> errors = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(FieldError::getDefaultMessage)
            .collect(Collectors.toList());

        ErrorResponse errorResponse = new ErrorResponse(
            "VALIDATION_ERROR",
            "Validation failed: " + String.join(", ", errors),
            System.currentTimeMillis()
        );
        return new ResponseEntity<>(errorResponse, HttpStatus.BAD_REQUEST);
    }

    // 处理未捕获的所有异常
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleAllExceptions(Exception ex) {
        ErrorResponse errorResponse = new ErrorResponse(
            "INTERNAL_SERVER_ERROR",
            "An unexpected error occurred",
            System.currentTimeMillis()
        );
        return new ResponseEntity<>(errorResponse, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

2. 自定义错误响应结构

统一的错误响应格式让前端更易解析，也便于日志追踪。

@Data
@AllArgsConstructor
@NoArgsConstructor
public class ErrorResponse {
    private String code;
    private String message;
    private long timestamp;
    private List<String> details; // 可选：详细错误信息
}

3. 自定义业务异常类

业务异常专门用于处理应用逻辑层的错误。

public class BusinessException extends RuntimeException {
    private final String errorCode;

    public BusinessException(String errorCode, String message) {
        super(message);
        this.errorCode = errorCode;
    }

    public String getErrorCode() {
        return errorCode;
    }
}

4. 使用 ResponseStatusException（简单场景）

对于简单的资源不存在等情况，可以直接抛出带状态码的异常。

@GetMapping("/resource/{id}")
public Resource getResource(@PathVariable Long id) {
    return repository.findById(id)
        .orElseThrow(() -> new ResponseStatusException(
            HttpStatus.NOT_FOUND, "Resource not found"));
}

5. 处理特定框架异常

例如 JPA 的 EntityNotFoundException：

@ExceptionHandler(EntityNotFoundException.class)
public ResponseEntity<ErrorResponse> handleEntityNotFound(EntityNotFoundException ex) {
    ErrorResponse errorResponse = new ErrorResponse(
        "NOT_FOUND",
        ex.getMessage(),
        System.currentTimeMillis()
    );
    return new ResponseEntity<>(errorResponse, HttpStatus.NOT_FOUND);
}

6. 日志记录

即便用户看到的错误信息简洁，也应在日志中记录详细堆栈信息：

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleAllExceptions(Exception ex, WebRequest request) {
    logger.error("Unhandled exception occurred: {}", ex.getMessage(), ex);

    ErrorResponse errorResponse = new ErrorResponse(
        "INTERNAL_SERVER_ERROR",
        "An unexpected error occurred",
        System.currentTimeMillis()
    );
    return new ResponseEntity<>(errorResponse, HttpStatus.INTERNAL_SERVER_ERROR);
}

7. 国际化支持

通过 MessageSource 结合 Locale，可以实现错误消息的国际化：

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorResponse> handleValidationExceptions(
    MethodArgumentNotValidException ex, Locale locale) {

    List<String> errors = ex.getBindingResult()
        .getFieldErrors()
        .stream()
        .map(error -> messageSource.getMessage(error, locale))
        .collect(Collectors.toList());

    ErrorResponse errorResponse = new ErrorResponse(
        "VALIDATION_ERROR",
        "Validation failed: " + String.join(", ", errors),
        System.currentTimeMillis()
    );
    return new ResponseEntity<>(errorResponse, HttpStatus.BAD_REQUEST);
}

8. 全局异常处理结构图（简化）

GlobalExceptionHandler
├── BusinessException -> HTTP 400
├── MethodArgumentNotValidException -> HTTP 400
├── EntityNotFoundException -> HTTP 404
├── ResponseStatusException -> 对应HTTP状态
└── Exception (通用异常) -> HTTP 500

最佳实践

1. 分类处理异常：业务异常、系统异常、第三方服务异常分别处理。
2. 友好的错误信息：避免暴露敏感信息或堆栈细节给用户。
3. 统一响应格式：保持所有错误响应一致，方便前端解析。
4. 适当HTTP状态码：根据异常类型返回合理的状态码。
5. 详细日志记录：用户看到简洁信息，但日志记录完整错误与堆栈。

这个方案可确保你的 Spring Boot 应用在出现异常时，既用户体验友好，又便于运维排查。