第2章 错误状态分类体系

在跨模块Result封装中，错误状态分类是基础。通过将错误划分为业务错误、系统错误、外部依赖错误和未知错误四类，可以实现精准的异常定位和优雅的降级处理。本章围绕模块边界、组件职责、数据流/控制流、选型权衡、风险点、落地步骤、验收标准，详细解析每个分类的架构设计要点。

错误类型	模块边界	组件职责	数据流/控制流	选型权衡	风险点
业务错误	业务逻辑层	校验规则、错误码映射	业务层校验 → Result封装 → 返回调用方；支持降级	错误码粒度 vs 维护成本	敏感信息泄漏
系统错误	基础设施层	资源监控、异常上报	系统异常采集 → 熔断/重试 → 控制面告警	检测粒度 vs 开销	资源耗尽导致上报失败
外部依赖错误	网关/适配器层	调用封装、错误转换	第三方超时 → 重试退避 → 降级结果	重试次数 vs 系统吞吐	级联雪崩
未知错误	全局错误处理中间件	兜底捕获、日志记录	未匹配异常 → 模糊提示 → 详细日志	信息隐藏 vs 可调试性	错误分类遗漏导致兜底泛滥

2.1 业务错误

业务错误指由应用层逻辑校验失败导致的异常状态，例如参数验证不通过、库存不足、用户不存在等。该分类发生在业务逻辑层边界。

模块边界与组件职责

• 模块边界：业务逻辑层内部，不跨模块传播原始校验信息。
• 组件职责：定义业务错误码映射表，将校验失败直接转为预设错误状态。

数据流与控制流

• 数据流：业务层校验 → Result封装 → 返回调用方。
• 控制流：捕获校验异常后，可选降级处理（如返回默认值）或中断链路。

选型权衡与风险点

• 选型权衡：错误码粒度越细，后续处理越精确，但维护成本越高。选择枚举或错误码类时需权衡模块间耦合度。
• 风险点：错误描述可能携带敏感业务信息（如用户手机号），需在封装前做脱敏处理。

落地步骤与验收标准

1. 步骤一：定义业务错误码表（如枚举类或错误码常量）。
2. 步骤二：在业务逻辑关键路径中捕获校验失败并封装为Result。
3. 步骤三：编写单元测试验证错误状态转换。
4. 验收标准：所有已知业务异常均返回统一错误结构，错误码与接口文档一致。

2.2 系统错误

系统错误指运行时环境或基础设施错误，如内存溢出、磁盘IO错误、配置加载失败。该分类发生在基础设施层边界。

模块边界与组件职责

• 模块边界：基础设施层内部，通常由系统级中间件或监控组件捕获。
• 组件职责：资源监控、异常上报、触发熔断或降级策略。

数据流与控制流

• 数据流：系统异常采集 → 控制面告警 → 集群调度决策。
• 控制流：当检测到系统错误时，执行熔断或自动重试（如数据库连接池重置）。

选型权衡与风险点

• 选型权衡：错误检测粒度（如CPU使用率阈值）越细，越能提前预警，但增加系统开销。
• 风险点：资源耗尽（如磁盘满）可能导致错误上报组件自身失败，造成静默失效。

落地步骤与验收标准

1. 步骤一：配置系统错误阈值（如内存占80%触发报警）。
2. 步骤二：实现系统错误监听与上报模块。
3. 步骤三：通过压力测试验证系统错误时的熔断逻辑。
4. 验收标准：系统资源使用超过阈值时，正确返回系统错误结果，并记录详细日志。

2.3 外部依赖错误

外部依赖错误指调用的外部服务或组件返回的异常，如第三方API超时、数据库连接失败、消息队列不可用。该分类发生在网关/适配器层边界。

模块边界与组件职责

• 模块边界：适配器层，负责封装第三方调用并转换错误格式。
• 组件职责：调用超时检测、重试退避、错误标准化。

数据流与控制流

• 数据流：第三方异常 → 适配层转换 → 统一错误结构 → 返回调用方。
• 控制流：支持指数退避重试（如首次重试1s，二次2s…），超过最大次数后降级为默认值。

选型权衡与风险点

• 选型权衡：重试次数多可提高成功率，但增加上游等待时间；需根据外部服务SLA设定。
• 风险点：单点外部依赖抖动可能导致级联雪崩，需配合熔断器使用。

落地步骤与验收标准

1. 步骤一：配置外部依赖超时时间和重试策略。
2. 步骤二：在适配层实现错误映射逻辑。
3. 步骤三：通过Mock测试模拟外部服务故障。
4. 验收标准：外部服务超时或返回异常时，转换为标准外部依赖错误，且不影响主链路。

2.4 未知错误

未知错误指无法归入前述三类的所有异常，作为兜底分类。例如第三方库抛出未预料的异常、未注册的错误码。该分类发生在全局错误处理中间件边界。

模块边界与组件职责

• 模块边界：全局中间件，在所有模块错误处理之后执行。
• 组件职责：兜底捕获、详细日志记录、返回统一模糊提示。

数据流与控制流

• 数据流：未匹配异常 → 中间件捕获 → 模糊错误信息 → 返回调用方。
• 控制流：不进行重试或降级，仅记录日志并上报监控系统。

选型权衡与风险点

• 选型权衡：信息隐藏程度 vs 可调试性；过多暴露内部细节易被攻击，过少则难以定位问题。
• 风险点：错误分类遗漏可能导致未知错误泛滥，掩盖系统真实健康状况。

落地步骤与验收标准

1. 步骤一：实现全局异常处理器(如@ControllerAdvice)。
2. 步骤二：配置日志级别和上下文字段。
3. 步骤三：通过混沌工程注入随机异常。
4. 验收标准：所有未匹配异常都被未知错误捕获，错误描述不泄漏任何内部细节。