Spring Boot REST API 统一异常处理最佳实践

// Controller 示例
@GetMapping("/{id}")
public ResponseEntity<curse> getCursaById (@PathVariable("id") Long id) {
    curse c = curseService.findCurseById(id);
    return new ResponseEntity<>(c, HttpStatus.OK);
}

// 位于同一控制器内的异常处理器
@ResponseStatus(HttpStatus.NOT_FOUND)
@ExceptionHandler(CursaNotFoundException.class)
public String noCursaFound(CursaNotFoundException ex) {
    return ex.getMessage();
}

// 自定义异常
public class CursaNotFoundException extends RuntimeException {
    public CursaNotFoundException(String s) {
        super(s);
    }
}

// ApiError.java
public class ApiError {
    private String message;
    private String code; // 可选，用于更精确地标识错误类型

    public ApiError() {
    }

    public ApiError(String message, String code) {
        this.message = message;
        this.code = code;
    }

    // Getters and Setters
    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }
}

// GlobalExceptionHandler.java
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 {

    /**
     * 处理 CursaNotFoundException 异常
     * 当 CursaNotFoundException 被抛出时，返回 HTTP 404 NOT_FOUND 和 ApiError 对象
     */
    @ExceptionHandler(value = CursaNotFoundException.class)
    public ResponseEntity<ApiError> handleCursaNotFoundException(CursaNotFoundException ex) {
        ApiError error = new ApiError();
        error.setMessage(ex.getMessage());
        // 假设 CursaNotFoundException 有一个 getCode() 方法，或者可以设置一个默认的错误码
        // 如果自定义异常没有 getCode() 方法，可直接设置固定错误码
        error.setCode("CURSA_NOT_FOUND"); 
        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }

    /**
     * 处理所有未被特定 @ExceptionHandler 捕获的通用异常
     * 当其他任何 Exception 被抛出时，返回 HTTP 500 INTERNAL_SERVER_ERROR 和 ApiError 对象
     */
    @ExceptionHandler(value = Exception.class)
    public ResponseEntity<ApiError> handleGenericException(Exception ex) {
        ApiError error = new ApiError();
        // 生产环境中，通常不直接返回详细异常信息，而是返回一个通用错误消息
        error.setMessage("An unexpected error occurred. Please try again later."); 
        error.setCode("GENERIC_ERROR");
        // 详细异常信息应记录到日志中，例如：logger.error("Unhandled exception: ", ex);
        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }

    // 可以根据业务需求添加更多针对特定异常的处理器
    // @ExceptionHandler(value = IllegalArgumentException.class)
    // public ResponseEntity<ApiError> handleIllegalArgumentException(IllegalArgumentException ex) {
    //     ApiError error = new ApiError(ex.getMessage(), "INVALID_ARGUMENT");
    //     return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
    // }
}

// CursaNotFoundException.java (更新版本，可选)
public class CursaNotFoundException extends RuntimeException {
    private String code;

    public CursaNotFoundException(String message) {
        super(message);
        this.code = "CURSA_NOT_FOUND"; // 默认错误码
    }

    public CursaNotFoundException(String message, String code) {
        super(message);
        this.code = code;
    }

    public String getCode() {
        return code;
    }
}