Spring Boot REST API 异常处理最佳实践：面向前端分离架构

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;
    }
}

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 {

    // 假设这是您的自定义业务异常
    public static class CursaNotFoundException extends RuntimeException {
        private String errorCode;

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

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

        public String getErrorCode() {
            return errorCode;
        }
    }

    /**
     * 处理 CursaNotFoundException 异常
     * 当课程未找到时，返回 404 NOT_FOUND 状态码和结构化错误信息
     */
    @ExceptionHandler(value = CursaNotFoundException.class)
    public ResponseEntity<ApiError> handleCursaNotFoundException(CursaNotFoundException ex) {
        ApiError error = new ApiError();
        error.setMessage(ex.getMessage());
        error.setCode(ex.getErrorCode()); // 使用自定义异常中的错误码
        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }

    /**
     * 处理所有未被特定 @ExceptionHandler 捕获的通用 Exception
     * 作为回退机制，返回 500 INTERNAL_SERVER_ERROR 状态码和通用错误信息
     */
    @ExceptionHandler(value = Exception.class)
    public ResponseEntity<ApiError> handleGenericException(Exception ex) {
        ApiError error = new ApiError();
        error.setMessage("服务器内部错误，请稍后重试。"); // 避免泄露敏感信息
        error.setCode("GENERIC_ERROR");
        // 生产环境中，此处应记录详细日志
        System.err.println("发生未知异常: " + ex.getMessage());
        ex.printStackTrace();
        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class CurseController {

    private final CurseService curseService; // 假设有一个CurseService

    public CurseController(CurseService curseService) {
        this.curseService = curseService;
    }

    @GetMapping("/curses/{id}")
    public ResponseEntity<Curse> getCursaById(@PathVariable("id") Long id) {
        // findCurseById() 方法可能会抛出 CursaNotFoundException
        Curse c = curseService.findCurseById(id);
        return new ResponseEntity<>(c, HttpStatus.OK);
    }
}

// 假设 CurseService 及其方法
interface CurseService {
    Curse findCurseById(Long id);
}

// 假设 Curse 类
class Curse {
    private Long id;
    private String name;
    // ... getters and setters
}

// Angular service example
import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { Observable, throwError } from 'rxjs';
import { catchError } from 'rxjs/operators';

interface ApiError {
  message: string;
  code: string;
}

interface Curse {
  id: number;
  name: string;
}

// ...
export class CurseService {
  constructor(private http: HttpClient) {}

  getCurseById(id: number): Observable<Curse> {
    return this.http.get<Curse>(`/api/curses/${id}`).pipe(
      catchError(this.handleError)
    );
  }

  private handleError(error: HttpErrorResponse) {
    let errorMessage = '未知错误！';
    if (error.error instanceof ErrorEvent) {
      // 客户端或网络错误
      errorMessage = `客户端错误: ${error.error.message}`;
    } else {
      // 后端返回的错误响应
      const apiError: ApiError = error.error;
      if (apiError && apiError.message) {
        errorMessage = `后端错误: ${apiError.message} (Code: ${apiError.code || 'N/A'})`;
      } else {
        errorMessage = `后端返回错误状态码: ${error.status}, 错误信息: ${error.message}`;
      }
    }
    console.error(errorMessage);
    // 可以在这里根据错误码进行路由跳转，例如：
    // if (error.status === 404 && error.error.code === 'CURSA_NOT_FOUND') {
    //   this.router.navigate(['/not-found']);
    // }
    return throwError(() => new Error(errorMessage));
  }
}