# 统一错误处理原则

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

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

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

判断依据只有一个：

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

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

### 返回码定义规则

**每个存在返回码的函数必须拥有自己独立的返回码枚举，不得在一个类或模块中定义大而通用的公共返回码枚举供多个函数混用。**

例如：

```cpp
enum class Request_Frame_Result {
    not_ready,
    cancelled
};

std::expected<Frame, Request_Frame_Result> request_frame();
```

```cpp
enum class Resize_Result {
    no_change,
    unsupported
};

Resize_Result resize(Size size);
```

禁止：

```cpp
enum class Scene_Result {
    not_ready,
    cancelled,
    no_change,
    unsupported,
    no_pending_frame,
    ...
};
```

然后由多个函数共同返回 `Scene_Result`。

规则如下：

* 有正常返回值，同时存在返回码：

  ```cpp
  std::expected<T, Xxx_Result>
  ```
* 没有额外正常返回值，返回码本身即可完整表达结果：

  ```cpp
  Xxx_Result
  ```
* 没有已知返回码：

  ```cpp
  T
  void
  ```
* 返回码类型必须对应具体函数的契约，函数之间不得为了减少枚举数量而合并返回码。

这样可以直接从函数签名确定该函数所有需要调用方处理的已知结果。

## 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 使用可配置的 Failure
Policy；第三方结果进入系统后重新按同一规则分类。**