StandardException 是团队约定的统一异常基类,承载错误码、消息和上下文数据;错误码须通过枚举集中管理,命名需模块化分层(如 USER_NOT_FOUND),异常构造强制绑定 ErrorCode,全局拦截器仅捕获其子类以实现结构化异常处理。

企业级项目中,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










