统一错误码与异常映射需建立“代码逻辑→异常对象→错误码→响应体”完整链路：分层定义错误码（如1001用户不存在），自定义异常绑定枚举并支持动态参数，全局@ExceptionHandler统一响应，OpenAPI文档同步错误码契约。
接口设计中统一规范错误码与异常映射，核心是让错误可识别、可追溯、可协作。不是简单地“抛个异常再转个码”，而是建立从代码逻辑 → 异常对象 → 错误码 → 响应体的完整链路。
定义分层清晰的错误码体系
错误码不是随意编号，要体现模块、场景和严重程度。例如：
- 前两位代表业务域（如 10 用户、20 订单、30 支付）
- 后两位区分具体问题（如 1001 用户不存在、1002 用户已禁用）
- 避免使用 HTTP 状态码替代业务码（404 ≠ 用户不存在，因为权限不足也可能返回404，但语义完全不同）
用自定义异常承载错误码与上下文
每个业务异常类应绑定唯一错误码，并支持注入动态参数：
- 继承统一基类（如
BaseException），构造时传入ErrorCode枚举 - 异常消息可含占位符（如
"订单{orderNo}状态非法，当前为{status}"），由框架自动填充 - 禁止直接
throw new RuntimeException("xxx")—— 这类异常无法被精准识别和翻译
全局拦截并标准化响应格式
所有 Controller 层异常必须由 @RestControllerAdvice 统一捕获，禁止在接口方法内写 try-catch 包装返回值：
立即学习“Java免费学习笔记（深入）”；
- 对
BusinessException：提取其errorCode和填充后的消息，封装为Result.fail(code, message) - 对
SystemException或第三方异常：记录完整堆栈，返回通用系统错误码（如SYS-500），不暴露技术细节 - 对
Error（如OutOfMemoryError）：不做业务响应，交由容器或网关处理，防止系统进一步恶化
前后端约定与文档同步落地
规范真正生效，靠的是契约而非代码：
- 所有错误码写入 OpenAPI 文档的
responses中，标注触发条件和示例 - 前端按错误码做分支处理（如
USER-404跳登录页，ORDER-409提示刷新重试） - 日志中强制打印错误码（而不仅是 message），便于 ELK 或 Sentry 按码聚合分析失败率
