docs: synced via GitHub Actions

Author: nop-cao

src/theory/composition-over-inheritance-in-exception-handling.md

@@ -0,0 +1,190 @@
+# 告别异常继承树：从 NopException 的设计看“组合”模式如何重塑错误处理
+
+在软件开发中，异常处理是一个不可或缺的环节。长久以来，经典的面向对象思想教导我们，为不同类型的错误建立一个庞大的继承树是一种优雅的方案。例如，定义一个基础的 `AppException`，然后派生出 `BusinessException`、`SystemException` 等。这种基于**继承（Inheritance）**的设计模式直观且经典。时至今日，这种思想在许多开发者心中依然根深蒂固，被认为是“正统”的 OO 设计。
+
+然而，当系统走向分布式、服务化，并需要应对复杂的国际化、多租户、定制化需求时，这个看似优雅的“异常继承树”会逐渐变得僵化、臃肿，最终成为维护的噩梦。
+
+Nop 平台的 `NopException` 设计则另辟蹊径，它果断地放弃了庞杂的继承体系，采用单一、统一的异常类，通过**组合（Composition）**的方式来构建和描述错误。本文将深入剖析其设计，阐明为何这种组合式设计在现代复杂系统中是更优的选择，以及它如何实现传统继承模式难以企及的强大能力。
+
+## 一、 传统的“继承之困”：从“关注点混淆”到“分类学”的本质
+
+在深入技术细节之前，我们先来看一个普遍存在的问题：**传统的异常继承模式，从根本上导致了“关注点混淆”（Confusion of Concerns）。**
+
+想象一个开发者在业务代码中需要抛出一个“参数错误”，他会陷入一连串本不该由他考虑的思考：
+*   **分类问题**：我需要一个参数错误异常。系统中是否有现成的 `InvalidParameterException`？如果没有，我需要创建一个。它应该继承自 `BusinessException` 还是 `ValidationException`？
+*   **表现问题**：我需要给前端返回一个友好的中文提示。是直接把提示信息硬编码到异常的 message 里吗？（例如 `throw new InvalidParameterException("用户名不能为空")`）
+*   **处理问题**：这个错误不应该导致事务回滚。我是否需要寻找或创建一个 `NotRollbackableInvalidParameterException`？
+
+在这个思考链中，异常的**创建者**（业务开发者）被迫承担了过多的、本该由**使用者**（全局处理器、日志系统、事务管理器）决定的职责。他不仅要描述“发生了什么”，还要去思考“它应该如何被分类、如何被展示、如何被处理”。
+
+**这个问题的本质，根植于继承模式的核心——“is-a”（是一个）的分类学思想。**
+
+传统的继承模式，其核心是 “is-a”（是一个） 的关系。`InvalidParameterException` is-a `BusinessException`。它试图在编译期，用一个静态的、树状的“分类体系”去框定运行时千变万化的错误场景。然而，错误的属性是多维度的，这种僵化的分类法很快就会捉襟见肘。
+
+这种基于“分类”的设计模式，在实践中不可避免地会表现为以下三大困境：
+
+1.  **组合爆炸**：现实世界的错误属性是多维度的。一个错误可能既是“参数校验失败”，又需要“事务不回滚”。如果试图用继承来表达这些组合，我们将陷入创建无数子类的泥潭。
+2.  **僵化的层级结构**：继承关系在编译时就已经确定，是静态的。任何对层级树的调整都可能引发大规模的代码修改，违反了“开闭原则”。
+3.  **信息传递的割裂**：不同的异常子类携带不同的上下文信息。顶层的统一异常处理器为了获取这些信息，不得不编写大量的 `if (e instanceof ...)` 代码块，对每个子类进行强制类型转换，与所有具体的异常子类产生了紧耦合。
+
+## 二、组合的核心：NopException 如何实现“关注点分离”
+
+`NopException` 的设计哲学与继承完全相反，它基于 **“has-a”（有一个）** 的关系。它认为，一个异常**不是**某种特定的类型，而是**一个**包含了丰富结构化信息的通用容器。我们可以将其核心结构简化理解如下：
+
+```java
+// NopException 的简化核心结构
+public class NopException extends RuntimeException {
+    // 1. 错误标识：使用一个富信息的 ErrorCode 对象，而非裸字符串
+    private final ErrorCode errorCode;
+    // 2. 动态参数：一个 Map，用于携带任意结构化上下文信息
+    private final Map<String, Object> params = new HashMap<>();
+    // 3. 行为标志位：用于控制特殊逻辑，如事务回滚
+    private boolean notRollback;
+    // ... 其他元数据：如HTTP状态码、错误描述等
+    
+    // 通过链式调用方法（返回 this）实现属性的“组合”
+    public NopException param(String name, Object value) { /* ... */ }
+    public NopException notRollback(boolean notRollback) { /* ... */ }
+    // ...
+}
+```
+
+其精髓在于：
+*   **它是一个“数据容器”**：主要成员变量都是数据字段。
+*   **它采用“建造者模式”**：通过一系列返回 `this` 的方法，允许开发者像搭积木一样，自由地、动态地为一个异常实例添加属性和行为标志。
+
+使用时，代码从 `throw new InvalidParameterException(...)` 变成了更加清晰和强大的形式：
+```java
+// 假设 ApiErrors 接口中已定义了所有错误码常量
+import static io.nop.api.core.ApiErrors.ERR_VALIDATE_CHECK_FAIL;
+
+// ...
+List<String> validationErrors = ...;
+throw new NopException(ERR_VALIDATE_CHECK_FAIL)   // 1. 指定类型安全的错误码常量
+        .param("errors", validationErrors)       // 2. 组合结构化的上下文参数
+        .notRollback(true);                        // 3. 组合行为标志
+```
+
+**至此，创建者的任务已经全部完成。** 他不需要，也无法关心：
+*   这个异常最终会以什么语言（中文、英文）展示给用户。
+*   返回给前端的 HTTP 状态码是 400 还是 500。
+*   这个 `ErrorCode` 是否需要映射成另一个对外的错误码。
+*   日志系统会记录哪些参数，以何种格式记录。
+
+`NopException` 就像一个标准化的“事故报告单”，创建者只负责填写报告，而“如何解读和处理这份报告”是后续处理者的事。**创建者与使用者之间，通过 `NopException` 这个结构化的数据契约，实现了完美的关注点分离。**
+
+### 类型安全与工程实践：错误码常量化
+
+有人可能会质疑，使用基于标识符的错误码，是否会失去编译期的类型安全，沦为难以维护的“魔法字符串”？`NopException` 的设计者通过一个极其优雅的工程实践——错误码常量化，完美地解决了这个问题。
+
+框架强制要求所有的 `ErrorCode` 都必须在类似 `ApiErrors` 的接口中以常量的形式统一定义：
+
+```java
+// io.nop.api.core.ApiErrors.java
+public interface ApiErrors {
+    // 定义一个富信息的 ErrorCode 对象
+    ErrorCode ERR_CHECK_INVALID_ARGUMENT = 
+        define("nop.err.api.check.invalid-argument", "非法参数");
+
+    ErrorCode ERR_CHECK_NOT_EQUALS = 
+        define("nop.err.api.check.value-not-equals",
+               "实际值[{actual}]不等于期待值[{expected}]", "actual", "expected");
+    
+    // ... 其他数百个错误码定义
+}
+```
+
+这种设计带来了三大核心优势：
+
+1.  **恢复类型安全与IDE支持**：开发者使用 `ApiErrors.ERR_CHECK_INVALID_ARGUMENT` 而不是裸字符串，杜绝了拼写错误。IDE可以提供代码补全、查找引用、安全重命名等所有静态语言的便利，工程维护性大大提高。
+
+2.  **错误“契约”的中心化定义**：`ErrorCode` 不只是一个字符串，它是一个元数据载体。`define` 方法在编译期就将**唯一ID**、**默认消息模板**甚至**期望的参数名**（如 `"actual"`, `"expected"`）绑定在一起，形成了错误的“契约”。这为框架进行自动化校验和文档生成提供了可能。
+
+3.  **提升代码自文档性**：`ApiErrors` 接口本身就成了一份权威的、实时更新的“错误码字典”，极大地提升了代码的可读性和团队协作效率。
+
+## 三、能力升级：从 NopException 到标准 ApiResponse 的华丽变身
+
+`NopException` 的强大之处远不止于其自身的灵活性。它是一个精心设计的“信息包”，是整个框架异常处理流水线的起点。当 `NopException` 被全局异常处理器捕获后，它会经历一系列“加工”，最终被转换为一个标准的、可序列化的 `ApiResponse` 对象，返回给前端或服务调用方。
+
+这个“加工”过程由 `ErrorMessageManager` 负责，它赋予了 `NopException` 继承模式难以匹敌的三大高级能力：
+
+### 1. 体系规范化：统一的 `ApiResponse` 输出
+
+无论后台抛出何种 `NopException`，最终都会被统一转换为 `ApiResponse` 格式。
+
+```json
+// 成功时
+{ "status": 0, "data": { ... } }
+
+// 失败时
+{
+  "status": 1, 
+  "code": "VALIDATION_FAILED", // 映射后的错误码
+  "msg": "用户名不能为空"         // 国际化后的错误消息
+}
+```
+`NopException` 对象中的 `errorCode`、`params` 等数据，被精确地映射到 `ApiResponse` 的 `code`、`msg` 字段。这种设计实现了**后端异常到前端错误的标准化转换**，让整个系统的错误返回格式高度一致、可预测。
+
+### 2. 高度可配置的错误码映射
+
+在复杂的企业场景中，内部错误码和外部错误码往往需要解耦。`ErrorMessageManager` 通过外部化配置（如 YAML 文件）完美解决了这个问题。
+
+```yaml
+# error-mapping.yaml
+nop.err.api.check.invalid-argument: # 使用内部错误码ID作为key
+  mapToCode: E400_INVALID_PARAM # 将内部错误码映射为这个对外错误码
+  httpStatus: 400
+```
+这个映射机制**在运行时动态加载和应用**，无需修改代码即可为不同客户定制错误码体系。
+
+### **3. 强大的国际化（i18n）支持**
+
+**`ErrorMessageManager` 会根据当前用户的 `locale`（语言环境），加载对应语言的国际化资源（YAML 文件），将错误信息自动翻译。**
+
+**例如，系统会按模块和语言组织这些资源文件：**
+
+```yaml
+# /_vfs/i18n/zh-CN/sys.i18n.yaml
+nop.err.api.check.value-not-equals: "实际值[{actual}]不等于期待值[{expected}]"
+
+```
+
+```yaml
+# /_vfs/i18n/en/sys.i18n.yaml
+nop.err.api.check.value-not-equals: "The actual value [{actual}] is not equal to the expected value [{expected}]"
+```
+
+**当 `NopException` 携带 `ApiErrors.ERR_CHECK_NOT_EQUALS` 和 `{ "actual": 5, "expected": 10 }` 这些信息时，`ErrorMessageManager` 会：**
+1.  找到对应的错误码ID `nop.err.api.check.value-not-equals`。
+2.  **根据用户语言（如 `en`）加载对应的 `sys.i18n.yaml` 文件。**
+3.  **从 YAML 文件中获取消息模板。**
+4.  将 `NopException` 中的 `params` 填充到模板中。
+5.  生成最终的本地化消息：“The actual value [5] is not equal to the expected value [10]”。
+
+这整个过程对业务开发人员是完全透明的。
+
+## 结论：拥抱组合，构建面向未来的架构
+
+回到最初的问题：为什么传统的异常继承模式不再是最佳选择？
+
+因为在现代软件架构中，我们需要的不仅仅是一个能在 `catch` 块中被识别的“类型”，而是一个**能够携带丰富上下文、在处理流水线中被层层加工、并能灵活适应外部变化的“信息载体”**。
+
+| 对比维度 | 继承模式 (Inheritance) | 组合模式 (NopException) |
+| :--- | :--- | :--- |
+| **核心思想** | 分类学 (Is-A) | 结构主义 (Has-A) |
+| **灵活性** | 僵化，编译时确定 | 极高，运行时动态构建 |
+| **扩展性** | 差，易导致类爆炸 | 极好，通过配置和数据驱动 |
+| **工程实践**| 原生类型安全 | **通过常量模式，实现类型安全与IDE友好** |
+| **核心能力** | 类型匹配 | **标准化输出、错误码映射、国际化** |
+| **架构适应性**| 适用于简单应用 | **为复杂、分布式、服务化系统而生** |
+
+`NopException` 的设计哲学，正是从“这个错误**是什么**类型？”到“这个错误**由什么信息组成**？”的深刻思维转变。**它巧妙地通过错误码常量机制，弥补了组合模式在静态检查上的天然短板，实现了灵活性与工程健壮性的完美结合。**它与 `ErrorMessageManager`、`ApiResponse` 共同构成了一套优雅、强大且高度解耦的异常处理体系，有力地证明了**组合优于继承**在构建复杂、可演进系统中的绝对优势。这不仅仅是一种技术选择，更是一种面向未来的架构智慧。
+
+## 延伸阅读
+
+本文探讨的“组合优于继承”思想有着更深层的理论基础。如果您对以下问题感兴趣：
+- 为什么“组合优于继承”不仅仅是工程经验，而是有着深刻的数学必然性？
+- 继承的 `A > B ⇒ P(B) → P(A)` 与组合的 `A = B + C` 这两个公式背后揭示了怎样的逻辑差异？
+- 这种设计思想如何引领我们走向下一代软件构造理论——可逆计算？
+
+推荐阅读：《**[组合为什么优于继承：从工程实践到数学本质](https://mp.weixin.qq.com/s/P8tr71MD74fxCOfSleYJyg)**》，该文从数学本质出发，完整揭示了这一设计原则背后的深层逻辑。