本文旨在深入探讨spring boot rest api中异常处理的最佳实践，重点介绍如何通过自定义异常、`@controlleradvice`进行全局异常处理，以及在控制器内部使用`@exceptionhandler`进行局部处理。文章将指导开发者避免使用通用`exception`，构建清晰、可维护且响应友好的错误处理机制，确保api的健壮性和用户体验。
在构建Spring Boot RESTful API时，有效的异常处理是确保应用健壮性和提供良好用户体验的关键。不恰当的异常处理可能导致API返回模糊的错误信息、不正确的HTTP状态码，甚至泄露内部实现细节。本教程将指导您如何以专业和高效的方式处理Spring Boot REST API中的异常。
避免使用通用 Exception
在服务层或任何业务逻辑层中，直接抛出或捕获通用的java.lang.Exception是一种不推荐的做法。通用异常缺乏语义，使得调用者难以理解具体发生了什么错误，也无法针对性地进行处理。
不推荐的做法示例：
public Optional<Item> getSpecificItem(Long itemId) throws Exception {
// 这种方式会抛出通用的Exception，缺乏具体语义
return Optional.ofNullable(itemRepository.findById(itemId).
orElseThrow(() -> new Exception("Item with that id doesn't exist")));
}相反，我们应该创建并使用具有业务含义的自定义异常。
创建自定义异常
自定义异常能够清晰地表达业务逻辑中可能出现的特定错误情况。例如，当请求的商品不存在时，可以定义一个ItemNotFoundException。
// ItemNotFoundException.java
public class ItemNotFoundException extends RuntimeException {
public ItemNotFoundException(String message) {
super(message);
}
}服务层使用自定义异常：
在服务层中，当业务规则被违反时，抛出这些自定义异常。
import org.springframework.stereotype.Service;
import java.util.Optional;
@Service
public class ItemService {
private final ItemRepository itemRepository; // 假设有一个ItemRepository
public ItemService(ItemRepository itemRepository) {
this.itemRepository = itemRepository;
}
public Item getSpecificItem(Long itemId) {
return itemRepository.findById(itemId)
.orElseThrow(() -> new ItemNotFoundException("Item with id " + itemId + " does not exist"));
}
}全局异常处理：@ControllerAdvice
对于跨多个控制器或整个应用中需要统一处理的异常，Spring Boot提供了@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;
import org.springframework.web.bind.annotation.ResponseStatus;
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ItemNotFoundException.class)
@ResponseStatus(HttpStatus.NOT_FOUND) // 设置HTTP状态码为404
public ResponseEntity<String> handleItemNotFoundException(ItemNotFoundException ex) {
// 可以返回一个自定义的错误对象，这里简单返回错误信息
return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
}
// 可以定义更多针对其他自定义异常的处理器
// @ExceptionHandler(AnotherBusinessException.class)
// @ResponseStatus(HttpStatus.BAD_REQUEST)
// public ResponseEntity<ErrorResponse> handleAnotherBusinessException(AnotherBusinessException ex) {
// return new ResponseEntity<>(new ErrorResponse("BAD_REQUEST", ex.getMessage()), HttpStatus.BAD_REQUEST);
// }
// 捕获所有未被特定处理的异常 (谨慎使用，可能隐藏具体错误)
// @ExceptionHandler(Exception.class)
// @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
// public ResponseEntity<String> handleGenericException(Exception ex) {
// return new ResponseEntity<>("An unexpected error occurred: " + ex.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
// }
}@ExceptionHandler注解：用于指定当前方法将处理哪种类型的异常。 @ResponseStatus注解：直接在处理方法上设置响应的HTTP状态码。如果返回ResponseEntity，则可以在其中设置状态码。
控制器内部异常处理：@ExceptionHandler
除了全局@ControllerAdvice，您也可以在特定的控制器类内部使用@ExceptionHandler。这种方式适用于处理仅与该控制器相关，或者需要该控制器特有逻辑的异常。
示例：控制器内部异常处理
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class ItemController {
private final ItemService itemService;
public ItemController(ItemService itemService) {
this.itemService = itemService;
}
@GetMapping("/items/{itemId}")
public Item getItem(@PathVariable Long itemId) {
return itemService.getSpecificItem(itemId);
}
// 仅为此控制器处理ItemNotFoundException
@ExceptionHandler(ItemNotFoundException.class)
@ResponseStatus(HttpStatus.NOT_FOUND)
public String handleItemNotFoundInThisController(ItemNotFoundException ex) {
// 可以返回一个自定义的错误信息，这里简单返回异常消息
return "Error: " + ex.getMessage();
}
}何时选择控制器内部处理？
- 当异常处理逻辑高度特化，仅适用于某个特定控制器，并且不希望影响其他控制器时。
- 当您需要访问控制器特有的上下文信息来生成错误响应时。
优先级： 如果一个异常同时被@ControllerAdvice和控制器内部的@ExceptionHandler捕获，控制器内部的@ExceptionHandler会优先被执行。
总结与最佳实践
- 避免通用 Exception： 永远不要在业务逻辑中直接抛出或声明throws Exception。这会使代码难以理解和维护。
- 创建自定义异常： 为您的业务场景定义具体、语义化的自定义异常（例如ItemNotFoundException、InvalidInputException等）。这些异常通常继承自RuntimeException，避免强制捕获。
- 使用 @ControllerAdvice 进行全局处理： 对于大多数业务异常和系统异常（如MethodArgumentNotValidException、NoHandlerFoundException），使用@ControllerAdvice提供一个集中的、统一的异常处理机制。这能确保API响应的一致性。
- 使用 @ExceptionHandler 进行局部处理： 仅当异常处理逻辑高度特化，仅与某个特定控制器相关时，才考虑在控制器内部使用@ExceptionHandler。
- 返回有意义的错误响应： 异常处理方法应返回清晰、有用的错误信息，并设置正确的HTTP状态码（例如，资源未找到返回404 NOT_FOUND，无效请求返回400 BAD_REQUEST，服务器内部错误返回500 INTERNAL_SERVER_ERROR）。可以考虑定义一个统一的错误响应对象。
- 日志记录： 在异常处理方法中，务必记录异常详情，以便后续排查问题。
通过遵循这些实践，您的Spring Boot REST API将拥有一个健壮、可维护且用户友好的异常处理系统。
