docs: 添加 Axis Innovators Box 框架完整 API 文档

- 新增浏览器模块技术文档,涵盖 BrowserCore、BrowserWindow 等核心组件
- 添加事件系统文档,包括 EventBus、GlobalEventBus 及各类事件定义
- 创建 LanguageManager 国际化管理器详细说明文档
- 新增 Log4j2OutputStream 标准输出重定向类文档
- 添加 Main 入口类启动流程与路由机制说明
- 创建 BrowserCreationCallback 回调接口使用指南
- 完善 AxisInnovatorsBox 主类架构与崩溃诊断系统文档
This commit is contained in:
2026-01-03 08:46:19 +08:00
parent 06f36fc3f0
commit 7badbb0d8e
29 changed files with 3011 additions and 2275 deletions

View File

@@ -0,0 +1,63 @@
这是一个专门为 `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*