这是一个专门为 `com.axis.innovators.box.register.RegistrationError` 类编写的技术介绍文档。

---

# RegistrationError 类技术文档

**包路径:** `com.axis.innovators.box.register.RegistrationError`  
**类型:** 自定义错误类 (Custom Error)  
**继承关系:** `java.lang.Error`  
**作者:** tzdwindows 7

## 1. 概述

`RegistrationError` 是 **Axis Innovators Box** 框架中专门用于处理**注册阶段致命失败**的类。与标准的 `Exception` 不同，该类继承自 `java.lang.Error`，这表明它代表的是一种不可恢复的严重问题。

在工具加载、插件注册或核心组件初始化过程中，如果发生了违反框架逻辑或导致系统无法继续运行的错误，框架会抛出此错误以立即中断当前非法的操作流程。

## 2. 为什么选择继承自 `Error`？

在 Java 异常体系中，通常 `Exception` 用于程序可以处理的异常情况，而 `Error` 用于指示合理的应用程序不应该试图捕获的严重问题。

`RegistrationError` 继承自 `Error` 的设计意图在于：
1.  **强制中断:** 注册失败通常意味着插件配置错误、依赖缺失或核心工具 ID 冲突。这种情况下，继续运行程序可能会导致不可预知的行为或数据损坏。
2.  **跳过普通捕获:** 许多代码块会使用 `catch (Exception e)` 来捕获业务异常。继承自 `Error` 可以确保注册阶段的致命问题不会被普通的业务异常处理器“默默吞掉”，从而能被最外层的崩溃处理器（如 `AxisInnovatorsBox` 中的崩溃报告系统）捕获。
3.  **语义化:** 明确标识这是一个“框架级”的初始化错误，而非普通的“业务级”异常。

## 3. 构造函数

```java
public RegistrationError(String message) {
    super(message);
}
```

*   **`message`**: 详细的错误描述信息。通常包含注册失败的工具名称、原因以及可能的解决建议。

## 4. 使用场景

该错误通常由以下组件在验证失败时抛出：
*   **RegistrationTool**: 当尝试注册一个 ID 已经存在或参数非法的工具分类时。
*   **RegistrationTopic**: 当加载的主题类无法被实例化或不符合规范时。
*   **PluginLoader**: 当插件描述文件损坏或插件版本与核心框架严重不兼容时。

## 5. 代码示例

以下是该类在注册逻辑中的典型应用：

```java
public void registerTool(String toolId, ToolInstance tool) {
    if (registry.containsKey(toolId)) {
        // 如果 ID 冲突，抛出 RegistrationError，这将导致程序或该插件加载流程终止
        throw new RegistrationError("致命错误：工具 ID [" + toolId + "] 已存在，无法重复注册！");
    }
    registry.put(toolId, tool);
}
```

## 6. 与崩溃报告系统的集成

当 `RegistrationError` 被抛出且未被捕获时，它会触发 `AxisInnovatorsBox` 中设置的 `UncaughtExceptionHandler`。这将直接导致崩溃诊断窗口弹出，向用户显示详细的注册失败信息，并允许用户导出包含插件列表和系统状态的诊断包。

---
*文档生成时间: 2026-01-02*