# 统一错误处理原则

## 1. 已知结果处理规则

属于 API 契约允许出现、调用方能够明确处理的情况，使用返回码表达，例如 `Xxx_Result`、`Xxx_Status`、`Xxx_Error`。

返回码不等于错误码，`timeout`、`cancelled`、`not_ready`、`no_change` 等都可以是正常结果。

判断依据只有一个：

**该结果是否可预料，并且调用方是否具有明确的处理方式。**

不按“内部/外部”区分。

## 2. 未知失败处理规则

不属于正常结果空间，或者当前调用路径没有可靠恢复方式的情况，统一视为 **Unknown Failure**。

Unknown Failure 不得转换成 `unknown_error`、`internal_error` 等普通返回码。

中间层没有恢复能力时不得层层处理，不增加无意义的 `catch`、包装或 catch/rethrow。

Unknown Failure 应直接退出当前执行路径，由上层真正具有故障隔离能力的 request、task、worker、进程或服务边界处理。

异步跨线程时可以使用 `std::exception_ptr`、`promise::set_exception()`、`future::get()` 搬运失败；这只是 transport，不属于错误处理。

## 3. Unknown Failure Policy

Unknown Failure 支持两种处置策略：

```text
fast_fail
    -> 在实际故障位置尽快终止
    -> 用于开发、调试和测试
    -> 优先保留故障现场

exception
    -> 使用异常自然跨层传播
    -> 中间层不处理
    -> 到达上层故障隔离边界
    -> 优先利用 task/thread/process 等隔离能力
```

`fast_fail` 只改变 Unknown Failure 的处置方式， **不得改变 Known Result / Unknown Failure 的分类。**

## 4. 第三方库处理规则

第三方库自身使用返回码还是异常，不决定本系统的处理方式。

接入第三方库后必须重新按照本系统规则分类：

```text
第三方返回结果
    -> 本系统可预料、可处理
       -> 转换为本系统返回码

    -> 本系统没有可靠恢复方式
       -> 转换为 Unknown Failure
       -> 交给当前 Unknown Failure Policy
```

不得机械透传第三方错误模型，也不得因为第三方返回了错误码，就强制在本系统中继续使用错误码。

## 5. 其他要求

`noexcept` 只用于明确保证异常不会逃逸的函数。

不得为了错误处理增加重复检查、兼容层、无意义 `try/catch`，也不得改变原函数的既有语义。

**最终原则：已知结果使用返回码；未知失败使用可配置的 Unknown Failure Policy；第三方错误进入系统后重新按同一规则分类。**