常惠雯在Spring Boot项目中如何优雅处理全局异常？

Question

常惠雯在Spring Boot项目中遇到一个典型问题：当Controller中抛出自定义业务异常（如`UserNotFoundException`）或系统异常（如`NullPointerException`）时，前端收到的是HTTP 500页面或默认JSON错误体，缺乏统一状态码、错误码、可读消息及日志追踪能力，导致前后端协作低效、线上问题排查困难。她尝试用`@ExceptionHandler`逐个方法处理，但代码重复、维护成本高；也试过`@ControllerAdvice`，却未区分异常类型优先级，导致400/500响应混乱，且未集成统一返回结构（如`Result`）与链路ID透传。此外，全局异常处理器未能兼容RESTful API与Web页面请求（如HTML跳转），也缺少对`@Valid`校验异常的优雅捕获。如何设计一套高内聚、可扩展、符合团队规范的全局异常处理机制，兼顾可读性、可观测性与前后端契约一致性？

Answer 1

```html

一、问题本质剖析：为什么“简单加个@ControllerAdvice”依然失败？

常惠雯的困境并非技术不可达，而是缺乏分层治理思维。Spring Boot默认异常处理链（DispatcherServlet → HandlerExceptionResolver → DefaultErrorAttributes）存在天然优先级断层：校验异常（MethodArgumentNotValidException）、参数解析异常（HttpMessageNotReadableException）、业务异常（UserNotFoundException）、运行时异常（NullPointerException）和系统级错误（如OOM）混杂在同一处理通道中，未按语义分级拦截。更关键的是，@ControllerAdvice默认全局生效，但未绑定@Order与@ExceptionHandler的显式类型匹配策略，导致子类异常（如RuntimeException）意外覆盖父类（如IllegalArgumentException）处理逻辑。

二、设计原则锚定：高内聚、可扩展、契约一致性的三大支柱

• 语义分层：将异常划分为「客户端错误（4xx）」「服务端错误（5xx）」「业务域错误（自定义码）」三级；
• 契约先行：统一返回结构Result<T>必须包含code（业务码）、status（HTTP状态）、message（前端友好文案）、traceId（全链路ID）、timestamp（ISO8601）；
• 可观测性嵌入：日志需自动注入MDC.put("traceId", traceId)，并支持ELK/Splunk结构化采集；
• 场景隔离：REST API返回JSON，传统Web请求（Accept: text/html）重定向至/error页面或渲染Thymeleaf模板。

三、核心架构实现：五层拦截+双通道响应

采用如下分层策略：

层级	拦截异常类型	HTTP状态码	响应格式	关键动作
① 参数校验层	MethodArgumentNotValidException, BindException	400	JSON	提取@NotBlank/@Min等注解的message，聚合为fieldErrors
② 业务语义层	BusinessException及其子类（如UserNotFoundException）	由异常自身getHttpStatus()决定（可为404/409/422）	JSON + HTML双模	调用ErrorCode.resolve(code)查国际化文案
③ 系统防护层	NullPointerException, IllegalArgumentException等非受检异常	500	JSON（生产环境）/详细HTML（开发环境）	生成唯一traceId，记录堆栈到ERROR日志

四、关键代码骨架：可即插即用的生产级模板

// 统一返回体
public class Result<T> {
  private int code;
  private int status;
  private String message;
  private String traceId;
  private long timestamp;
  private T data;
  // getter/setter...
}

// 全局异常处理器（带Order优先级）
@Order(Ordered.HIGHEST_PRECEDENCE)
@ControllerAdvice
@ResponseBody
public class GlobalExceptionHandler {

  @ExceptionHandler(MethodArgumentNotValidException.class)
  public Result<Void> handleValidation(MethodArgumentNotValidException e) {
    String msg = e.getBindingResult().getFieldErrors().stream()
        .map(FieldError::getDefaultMessage).collect(Collectors.joining("; "));
    return Result.fail(400, "VALIDATION_FAILED", msg);
  }

  @ExceptionHandler(BusinessException.class)
  public Result<Void> handleBusiness(BusinessException e) {
    return Result.fail(e.getErrorCode(), e.getMessage())
        .withTraceId(MDC.get("traceId"))
        .withTimestamp(System.currentTimeMillis());
  }

  @ExceptionHandler(Exception.class)
  public Result<Void> handleUnexpected(Exception e) {
    String traceId = IdUtil.fastSimpleUUID();
    MDC.put("traceId", traceId);
    log.error("Unhandled exception [{}]", traceId, e); // 结构化日志
    return Result.fail(500, "SYSTEM_ERROR", "服务暂不可用").withTraceId(traceId);
  }
}

五、增强能力集成：链路透传与多端适配

通过OncePerRequestFilter注入链路ID，并根据Accept头动态切换响应策略：

graph TD
  A[HTTP Request] --> B{Accept: text/html?}
  B -->|Yes| C[Forward to /error.html]
  B -->|No| D[Invoke GlobalExceptionHandler]
  D --> E{Is BusinessException?}
  E -->|Yes| F[Return Result with 4xx]
  E -->|No| G[Return Result with 500]

六、工程化保障：团队规范落地清单

1. 定义ErrorCode枚举，强制所有业务异常构造时传入枚举实例；
2. 在CI阶段添加Checkstyle规则：禁止catch (Exception e)裸捕获；
3. Swagger文档自动聚合@ApiResponses，同步展示各接口可能返回的code；
4. Logback配置%X{traceId}占位符，确保日志与链路ID强绑定；
5. 提供Postman Collection示例，预置traceId变量用于问题复现；
6. 建立error_code.csv翻译表，支持i18n多语言消息注入；
7. 对@Valid校验字段增加@Schema(description=...)提升API文档可读性。

七、演进路线图：从可用到卓越

阶段目标包括：
✓ V1.0：支持JSON统一响应+基础链路ID
✓ V2.0：集成Sentry错误监控+自动告警
✓ V3.0：基于OpenTelemetry实现异常指标埋点（如exception_count{type="UserNotFoundException"}）
✓ V4.0：AI辅助诊断——根据堆栈+traceId自动推荐修复方案（对接内部知识库）

```