为什么需要自定义异常？
在构建restful api时，http状态码是客户端与服务器之间沟通请求结果的基础。例如，404 not found表示资源不存在，400 bad request表示请求参数有误，409 conflict表示请求与目标资源的当前状态冲突。然而，仅仅依赖这些通用的http状态码往往不足以提供足够的上下文信息，尤其是在复杂的业务场景中。
考虑以下场景：
- 当用户尝试访问一个不存在的用户资源时，服务器返回 404 Not Found。
- 当用户尝试注册一个已被占用的用户名时，服务器返回 409 Conflict 或 400 Bad Request。
如果所有“资源未找到”的情况都只返回一个泛泛的 404，那么客户端或终端用户将无法区分是“用户未找到”还是“商品未找到”。同样，一个通用的 400 或 409 也无法明确告知用户是“用户名已存在”还是“邮箱已存在”，或者“订单状态不允许此操作”。
自定义异常（如 UserNotFoundException、NameAlreadyExistsException）的价值在于它们能够携带更具体的业务含义。它们是业务逻辑层面的错误描述，能够清晰地指明问题的类型和原因，从而：
- 提升可读性与可维护性： 开发者通过异常类型即可理解错误发生的原因，无需深入查看错误消息或堆栈。
- 改善用户体验： 客户端可以根据不同的自定义异常向用户展示更精确、更友好的错误提示（例如：“用户不存在，请检查用户名是否正确” vs. “用户名已被占用，请尝试其他名称”）。
- 实现精细化错误处理： 客户端应用程序可以根据接收到的具体异常类型，执行不同的业务逻辑，例如，对于 UserNotFoundException，可以引导用户注册；对于 NameAlreadyExistsException，则提示用户登录或更换名称。
HTTP状态码与自定义异常的协同
自定义异常并非要取代HTTP状态码，而是对其进行补充和增强。最佳实践是让自定义异常与合适的HTTP状态码协同工作。这意味着，虽然你的代码抛出的是 UserNotFoundException，但最终响应给客户端的HTTP状态码仍应是 404 Not Found。
以下是一些常见的映射示例：
- UserNotFoundException / ResourceNotFoundException -> HTTP 404 Not Found
- NameAlreadyExistsException / ResourceConflictException -> HTTP 409 Conflict
- InvalidInputException / ValidationException -> HTTP 400 Bad Request
- UnauthorizedException -> HTTP 401 Unauthorized
- ForbiddenException -> HTTP 403 Forbidden
Spring Boot提供了强大的机制来集中处理这些自定义异常，并将它们映射到相应的HTTP状态码和响应体。
自定义异常的实现与实践
在Spring Boot中，通常通过以下步骤实现和处理自定义异常：
-
定义自定义异常类： 自定义异常通常继承自 RuntimeException（非受检异常），这样在业务代码中抛出时无需强制捕获，简化了代码。
// 用户未找到异常 public class UserNotFoundException extends RuntimeException { public UserNotFoundException(String message) { super(message); } } // 名称已存在异常 public class NameAlreadyExistsException extends RuntimeException { public NameAlreadyExistsException(String message) { super(message); } } // 示例：无效输入异常 public class InvalidInputException extends RuntimeException { public InvalidInputException(String message) { super(message); } } -
在业务逻辑中抛出自定义异常： 在Service层或Controller层，当检测到特定业务错误时，抛出相应的自定义异常。
@Service public class UserService { public User getUserById(Long id) { // 假设从数据库查询用户 User user = userRepository.findById(id) .orElseThrow(() -> new UserNotFoundException("User with ID " + id + " not found.")); return user; } public User createUser(User user) { if (userRepository.existsByName(user.getName())) { throw new NameAlreadyExistsException("Username '" + user.getName() + "' already exists."); } return userRepository.save(user); } } -
全局异常处理： 使用 @ControllerAdvice 和 @ExceptionHandler 注解来创建全局异常处理器，统一捕获和处理这些自定义异常，并生成统一的错误响应。
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 { @ExceptionHandler(UserNotFoundException.class) public ResponseEntityhandleUserNotFoundException(UserNotFoundException ex) { ErrorResponse error = new ErrorResponse(HttpStatus.NOT_FOUND.value(), ex.getMessage()); return new ResponseEntity<>(error, HttpStatus.NOT_FOUND); } @ExceptionHandler(NameAlreadyExistsException.class) public ResponseEntity handleNameAlreadyExistsException(NameAlreadyExistsException ex) { ErrorResponse error = new ErrorResponse(HttpStatus.CONFLICT.value(), ex.getMessage()); return new ResponseEntity<>(error, HttpStatus.CONFLICT); } @ExceptionHandler(InvalidInputException.class) public ResponseEntity handleInvalidInputException(InvalidInputException ex) { ErrorResponse error = new ErrorResponse(HttpStatus.BAD_REQUEST.value(), ex.getMessage()); return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST); } // 可以定义一个通用的错误响应结构 public static class ErrorResponse { private int status; private String message; // Getters and Setters public ErrorResponse(int status, String message) { this.status = status; this.message = message; } public int getStatus() { return status; } public void setStatus(int status) { this.status = status; } public String getMessage() { return message; } public void setMessage(String message) { this.message = message; } } }
通过这种方式，客户端在接收到错误响应时，不仅能看到HTTP状态码（如404），还能在响应体中获取到更具体的错误信息（如{"status": 404, "message": "User with ID 123 not found."}），从而更好地理解和处理错误。
注意事项
- 避免过度设计： 不要为每一个微小的、不影响业务逻辑的差异都创建新的异常类。应关注那些需要客户端采取不同行动或提供不同反馈的业务错误。
- 异常层次结构： 对于一组相关的异常，可以考虑使用继承来创建异常层次结构，例如，所有业务相关的异常都继承自 BusinessException。
- 统一错误响应格式： 确保所有异常处理都返回一个统一的错误响应结构（如包含错误码、错误消息、时间戳等），以便客户端能够一致地解析错误信息。
- 日志记录： 在异常处理器中记录异常，以便于问题排查和监控。
总结
自定义异常在Spring Boot的异常处理中扮演着至关重要的角色。它们通过提供比通用HTTP状态码更丰富的业务上下文，极大地提高了应用程序的健壮性、可维护性和用户友好性。通过合理地定义和处理自定义异常，并将其映射到适当的HTTP状态码，我们可以构建出响应更精确、用户体验更佳的API服务。
