如何统一企业级项目中的异常变量输出，采用StandardException与错误码（Error Code）规范？

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

在商业级项目中，StandardException不是一个JDK或Spring内置类，而是团队约定的统一异常基类。它承载错误码（ErrorCode）、可读消息、上下文数据等关键信息，使异常从抛出即消失转变为可识别、可追踪、可响应的结构化符号。

错误码必须集中管理，不能硬编码

所有业务异常必须通过枚举类（如 ErrorCode）定义错误码，禁止在 throw 语句里直接拼字符串或数字。例如：

• USER_NOT_FOUND("USER_001", "用户不存在")
• ORDER_EXPIRED("ORDER_005", "订单已过期，请重新下单")

枚举字段应包含：code 字符串（便于前端 switch）、中文提示（开发/测试用）、英文描述（国际化基础）、HTTP 状态建议值（如 404 对应 USER_NOT_FOUND）。

StandardException 基类要强制绑定 ErrorCode

自定义异常必须继承一个统一基类（如 StandardException），且构造函数只接受 ErrorCode 枚举或其 code 字符串，不允许多余重载。示例结构：

• 构造时自动填充 code、message、timestamp
• 支持传入额外参数（如 userId、orderId），用于填充 message 占位符（"用户 {0} 余额不足"）
• 提供 getDetails() 方法返回脱敏后的上下文 Map，供日志和监控使用

全局拦截器只认 StandardException 及其子类

Spring 的 @RestControllerAdvice 应仅捕获 StandardException，其他未预期异常（如 NullPointerException）走兜底逻辑，返回通用 500 错误并记录 ERROR 日志。这样做的好处是：

• 前端永远收到标准 Result<?> 结构，含 code（业务码）、errorCode（字符串标识）、msg（用户提示）、traceId（链路追踪）
• 运维可通过 errorCode 快速筛选告警，无需解析日志文本
• 测试人员根据 errorCode 编写断言，接口契约更稳定

错误码体系需分层可扩展

错误码命名不是编号游戏，而是一套语义路由系统：

• 前缀按模块划分：USER_、PAY_、NOTICE_，避免全局冲突
• 后缀按场景细化：USER_LOCKED、USER_INVALID_TOKEN，拒绝模糊命名如 ERROR_001
• 预留号段：如 USER_9000+ 专用于系统级异常（DB 连接失败、Redis 超时），与业务异常隔离
• 配套文档：每个 ErrorCode 枚举项附带「影响范围」「建议操作」「是否需人工介入」说明，嵌入到 Swagger 或内部 Wiki