一、先理解什么是全局异常处理器全局异常处理器是基于 Spring 的RestControllerAdvice或ControllerAdvice ExceptionHandler注解实现的组件它能统一捕获项目中所有未被局部捕获的异常并按照统一的格式处理、返回结果替代了传统的 “try-catch 满天飞” 的方式。举个简单的示例import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice; // 标识这是全局异常处理器作用于所有RestController RestControllerAdvice public class GlobalExceptionHandler { // 捕获所有运行时异常最通用的异常类型 ExceptionHandler(RuntimeException.class) public ResultVO handleRuntimeException(RuntimeException e) { // 统一返回格式错误码 错误信息 空数据 return ResultVO.fail(500, 服务器内部错误 e.getMessage()); } // 捕获自定义业务异常项目中最常用 ExceptionHandler(BusinessException.class) public ResultVO handleBusinessException(BusinessException e) { return ResultVO.fail(e.getCode(), e.getMessage()); } // 统一返回体可根据项目需求自定义 public static class ResultVOT { private int code; // 响应码200成功其他失败 private String msg; // 提示信息 private T data; // 响应数据 // 静态构造方法简化调用 public static T ResultVOT fail(int code, String msg) { ResultVOT vo new ResultVO(); vo.code code; vo.msg msg; vo.data null; return vo; } } // 自定义业务异常示例 public static class BusinessException extends RuntimeException { private int code; public BusinessException(int code, String msg) { super(msg); this.code code; } // getter/setter public int getCode() { return code; } } }二、为什么优秀的 Spring Boot 项目必须有它1. 解决 “异常处理碎片化” 问题提升代码可维护性反例糟糕的写法如果没有全局异常处理器你需要在每个 Controller 方法里写 try-catchGetMapping(/user/{id}) public ResultVO getUser(PathVariable Long id) { try { User user userService.getById(id); if (user null) { throw new RuntimeException(用户不存在); } return ResultVO.success(user); } catch (Exception e) { return ResultVO.fail(500, 查询用户失败 e.getMessage()); } }这种写法会导致代码冗余每个接口都要写重复的 try-catch 逻辑维护成本高如果要修改异常返回格式需要改所有接口的 catch 块漏处理风险新手容易忘记加 try-catch导致异常直接抛给前端。正例全局处理器只需在全局处理器中定义一次规则所有接口的异常都会被自动捕获和处理代码简洁且易维护。2. 统一异常返回格式提升前后端协作效率没有全局处理器时不同异常会返回不同格式的结果空指针异常可能返回 Tomcat 的 500 错误页面HTML参数校验异常可能返回 Spring 默认的 JSON 格式字段杂乱业务异常可能返回开发者随手写的字符串。前端开发者需要适配多种异常格式极易出现兼容问题。而全局异常处理器可以强制所有异常返回统一的 JSON 格式例如{ code: 400, msg: 参数错误手机号格式不正确, data: null }前后端只需约定一套异常格式规则协作效率大幅提升。3. 隐藏敏感信息提升系统安全性如果异常直接抛给前端可能泄露关键信息例如数据库连接失败的异常会暴露jdbc:mysql://xxx:3306/xxx这类敏感地址例如空指针异常会暴露项目的类名、方法名、行号如NullPointerException at com.xxx.UserController.getUser(UserController.java:25)。全局异常处理器可以对用户友好返回 “服务器繁忙请稍后重试” 等通用提示对开发者友好将详细异常信息堆栈、敏感数据记录到日志中方便排查问题对攻击者不友好避免泄露系统架构、数据库信息等敏感内容。对攻击者不友好以下说明1. 避免泄露数据库相关敏感信息没有全局异常处理器时若数据库连接失败、SQL 执行出错异常会直接抛给前端例如NullPointerException: 无法连接数据库 jdbc:mysql://192.168.1.100:3306/test_db?useSSLfalse用户名root密码123456攻击者可直接获取数据库地址192.168.1.100、端口3306、数据库名test_db数据库用户名root、甚至密码123456若代码中硬编码数据库类型MySQL进而针对性发起暴力破解、SQL 注入攻击有全局异常处理器后会拦截该异常前端仅返回{code:500,msg:服务器繁忙请稍后重试,data:null}而详细的数据库连接异常、SQL 堆栈信息仅记录在后端日志供开发者排查攻击者无法获取任何数据库相关敏感信息。2. 避免泄露系统架构与代码结构系统运行中出现空指针、数组越界等异常时默认会返回完整的 Java 堆栈信息例如NullPointerException at com.xxx.controller.UserController.getUserById(UserController.java:38) at com.xxx.service.impl.UserServiceImpl.getById(UserServiceImpl.java:52) at org.springframework.web.method.support.InvocableHandlerMethod.invoke(InvocableHandlerMethod.java:205)攻击者可通过该信息摸清系统框架Spring Web项目包结构com.xxx.controller、com.xxx.service核心业务类/方法UserController、getUserById代码行号甚至可推测代码逻辑如第 38 行可能是获取用户信息时未判空全局异常处理器会屏蔽所有堆栈信息不暴露任何类名、方法名、行号让攻击者无法了解系统内部架构无法针对性寻找代码漏洞如未授权访问、逻辑漏洞。3. 避免泄露第三方组件 / 配置信息若项目集成了 Redis、RabbitMQ、OSS 等第三方组件当组件连接失败或调用出错时默认异常会泄露第三方组件类型Redis、RabbitMQ组件地址、端口如 redis://192.168.1.101:6379组件账号密码若配置不当例如未拦截的 Redis 连接异常RedisConnectionFailureException: 无法连接Redis服务器 192.168.1.101:6379密码abc123攻击者可获取 Redis 地址和密码尝试登录 Redis、篡改数据或植入恶意脚本而全局异常处理器会统一返回通用提示隐藏所有第三方组件的配置细节切断这类攻击路径。4. 区分异常类型精准处理不同场景全局处理器可以针对不同异常类型做差异化处理异常类型处理策略业务异常如 “用户不存在”返回 400 码 具体业务提示对用户友好参数校验异常Valid返回 400 码 校验失败的字段信息系统异常如空指针返回 500 码 通用提示 记录详细日志权限异常如未登录返回 401 码 “请先登录”这种精细化处理能让前端精准判断异常原因例如400 错误提示用户修改参数401 错误跳转到登录页500 错误提示用户稍后重试同时后端告警。5. 简化异常抛出逻辑聚焦业务逻辑开发者无需再关心 “异常怎么返回”只需专注 “什么时候抛异常”GetMapping(/user/{id}) public ResultVO getUser(PathVariable Long id) { User user userService.getById(id); if (user null) { // 直接抛自定义异常全局处理器会自动处理 throw new BusinessException(400, 用户不存在); } return ResultVO.success(user); }代码逻辑更清晰符合 “单一职责” 原则业务逻辑和异常处理分离。总结优秀的 Spring Boot 项目引入全局异常处理器的核心价值在于提效统一异常处理逻辑减少冗余代码降低维护成本规范统一返回格式提升前后端协作效率安全隐藏敏感信息同时保留详细日志便于排查问题友好区分异常类型对用户返回友好提示对开发者返回精准日志。全局异常处理器是 Spring Boot 项目 “优雅处理异常” 的最佳实践也是从 “能用” 到 “好用、安全、可维护” 的关键一步。附完整实现代码1. 第一步定义错误码枚举核心扩展点import lombok.Getter; /** * 全局错误码枚举 * 规范 * 1. 200成功 * 2. 4xx客户端错误参数、权限、业务规则 * 3. 5xx服务端错误系统、数据库、第三方依赖 */ Getter public enum ErrorCodeEnum { // 通用错误 SUCCESS(200, 操作成功), SYSTEM_ERROR(500, 服务器繁忙请稍后重试), PARAM_ERROR(400, 参数格式错误), // 业务错误 USER_NOT_EXIST(40001, 用户不存在), ORDER_NOT_FOUND(40002, 订单不存在), TOKEN_EXPIRED(40101, 登录已过期请重新登录), // 参数校验错误 VALID_FAILED(40000, 参数校验失败); private final int code; private final String msg; ErrorCodeEnum(int code, String msg) { this.code code; this.msg msg; } }2. 第二步定义统一返回结果import lombok.Data; /** * 全局统一返回结构 * 所有接口正常/异常均返回此格式 */ Data public class ResultT { /** 响应码对应ErrorCodeEnum */ private int code; /** 响应提示信息 */ private String message; /** 响应数据 */ private T data; // 成功响应 public static T ResultT success(T data) { ResultT result new Result(); result.setCode(ErrorCodeEnum.SUCCESS.getCode()); result.setMessage(ErrorCodeEnum.SUCCESS.getMsg()); result.setData(data); return result; } // 失败响应自定义提示 public static T ResultT fail(int code, String message) { ResultT result new Result(); result.setCode(code); result.setMessage(message); result.setData(null); return result; } // 失败响应基于错误码枚举 public static T ResultT fail(ErrorCodeEnum errorCode) { return fail(errorCode.getCode(), errorCode.getMsg()); } }3. 第三步定义自定义异常分层设计/** * 基础异常类所有自定义异常的父类 */ public class BaseException extends RuntimeException { private final int code; public BaseException(int code, String message) { super(message); this.code code; } public BaseException(ErrorCodeEnum errorCode) { super(errorCode.getMsg()); this.code errorCode.getCode(); } public int getCode() { return code; } } /** * 业务异常用户操作、业务规则触发 */ public class BusinessException extends BaseException { public BusinessException(int code, String message) { super(code, message); } public BusinessException(ErrorCodeEnum errorCode) { super(errorCode); } } /** * 系统异常数据库、第三方依赖、代码逻辑错误 */ public class SystemException extends BaseException { public SystemException(int code, String message) { super(code, message); } public SystemException(ErrorCodeEnum errorCode) { super(errorCode); } }4. 第四步全局异常处理器写法核心import lombok.extern.slf4j.Slf4j; import org.springframework.validation.BindingResult; import org.springframework.validation.FieldError; import org.springframework.web.bind.MethodArgumentNotValidException; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice; import org.springframework.web.servlet.NoHandlerFoundException; /** * 全局异常处理器 * 作用范围所有RestController注解的控制器 * 核心安全脱敏 分层处理 统一格式 */ Slf4j RestControllerAdvice(basePackages com.xxx.project.controller) // 指定生效包缩小范围 public class GlobalExceptionHandler { // 业务异常处理 ExceptionHandler(BusinessException.class) public Result? handleBusinessException(BusinessException e) { // 业务异常只打warn日志不打印堆栈减少日志量 log.warn(业务异常{}, e.getMessage()); return Result.fail(e.getCode(), e.getMessage()); } // 参数校验异常处理 ExceptionHandler(MethodArgumentNotValidException.class) public Result? handleValidException(MethodArgumentNotValidException e) { BindingResult bindingResult e.getBindingResult(); // 拼接所有参数错误信息友好提示 StringBuilder msg new StringBuilder(); for (FieldError fieldError : bindingResult.getFieldErrors()) { msg.append(fieldError.getField()).append().append(fieldError.getDefaultMessage()).append(); } String errorMsg msg.length() 0 ? msg.substring(0, msg.length() - 1) : ErrorCodeEnum.VALID_FAILED.getMsg(); log.warn(参数校验异常{}, errorMsg); return Result.fail(ErrorCodeEnum.VALID_FAILED.getCode(), errorMsg); } // 404异常处理 ExceptionHandler(NoHandlerFoundException.class) public Result? handle404Exception(NoHandlerFoundException e) { log.warn(404异常请求路径不存在 - {}, e.getRequestURL()); return Result.fail(404, 请求路径不存在); } // 系统异常处理兜底 ExceptionHandler({SystemException.class, Exception.class}) public Result? handleSystemException(Exception e) { // 系统异常打error日志打印完整堆栈便于排查 log.error(系统异常, e); // 前端只返回通用提示不泄露任何敏感信息 return Result.fail(ErrorCodeEnum.SYSTEM_ERROR); } }5. 第五步配置补充可选增强安全性在application.yml中添加配置关闭 Spring 默认错误提示确保全局处理器完全生效spring: mvc: throw-exception-if-no-handler-found: true # 触发404异常交给全局处理器处理 web: resources: add-mappings: false # 关闭静态资源映射的404默认处理 server: error: include-stacktrace: never # 禁止返回堆栈信息 include-message: never # 禁止返回默认错误信息使用示例业务代码中import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RestController; import javax.validation.constraints.NotBlank; RestController public class UserController { GetMapping(/user/{id}) public Result? getUser(NotBlank(message 用户ID不能为空) PathVariable String id) { // 业务逻辑校验触发业务异常 if (0.equals(id)) { throw new BusinessException(ErrorCodeEnum.USER_NOT_EXIST); } // 模拟系统异常如数据库查询失败 if (999.equals(id)) { throw new SystemException(ErrorCodeEnum.SYSTEM_ERROR); } return Result.success(用户信息 id); } }写法核心要点1. 安全层面系统异常前端只返回通用提示详细堆栈仅记录在后端日志限制全局处理器生效范围basePackages避免影响非业务接口关闭 Spring 默认错误信息暴露server.error配置。2. 可维护层面用枚举管理错误码新增错误码只需加枚举项无需改处理器异常分层设计业务 / 系统 / 参数处理逻辑清晰扩展方便日志分级打印warn/error减少无效日志便于问题定位。3. 易用层面参数校验异常返回具体字段错误信息用户 / 前端能精准修正统一返回结构前后端无需适配多格式自定义异常支持直接传枚举简化业务代码中异常抛出。