在现代Java Web开发中，异常处理是保证系统健壮性和提升用户体验的关键环节。本文将带你从痛点出发，手把手构建一套优雅、统一的全局异常处理方案。
一、 为什么需要全局异常处理？
在传统的开发模式中，我们经常在Controller层充斥着大量的try-catch代码块：
@PostMapping("/user")publicResult<User>createUser(@RequestBodyUserDTOuserDTO){try{Useruser=userService.createUser(userDTO);returnResult.success(user);}catch(BizExceptione){returnResult.fail(e.getCode(),e.getMessage());}catch(Exceptione){log.error("创建用户失败",e);returnResult.fail(500,"系统内部错误");}}这种方式不仅让业务逻辑代码臃肿，而且如果每个接口都这样处理，一旦需要调整返回格式，工作量将是巨大的。SpringBoot 提供了强大的全局异常处理机制，让我们能够将异常处理与业务逻辑彻底解耦。
二、 核心武器：@ControllerAdvice + @ExceptionHandler
SpringBoot 实现全局异常处理主要依赖两个核心注解：
@ControllerAdvice：用于定义全局控制器的增强类，通常配合@ExceptionHandler使用。@ExceptionHandler：用于指定当发生特定异常时，应该由哪个方法来处理。
三、 实战：构建统一异常处理体系
1. 定义统一响应体 (Result)
在开始处理异常之前，我们需要约定前后端交互的统一数据结构。
@Data@AllArgsConstructor@NoArgsConstructorpublicclassResult<T>{/** 状态码 */privateIntegercode;/** 提示信息 */privateStringmessage;/** 数据载体 */privateTdata;publicstatic<T>Result<T>success(Tdata){returnnewResult<>(200,"success",data);}publicstatic<T>Result<T>success(){returnnewResult<>(200,"success",null);}publicstatic<T>Result<T>fail(Integercode,Stringmessage){returnnewResult<>(code,message,null);}}2. 构建业务异常体系
我们需要定义一个基础的业务异常类，用于承载错误码和错误信息。
@GetterpublicclassBizExceptionextendsRuntimeException{privatefinalIntegercode;publicBizException(Integercode,Stringmessage){super(message);this.code=code;}// 支持传入枚举类型的错误码publicBizException(ErrorCodeerrorCode){super(errorCode.getMessage());this.code=errorCode.getCode();}}// 错误码枚举示例@Getter@AllArgsConstructorpublicenumErrorCode{USER_NOT_FOUND(1001,"用户不存在"),USER_ALREADY_EXISTS(1002,"用户已存在"),PARAM_ERROR(1003,"参数错误");privatefinalIntegercode;privatefinalStringmessage;}3. 编写全局异常处理器 (GlobalExceptionHandler)
这是核心部分，我们将不同类型的异常在这里进行统一拦截和处理。
@Slf4j@RestControllerAdvicepublicclassGlobalExceptionHandler{/** * 处理自定义业务异常 */@ExceptionHandler(BizException.class)publicResult<?>handleBizException(BizExceptione){log.warn("业务异常: code={}, msg={}",e.getCode(),e.getMessage());returnResult.fail(e.getCode(),e.getMessage());}/** * 处理参数校验异常 (Hibernate Validator) */@ExceptionHandler(MethodArgumentNotValidException.class)publicResult<?>handleValidationException(MethodArgumentNotValidExceptione){Stringmessage=e.getBindingResult().getFieldErrors().stream().map(DefaultMessageSourceResolvable::getDefaultMessage).collect(Collectors.joining(", "));log.warn("参数校验异常: {}",message);returnResult.fail(ErrorCode.PARAM_ERROR.getCode(),message);}/** * 处理非法参数异常 */@ExceptionHandler(IllegalArgumentException.class)publicResult<?>handleIllegalArgumentException(IllegalArgumentExceptione){log.warn("非法参数异常: {}",e.getMessage());returnResult.fail(400,e.getMessage());}/** * 兜底处理：处理所有未被捕获的异常 */@ExceptionHandler(Exception.class)publicResult<?>handleException(Exceptione){log.error("系统未知异常: ",e);returnResult.fail(500,"系统繁忙，请稍后再试");}}四、 最佳实践与进阶技巧
- 异常分类处理：尽量细化异常类型，不要把所有异常都扔给
Exception.class处理，这样会导致无法针对不同错误返回精确的提示。 - 日志记录策略：
- 业务异常：通常使用
warn级别，因为这是用户操作不当或业务规则限制导致的。 - 系统异常：必须使用
error级别，并打印完整的堆栈信息（log.error("...", e)），以便快速定位 Bug。
- 业务异常：通常使用
- 安全性考虑：在捕获
Exception.class时，绝不要将异常堆栈信息直接返回给前端，防止泄露数据库结构或内部路径等敏感信息。
五、 总结
通过引入全局异常处理机制，我们的 Controller 代码变得异常清爽：
@PostMapping("/user")publicResult<User>createUser(@Valid@RequestBodyUserDTOuserDTO){// 业务逻辑，无需 try-catchUseruser=userService.createUser(userDTO);returnResult.success(user);}这样不仅提升了代码的可读性，也极大地提高了系统的可维护性。掌握这套方案，你的 SpringBoot 项目将迈出规范化的重要一步！
🎁 福利时间
如果你正在备战面试或者想要学习其他知识，给大家推荐一个宝藏知识库，作者整理了一些列 Java 程序员需要掌握的核心知识，有需要的自取不谢。
知识库地址：https://farerboy.com/
