194 lines
5.8 KiB
Markdown
194 lines
5.8 KiB
Markdown
# 错误处理机制
|
||
|
||
NEO Bot 采用了统一的错误处理机制，确保在各种异常情况下提供清晰、一致的错误信息。本文档将介绍系统的错误处理架构、错误码定义和使用方法。
|
||
|
||
## 1. 错误处理架构
|
||
|
||
### 1.1 自定义异常体系
|
||
|
||
系统定义了一套完整的自定义异常类体系，覆盖了各种常见的错误场景：
|
||
|
||
- **WebSocket 相关错误**：`WebSocketError`、`WebSocketConnectionError`、`WebSocketAuthenticationError`
|
||
- **插件相关错误**：`PluginError`、`PluginLoadError`、`PluginReloadError`、`PluginNotFoundError`
|
||
- **配置相关错误**：`ConfigError`、`ConfigNotFoundError`、`ConfigValidationError`
|
||
- **权限相关错误**：`PermissionError`
|
||
- **命令相关错误**：`CommandError`、`CommandNotFoundError`、`CommandParameterError`
|
||
- **Redis 相关错误**：`RedisError`
|
||
- **浏览器管理器相关错误**：`BrowserManagerError`、`BrowserPoolError`
|
||
- **代码执行相关错误**：`CodeExecutionError`
|
||
|
||
所有自定义异常类都位于 `core.utils.exceptions` 模块中。
|
||
|
||
### 1.2 统一的错误码系统
|
||
|
||
系统使用统一的错误码来标识不同类型的错误，错误码规则如下：
|
||
|
||
- `1xxx`：系统级错误
|
||
- `2xxx`：WebSocket 相关错误
|
||
- `3xxx`：插件相关错误
|
||
- `4xxx`：配置相关错误
|
||
- `5xxx`：权限相关错误
|
||
- `6xxx`：命令相关错误
|
||
- `7xxx`：Redis 相关错误
|
||
- `8xxx`：浏览器管理器相关错误
|
||
- `9xxx`：代码执行相关错误
|
||
|
||
完整的错误码定义可以在 `core.utils.error_codes` 模块的 `ErrorCode` 类中找到。
|
||
|
||
### 1.3 统一的错误响应格式
|
||
|
||
系统提供了统一的错误响应格式，确保所有模块返回一致的错误信息：
|
||
|
||
```json
|
||
{
|
||
"code": 错误代码,
|
||
"message": 错误消息,
|
||
"success": false,
|
||
"data": 附加数据（可选）,
|
||
"request_id": 请求ID（可选）
|
||
}
|
||
```
|
||
|
||
## 2. 日志记录增强
|
||
|
||
### 2.1 模块专用日志记录器
|
||
|
||
系统提供了 `ModuleLogger` 类，用于创建模块专用的日志记录器，自动添加模块标识：
|
||
|
||
```python
|
||
from core.utils.logger import ModuleLogger
|
||
|
||
# 创建模块专用日志记录器
|
||
logger = ModuleLogger("MyModule")
|
||
|
||
# 使用日志记录器
|
||
logger.info("模块初始化完成")
|
||
logger.error("发生错误")
|
||
logger.exception("发生异常")
|
||
```
|
||
|
||
### 2.2 异常详情记录
|
||
|
||
系统提供了 `log_exception` 函数，用于记录自定义异常的详细信息：
|
||
|
||
```python
|
||
from core.utils.logger import log_exception
|
||
from core.utils.exceptions import PluginError
|
||
|
||
try:
|
||
# 代码逻辑
|
||
raise PluginError("插件加载失败", plugin_name="test_plugin")
|
||
except Exception as e:
|
||
log_exception(e, module_name="PluginManager")
|
||
```
|
||
|
||
## 3. 核心模块的错误处理
|
||
|
||
### 3.1 WebSocket 模块
|
||
|
||
WebSocket 模块使用自定义异常类处理各种连接错误：
|
||
|
||
- `WebSocketConnectionError`：连接失败
|
||
- `WebSocketAuthenticationError`：认证失败
|
||
- `WebSocketError`：其他 WebSocket 相关错误
|
||
|
||
### 3.2 插件管理器模块
|
||
|
||
插件管理器模块使用自定义异常类处理各种插件操作错误：
|
||
|
||
- `PluginLoadError`：插件加载失败
|
||
- `PluginReloadError`：插件重载失败
|
||
- `PluginNotFoundError`：插件未找到
|
||
|
||
### 3.3 配置加载器模块
|
||
|
||
配置加载器模块使用自定义异常类处理各种配置加载错误：
|
||
|
||
- `ConfigNotFoundError`：配置文件未找到
|
||
- `ConfigValidationError`：配置验证失败
|
||
- `ConfigError`：其他配置相关错误
|
||
|
||
## 4. 全局异常捕获
|
||
|
||
系统在主程序入口添加了全局异常捕获机制，确保所有未处理的异常都能被捕获并提供友好的错误信息：
|
||
|
||
- 捕获并记录所有未处理的异常
|
||
- 生成统一格式的错误响应
|
||
- 根据错误类型给出不同的排查建议
|
||
- 提供详细的错误信息和日志记录位置
|
||
|
||
## 5. 如何在插件中使用错误处理
|
||
|
||
### 5.1 抛出自定义异常
|
||
|
||
在插件中，您可以使用系统提供的自定义异常类来抛出更精确的错误：
|
||
|
||
```python
|
||
from core.utils.exceptions import CommandParameterError
|
||
from core.utils.logger import ModuleLogger
|
||
|
||
logger = ModuleLogger("MyPlugin")
|
||
|
||
@matcher.command("test")
|
||
async def test_command(bot, event, args):
|
||
if len(args) < 1:
|
||
raise CommandParameterError("test", "缺少必要参数")
|
||
|
||
# 命令逻辑
|
||
```
|
||
|
||
### 5.2 捕获并处理异常
|
||
|
||
在插件中，您可以捕获并处理异常，提供更友好的错误信息：
|
||
|
||
```python
|
||
from core.utils.exceptions import PluginError
|
||
from core.utils.logger import ModuleLogger
|
||
|
||
logger = ModuleLogger("MyPlugin")
|
||
|
||
@matcher.command("test")
|
||
async def test_command(bot, event, args):
|
||
try:
|
||
# 可能抛出异常的代码
|
||
result = await some_operation()
|
||
await bot.send(event, f"操作结果: {result}")
|
||
except PluginError as e:
|
||
logger.error(f"插件操作失败: {e}")
|
||
await bot.send(event, f"操作失败: {e.message}")
|
||
except Exception as e:
|
||
logger.exception(f"发生未知错误: {e}")
|
||
await bot.send(event, "操作失败，请检查日志获取详细信息")
|
||
```
|
||
|
||
## 6. 错误排查建议
|
||
|
||
### 6.1 WebSocket 错误
|
||
|
||
- 检查 WebSocket 服务是否正在运行
|
||
- 检查配置文件中的 WebSocket 地址和令牌是否正确
|
||
- 检查网络连接是否正常
|
||
|
||
### 6.2 插件错误
|
||
|
||
- 检查插件目录是否存在
|
||
- 检查插件文件是否有语法错误
|
||
- 检查插件是否符合插件开发规范
|
||
|
||
### 6.3 配置错误
|
||
|
||
- 检查配置文件 config.toml 是否存在
|
||
- 检查配置文件格式是否正确
|
||
- 检查所有必填配置项是否都已设置
|
||
|
||
## 7. 总结
|
||
|
||
NEO Bot 的错误处理机制提供了：
|
||
|
||
- 完整的自定义异常类体系
|
||
- 统一的错误码系统
|
||
- 一致的错误响应格式
|
||
- 增强的日志记录功能
|
||
- 全局异常捕获和友好提示
|
||
|
||
这些功能确保了系统在各种异常情况下都能提供清晰、一致的错误信息，便于开发和维护。 |