三步搭建可落地的全局异常处理体系:统一Result返回结构,定义分层业务异常BusinessException,通过@RestControllerAdvice实现分级异常捕获与日志记录。

直接从开发痛点切入,边写边跑,三步就能搭起一套可落地的全局异常处理体系。
先统一返回结构,前端才不懵
所有接口必须返回一致格式,比如{code: 200, msg: "成功", data: {...}}。定义一个Result类,带success()和error(code, msg)两个静态工厂方法。注意:code别全用200或500,业务错误码要分层——400系给参数问题,401/403给权限,404给资源不存在,500留给系统崩溃。
再定义业务异常,让错误语义清晰
别直接抛RuntimeException。建一个BusinessException,构造时传入code和message,比如new BusinessException(402, "余额不足")。这样在Service里该抛就抛,不用关心怎么响应,交给全局处理器收口。
最后写全局处理器,用@RestControllerAdvice兜底
建一个GlobalExceptionHandler类,加@RestControllerAdvice注解。里面按优先级写几个@ExceptionHandler方法:
- 处理
BusinessException:取它的code和msg,包装成Result.error(e.getCode(), e.getMessage()) - 处理
MethodArgumentNotValidException:提取校验失败字段和提示,组装成“用户名不能为空”这类用户能看懂的话 - 兜底处理
Exception:生产环境只返回Result.error(500, "系统繁忙"),绝不能暴露堆栈
顺手加点实用增强
上线前建议补两处:
- 日志记录:每个
@ExceptionHandler方法开头加log.error("捕获异常", e),方便排查 - 敏感信息过滤:如果异常消息含数据库表名、路径、IP等,用工具类提前清洗再返回











