手把手教你封装一个异常处理类（Spring Boot 全局统一异常处理实战）

视频看了几百小时还迷糊？关注我，几分钟让你秒懂！

🧩 一、为什么需要统一异常处理？

在没有统一异常处理前，你的代码可能是这样的：

@GetMapping("/user/{id}") public ResponseEntity<?> getUser(@PathVariable Long id) { try { User user = userService.findById(id); return ResponseEntity.ok(user); } catch (UserNotFoundException e) { return ResponseEntity.status(404).body("用户不存在"); } catch (Exception e) { log.error("查询用户出错", e); return ResponseEntity.status(500).body("系统繁忙"); } }

问题很明显：

• 每个接口都要写try-catch，重复代码多；
• 错误信息不统一，前端解析困难；
• 异常日志分散，排查问题难；
• HTTP 状态码混乱（有的返回 200 却 body 是错误）。

✅目标：
一处定义，全局生效；结构清晰，前后端解耦；日志完整，便于监控。

🛠️ 二、Spring Boot 正确姿势：@ControllerAdvice+@ExceptionHandler

1. 定义统一返回格式

import lombok.Data; import java.time.LocalDateTime; @Data public class ApiResult<T> { private int code; private String message; private T data; private LocalDateTime timestamp; public static <T> ApiResult<T> success(T data) { ApiResult<T> result = new ApiResult<>(); result.code = 200; result.message = "success"; result.data = data; result.timestamp = LocalDateTime.now(); return result; } public static <T> ApiResult<T> error(int code, String message) { ApiResult<T> result = new ApiResult<>(); result.code = code; result.message = message; result.timestamp = LocalDateTime.now(); return result; } }

💡 前端只需要判断code == 200就知道成功，无需解析 HTTP 状态码！

2. 自定义业务异常类

public class BusinessException extends RuntimeException { private final int code; public BusinessException(int code, String message) { super(message); this.code = code; } public BusinessException(String message) { this(400, message); // 默认 400 } public int getCode() { return code; } }

✅ 业务异常 vs 系统异常：

• BusinessException：参数错误、余额不足等可预期错误；
• RuntimeException：空指针、数据库连接失败等不可预期错误。

3. 全局异常处理器（核心！）

import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.http.HttpStatus; import org.springframework.validation.BindException; import org.springframework.web.bind.MethodArgumentNotValidException; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.ResponseStatus; import org.springframework.web.bind.annotation.RestControllerAdvice; import javax.servlet.http.HttpServletRequest; import java.util.stream.Collectors; @RestControllerAdvice public class GlobalExceptionHandler { private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class); // 处理自定义业务异常 @ExceptionHandler(BusinessException.class) public ApiResult<?> handleBusinessException(BusinessException e, HttpServletRequest request) { log.warn("业务异常 | URI: {} | Error: {}", request.getRequestURI(), e.getMessage()); return ApiResult.error(e.getCode(), e.getMessage()); } // 处理参数校验异常（JSR-303） @ExceptionHandler(MethodArgumentNotValidException.class) @ResponseStatus(HttpStatus.BAD_REQUEST) public ApiResult<?> handleValidationException(MethodArgumentNotValidException e) { String message = e.getBindingResult().getFieldErrors().stream() .map(error -> error.getField() + ": " + error.getDefaultMessage()) .collect(Collectors.joining("; ")); log.warn("参数校验失败: {}", message); return ApiResult.error(400, "请求参数错误: " + message); } // 处理路径变量/请求参数类型转换错误 @ExceptionHandler(IllegalArgumentException.class) @ResponseStatus(HttpStatus.BAD_REQUEST) public ApiResult<?> handleIllegalArgumentException(IllegalArgumentException e) { log.warn("非法参数: {}", e.getMessage()); return ApiResult.error(400, "参数格式错误"); } // 处理所有未捕获的系统异常（兜底） @ExceptionHandler(Exception.class) @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR) public ApiResult<?> handleSystemException(Exception e, HttpServletRequest request) { // 生产环境不要暴露堆栈给前端！ log.error("系统异常 | URI: {} | Error: {}", request.getRequestURI(), e.getMessage(), e); return ApiResult.error(500, "系统繁忙，请稍后再试"); } }

🔑 关键点：

• @RestControllerAdvice=@ControllerAdvice+@ResponseBody；
• 按异常类型分层处理；
• 生产环境绝不返回e.printStackTrace()给前端！

🧪 三、使用示例

1. 业务层抛出异常

@Service public class UserService { public User findById(Long id) { if (id <= 0) { throw new BusinessException("用户ID必须大于0"); } // ... 查询逻辑 if (user == null) { throw new BusinessException(404, "用户不存在"); } return user; } }

2. Controller 无需 try-catch

@RestController @RequestMapping("/api/user") public class UserController { @Autowired private UserService userService; @GetMapping("/{id}") public ApiResult<User> getUser(@PathVariable Long id) { User user = userService.findById(id); // 可能抛出 BusinessException return ApiResult.success(user); // 成功时直接返回 } }

3. 调用效果

• 请求/api/user/0→ 返回：

{ "code": 400, "message": "用户ID必须大于0", "data": null, "timestamp": "2026-01-29T12:00:00" }

• 请求/api/user/999（不存在）→ 返回：

{ "code": 404, "message": "用户不存在", "data": null, "timestamp": "2026-01-29T12:00:01" }

✅ 前端只需判断code，无需关心 HTTP 状态码！

❌ 四、反例 & 常见错误

反例 1：在 Controller 里到处写 try-catch

// ❌ 重复、难维护、风格不统一 @GetMapping("/user/{id}") public Object getUser(@PathVariable Long id) { try { // ... } catch (Exception e) { return Map.of("error", e.getMessage()); } }

反例 2：把系统异常堆栈返回给前端

@ExceptionHandler(Exception.class) public String handle(Exception e) { return e.toString(); // 😱 前端看到一长串堆栈！ }

💥 风险：泄露服务器路径、框架版本、数据库结构！

反例 3：所有异常都返回 200

// ❌ HTTP 状态码始终是 200，违背 RESTful 原则 public Map<String, Object> error(String msg) { return Map.of("code", 500, "msg", msg); }

✅ 正确：HTTP 状态码 + JSON body 双重语义。

⚠️ 五、注意事项 & 最佳实践

🎯 六、总结：统一异常处理架构图

Controller 方法 ↓ 抛出 BusinessException / ValidationException / Exception ↓ GlobalExceptionHandler 拦截 ↓ 按类型返回标准化 ApiResult ↓ 前端统一处理 code == 200 ?

好处：

• ✅ 代码简洁，专注业务；
• ✅ 错误格式统一，前后端协作顺畅；
• ✅ 日志完整，便于运维；
• ✅ 符合 RESTful 规范。

视频看了几百小时还迷糊？关注我，几分钟让你秒懂！