17370845950

统一异常处理的核心目标是让异常在合适位置被捕获、分类、转换并返回友好响应，需区分业务、系统、参数校验异常，通过@ControllerAdvice+@ExceptionHandler实现分层处理，定义三级异常体系与标准Result返回体，避免静默吞异常、错误覆盖及异步失效等问题。

统一异常处理的核心目标

不是把所有异常都吞掉，而是让异常在合适的位置被捕获、分类、转换，并返回对前端友好的结构化响应。关键在于区分业务异常、系统异常和参数校验异常，各自走不同的处理路径，避免堆栈信息泄露，同时保留足够的排查线索。

@ControllerAdvice + @ExceptionHandler 统一拦截

这是 Spring Boot 中最常用且推荐的方式。通过自定义一个全局异常处理器类，用 @ControllerAdvice 标记，再为不同异常类型编写带 @ExceptionHandler 的方法：

• 捕获 BusinessException（自定义业务异常）→ 返回 HTTP 200 + 业务错误码 + 提示消息
• 捕获 MethodArgumentNotValidException → 提取 @Valid 校验失败的字段和提示，组装成统一错误格式
• 捕获 Exception（兜底）→ 记录完整堆栈日志，返回通用系统错误（如 code=50000），不暴露内部细节

定义分层异常与标准返回体

建议定义三级异常体系：ParamException（参数类）、BusinessException（业务规则类）、SystemException（运行时/IO/第三方调用类）。对应统一返回对象如 Result：

• code：整型错误码，按模块+类型划分（如 1001 表示用户模块参数错误）
• message：面向前端或用户的简明提示（非开发术语）
• data：成功时放业务数据，失败时可为空或放扩展字段（如 fieldErrors）
• timestamp：便于问题定位的时间戳

避免常见陷阱

统一异常处理容易踩坑，几个关键点要特别注意：

• 不要在 service 层 try-catch 后“静默吞掉”异常，除非你明确要转化为另一种异常并重抛
• @ExceptionHandler 方法参数不能只写 Exception，否则会覆盖更具体的异常处理器；优先按子类声明
• 全局异常处理器默认不处理静态资源、WebMvcConfigurer 配置异常、Filter 中抛出的异常，需额外配置或日志监控
• 异步方法（@Async）中抛出的异常不会被 @ControllerAdvice 拦截，需单独处理

补充：配合 AOP 做方法级异常增强

对于需要统一记录耗时、入参、异常场景的方法，可用 @Around 切面，在 catch 块中识别异常类型后主动触发事件或调用异常处理服务，实现比 @ExceptionHandler 更灵活的上下文控制（比如根据方法注解决定是否告警、是否重试）。