在spring boot应用中，尤其当与前端框架如angular集成时，推荐采用统一的rest api异常处理策略。核心思想是后端不进行页面重定向，而是返回结构化的json错误响应（如包含错误消息和错误码的`apierror`对象），并利用`@controlleradvice`实现全局异常捕获。前端根据接收到的错误响应进行相应的ui展示或导航。
在构建现代化的前后端分离应用时，后端API的异常处理机制对于提升用户体验和系统稳定性至关重要。传统的服务器端页面重定向已不再适用于RESTful API，因为前端框架（如Angular、React、Vue）需要通过API响应来感知错误并自主地进行视图渲染或导航。本文将深入探讨Spring Boot中处理REST API异常的最佳实践。
传统异常处理方式的局限性
在单个控制器方法上使用@ResponseStatus和@ExceptionHandler注解可以处理特定的异常，例如：
@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();
}</curse>
以及自定义异常类：
public class CursaNotFoundException extends RuntimeException {
public CursaNotFoundException(String s) {
super(s);
}
}
这种方式的局限性在于：
- 分散性： 每个控制器都需要重复定义异常处理逻辑，导致代码冗余且难以维护。
- 不统一： 返回的错误信息可能只是一个简单的字符串，缺乏结构化，不利于前端解析和展示。
- 不适用于前后端分离： 返回字符串或进行服务器端HTML页面重定向不符合RESTful API的设计原则，前端无法直接消费。
推荐的异常处理策略：全局统一与结构化响应
为了克服上述局限性，推荐采用以下策略：
1. 定义结构化的错误响应体
后端在发生异常时，应返回一个包含详细错误信息的结构化对象，通常是JSON格式。这使得前端能够清晰地解析错误类型、消息和可能的错误码。
public class ApiError {
private String message; // 错误消息
private String code; // 错误码，可用于前端进行特定处理
// 可以根据需要添加更多字段，例如：
// private HttpStatus status; // HTTP状态码
// private LocalDateTime timestamp; // 错误发生时间
// private String path; // 请求路径
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;
}
}
2. 使用 @ControllerAdvice 实现全局异常处理
@ControllerAdvice 注解允许您定义一个全局的异常处理器，捕获所有控制器抛出的特定类型异常。这极大地简化了异常处理逻辑，并确保了错误响应的统一性。
创建一个全局异常处理类：
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() 方法
// 如果没有，可以硬编码一个错误码或从消息中提取
error.setCode("CURSA_NOT_FOUND"); // 或者 ex.getCode()
return new ResponseEntity(error, HttpStatus.NOT_FOUND);
}
/**
* 处理所有未被特定处理的 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: " + ex.getMessage());
error.setCode("GENERIC_ERROR");
// 实际应用中，这里应该记录详细日志，但避免在响应中暴露敏感信息
return new ResponseEntity(error, HttpStatus.INTERNAL_SERVER_ERROR);
}
// 可以添加更多 @ExceptionHandler 方法来处理其他特定异常，例如：
// @ExceptionHandler(MethodArgumentNotValidException.class)
// public ResponseEntity<apierror> handleValidationExceptions(MethodArgumentNotValidException ex) {
// // 处理验证失败异常，提取所有字段错误信息
// String errorMessage = ex.getBindingResult().getFieldErrors().stream()
// .map(error -> error.getField() + ": " + error.getDefaultMessage())
// .collect(Collectors.joining(", "));
// ApiError error = new ApiError(errorMessage, "VALIDATION_ERROR");
// return new ResponseEntity(error, HttpStatus.BAD_REQUEST);
// }
}</apierror></apierror></apierror>
在这个GlobalExceptionHandler中：
- @ControllerAdvice 确保这个类能够“建议”所有控制器。
- @ExceptionHandler(value = CursaNotFoundException.class) 专门捕获 CursaNotFoundException，并返回一个HttpStatus.NOT_FOUND的ApiError响应。
- @ExceptionHandler(value = Exception.class) 作为一个兜底的处理器，捕获所有未被其他@ExceptionHandler处理的通用Exception，并返回HttpStatus.INTERNAL_SERVER_ERROR。
前后端协作：前端如何处理错误
当后端按照上述方式返回结构化的ApiError响应时，前端（如Angular）可以通过HTTP客户端（如HttpClient）拦截这些错误响应：
import { Injectable } from '@angular/core';
import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpErrorResponse } from '@angular/common/http';
import { Observable, throwError } from 'rxjs';
import { catchError } from 'rxjs/operators';
import { Router } from '@angular/router';
@Injectable()
export class ErrorInterceptor implements HttpInterceptor {
constructor(private router: Router) {}
intercept(request: HttpRequest<any>, next: HttpHandler): Observable<httpevent>> {
return next.handle(request).pipe(
catchError((error: HttpErrorResponse) => {
let errorMessage = 'An unknown error occurred!';
let errorCode = 'UNKNOWN_ERROR';
if (error.error instanceof ErrorEvent) {
// 客户端或网络错误
errorMessage = `Error: ${error.error.message}`;
} else {
// 后端返回的错误
if (error.error && error.error.message) {
errorMessage = error.error.message;
errorCode = error.error.code || errorCode;
} else if (error.message) {
errorMessage = error.message;
}
switch (error.status) {
case 404:
// 资源未找到
console.error(`404 Not Found: ${errorMessage}`);
// 例如，可以重定向到自定义的404页面
this.router.navigate(['/not-found']);
break;
case 500:
// 服务器内部错误
console.error(`500 Internal Server Error: ${errorMessage}`);
// 例如，可以重定向到错误提示页面
this.router.navigate(['/error']);
break;
// 其他状态码处理
default:
console.error(`HTTP Error ${error.status}: ${errorMessage}`);
break;
}
}
// 将错误重新抛出，以便其他订阅者也能处理
return throwError(() => new Error(errorMessage));
})
);
}
}</httpevent></any>
通过HTTP拦截器，前端可以统一处理所有API请求的错误，根据ApiError中的message和code来显示用户友好的提示信息，或者根据HTTP状态码和错误码进行页面重定向（例如，跳转到404页面或通用错误页面）。
注意事项与最佳实践
- 日志记录： 在GlobalExceptionHandler中，务必记录详细的异常堆栈信息，以便于问题排查。但切勿将敏感信息直接暴露给客户端。
- 错误码： 设计一套清晰、有意义的错误码体系，有助于前后端对错误进行精确识别和处理。
- 国际化： 如果应用需要支持多语言，错误消息也应进行国际化处理。
- 安全性： 避免在错误响应中暴露过多的内部实现细节或敏感数据。
- 自定义异常： 对于业务逻辑中特定的错误场景，创建自定义的RuntimeException（如CursaNotFoundException）是良好的实践，它能更清晰地表达业务含义。
- HTTP状态码： 正确使用HTTP状态码（如400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error）来反映错误的性质。
总结
在Spring Boot构建RESTful API时，采用@ControllerAdvice配合结构化ApiError响应的全局异常处理方案，是与前端框架（如Angular）良好协作的最佳实践。这种方法不仅实现了异常处理的统一管理，提高了代码的可维护性，还为前端提供了清晰、可消费的错误信息，从而提升了整个应用的健壮性和用户体验。通过前后端的紧密协作，可以构建出更加稳定和用户友好的应用。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
