在Java里如何构建业务异常码体系_Java错误码规范设计说明

Java业务异常码体系需类型安全、分层分类、统一管理：定义ErrorCode接口与BaseErrorCode基类；按领域分包用枚举实现，如ORDER_NOT_FOUND(10001,"order.not.found",NOT_FOUND)；message绑定i18n键值；抛BizException并由全局处理器格式化响应。

Java中构建业务异常码体系，核心是让错误码具备可读性、可维护性、可扩展性和系统级一致性。不靠字符串拼接或零散常量，而应通过类型安全、分层分类、统一管理的方式设计。

定义统一的错误码接口与基类

所有业务错误码应实现一个公共接口（如 ErrorCode），包含 code()、message()、httpStatus() 等标准方法。再提供抽象基类（如 BaseErrorCode）封装通用逻辑，避免重复代码。

• 接口强制约束结构，便于框架统一处理（如全局异常处理器自动提取信息）
• 基类支持懒加载 message（结合 i18n 资源文件）、默认 HTTP 状态码（如业务异常常用 400 或 422）
• 禁止直接使用 int/long 字面量定义码值，全部走枚举或实现类

按领域分包 + 枚举化管理错误码

错误码按业务域垂直拆分，例如：order.ErrorCode、user.ErrorCode、payment.ErrorCode。每个域内用 public enum 实现具体码项，每个枚举项是一个完整错误定义。

• 枚举名体现语义，如 ORDER_NOT_FOUND、INSUFFICIENT_BALANCE
• 构造参数包括：数字码（建议 5 位以上，前两位代表域，如 10 开头为订单）、默认提示、HTTP 状态
• 示例：ORDER_NOT_FOUND(10001, "订单不存在", HttpStatus.NOT_FOUND)
• 避免跨域复用枚举，防止耦合；共用场景提取为 common.ErrorCode（如 SYSTEM_ERROR）

支持多语言与运行时动态提示

错误 message 不硬编码在枚举里，而是绑定到 i18n prop

erties 文件（如 error_zh_CN.properties），通过 key 查找。枚举中只存 message key（如 "order.not.found"）。

• Spring 环境下可注入 MessageSource 实现运行时解析
• 对外返回时自动根据请求头 Accept-Language 渲染对应语言提示
• 开发阶段可通过 IDE 插件或编译检查确保所有 key 在资源文件中存在

集成到异常抛出与全局处理链路

定义业务异常类（如 BizException），构造时传入 ErrorCode 枚举实例。全局异常处理器（@ControllerAdvice）捕获后，统一格式化为标准响应体（含 code、message、requestId 等）。

• 禁止在 service 层 throw new RuntimeException("xxx")，必须用 BizException 包装 ErrorCode
• 日志记录时自动打印 error code + requestId，方便问题追踪
• 前端可基于 code 做精细化交互（如 code=10001 时跳转订单列表页）

不复杂但容易忽略的是错误码生命周期管理——上线后不能随意删除或重定义已有 code 含义，需配套文档和变更评审机制。建议搭配内部错误码平台或 Confluence 页面，记录每个码的用途、引入版本、调用方示例和修复状态。