如何通过 StandardException 在 Java 中统一企业级应用错误响应变量模板设计？

本文共计626个文字，预计阅读时间需要3分钟。

StandardException并非依赖某个具体的错误数据结构，而是一个定义明确的错误类型，作为所有异常响应的统一载体：

• 创建 ErrorResponse 类：含 code（如 "USER_NOT_FOUND"）、message（国际化键或默认提示）、timestamp、path 等字段
• 配套定义枚举 ErrorCode：集中管理所有业务错误码，每个枚举项自带默认消息和 HTTP 状态码（如 USER_NOT_FOUND(404, "用户不存在")）
• 避免在异常构造时硬编码字符串，所有提示走枚举或消息源（MessageSource）

设计分层自定义异常类

按语义和处理方式划分异常类型，而非堆砌继承：

• BizException：所有业务异常的顶层父类，持有一个 ErrorCode 实例，不继承 RuntimeException 或 Exception 强制检查（推荐运行时异常）
• ValidationException：专用于参数校验失败，可携带 BindingResult 或字段级错误列表
• 不建议创建 “StandardException” 这种空泛命名的类——它无法表达任何业务意图，反而增加理解成本

用 @ControllerAdvice + @ExceptionHandler 统一拦截与渲染

在 Spring MVC/Boot 中，这才是真正实现“所有错误响应模板统一”的核心机制：

• 编写全局异常处理器类，用 @ControllerAdvice 注解
• 为每类异常写对应 @ExceptionHandler 方法，例如：
  @ExceptionHandler(BizException.class) → 提取其 ErrorCode → 构造 ErrorResponse → 返回 ResponseEntity.status(code.getHttpStatus()).body(response)
• 同时覆盖 MethodArgumentNotValidException、HttpRequestMethodNotSupportedException 等框架级异常，确保 400/405/500 等也走同一响应结构

补充：API 契约与文档对齐

标准化不止于代码，还要让前端和文档感知一致：

立即学习“Java免费学习笔记（深入）”；

• 使用 OpenAPI（Swagger）注解，在控制器方法上声明 @ApiResponse，明确各 HTTP 状态码对应的 ErrorResponse 结构
• 将 ErrorCode 枚举导出为 JSON 或 Markdown 文档，作为前后端联调依据
• 日志中记录异常时，自动打印 ErrorCode.code 和关键上下文（如用户ID、订单号），便于排查