Java分布式系统异常体系以错误码为语义锚点，通过统一ErrorCode接口、强类型基类、业务域枚举实现类型安全；禁止字面量异常抛出，强制绑定BizException；配套编译检查、文档生成与配置中心保障落地。

Java 构建清晰的分布式系统异常体系，核心不是堆砌异常类，而是用错误码为语义锚点、基类为结构骨架、枚举为领域边界，把业务意图、HTTP 状态、多语言提示、上下文追踪全部绑定在一个可类型安全传递的对象上。

定义统一 ErrorCode 接口与强类型基类

所有错误码必须实现统一接口（如 ErrorCode），强制提供 code()、messageKey()、httpStatus() 方法。再通过抽象基类（如 BaseErrorCode）封装共性逻辑：

• message 不存实际文案，只存 i18n 键（如 "order.not.found"），运行时由 MessageSource 解析
• 支持懒加载 message，避免启动时加载全部资源文件
• HTTP 状态按语义预设：参数错误默认 400，未授权用 401，资源缺失用 404，业务拒绝用 403 或 422
• 禁止在代码中写 new BizException(10001, "订单不存在") 这类字面量调用

按业务域垂直拆分枚举，杜绝跨域混用

错误码包结构与微服务模块严格对齐，例如：

• com.company.order.error.OrderErrorCode
• com.company.user.error.UserErrorCode
• com.company.payment.error.PaymentErrorCode

每个枚举项命名体现完整语义，如 ORDER_NOT_FOUND(10001, "order.not.found", HttpStatus.NOT_FOUND)：

Java Maven Secondary Analysis

分析ZIP压缩包或GitLab仓库中的Java Maven项目，确定二次开发范围、类数量、模块分布及生产相关指标。

下载

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

• 码值建议 5 位以上，前两位代表域编号（如 10=订单、20=用户），便于快速识别来源
• 共用错误（如系统超时、熔断、限流）统一收口到 common.ErrorCode，不散落各模块
• 禁止跨域复用枚举项，防止模块耦合和语义漂移

绑定 BizException，全程强类型抛出与捕获

自定义 BizException，构造时必须传入 ErrorCode 枚举实例，禁止裸 throw 字符串或继承 RuntimeException 后随意抛出：

• Service 层抛出：throw new BizException(OrderErrorCode.ORDER_INVALID_STATUS);
• 支持动态占位：throw new BizException(UserErrorCode.USER_NOT_FOUND, "id={0}", userId);
• 全局异常处理器（@ControllerAdvice）捕获后，自动提取 code、解析多语言 message、注入 requestId，返回标准 JSON 响应体
• 日志框架自动记录 error.code 和 requestId，便于 ELK 快速聚合与链路追踪

配套支撑保障落地一致性

仅靠代码规范不够，需工程化手段兜底：

• 编译期检查：通过注解处理器或 IDE 插件，校验所有 messageKey 是否在 i18n 资源文件中存在
• 文档自动生成：基于枚举生成 Markdown 或 Swagger 错误码文档，与代码保持同步
• 配置中心集成：允许运营临时调整提示文案（如营销活动期间修改拒绝话术），无需发版
• 前端约定：前端根据 code 做精细化交互（如 code=10001 自动跳转订单列表页，code=20005 触发登录态刷新）