expected

Error_handling_specification.md

@@ -2,7 +2,7 @@
 
 ## 1. 已知结果处理规则
 
-属于 API 契约允许出现、调用方能够明确处理的情况，使用返回码表达，例如 `Xxx_Result`、`Xxx_Status`、`Xxx_Error`。
+属于 API 契约允许出现、调用方能够明确处理的情况，使用返回码表达。
 
 返回码不等于错误码，`timeout`、`cancelled`、`not_ready`、`no_change` 等都可以是正常结果。
 
@@ -12,6 +12,67 @@
 
 不按“内部/外部”区分。
 
+### 返回码定义规则
+
+**每个存在返回码的函数必须拥有自己独立的返回码枚举，不得在一个类或模块中定义大而通用的公共返回码枚举供多个函数混用。**
+
+例如：
+
+```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**。
@@ -47,19 +108,17 @@ exception
 
 第三方库自身使用返回码还是异常，不决定本系统的处理方式。
 
-接入第三方库后必须重新按照本系统规则分类：
-
 ```text
 第三方返回结果
     -> 本系统可预料、可处理
-       -> 转换为本系统返回码
+       -> 转换为当前函数自己的返回码
 
     -> 本系统没有可靠恢复方式
        -> 转换为 Unknown Failure
-       -> 交给当前 Unknown Failure Policy
+       -> 交给 Unknown Failure Policy
 ```
 
-不得机械透传第三方错误模型，也不得因为第三方返回了错误码，就强制在本系统中继续使用错误码。
+不得机械透传第三方错误模型，也不得因为第三方返回错误码，就强制在本系统继续使用错误码。
 
 ## 5. 其他要求
 
@@ -67,4 +126,5 @@ exception
 
 不得为了错误处理增加重复检查、兼容层、无意义 `try/catch`，也不得改变原函数的既有语义。
 
-**最终原则：已知结果使用返回码；未知失败使用可配置的 Unknown Failure Policy；第三方错误进入系统后重新按同一规则分类。**
+**最终原则：每个函数独立定义自己的已知返回结果；Unknown Failure 使用可配置的 Failure
+Policy；第三方结果进入系统后重新按同一规则分类。**