ErisPulse ErisPulse
在交互式文档中心打开 →
本页章节
本文为静态镜像,内容以交互版为准 在交互式文档中心打开 →

ErisPulse.Core.Bases.errors 模块


模块概述

ErisPulse 异常体系

定义框架统一的异常层级,使模块和适配器无需直接依赖底层库的异常类型。 底层实现(如 aiohttp)的异常会在内部捕获并转换为对应的 ErisPulse 异常。

提示

  1. 使用 ClientError 统一捕获所有 HTTP/WS 客户端请求异常
  2. WebSocket 断开使用 WebSocketDisconnect,服务端和客户端通用
  3. 底层库异常(aiohttp.ClientError 等)不会泄露到业务代码

类列表

class ErisPulseError(Exception)

ErisPulse 基础异常

所有 ErisPulse 自定义异常的基类。

class ClientError(ErisPulseError)

客户端异常基类

所有 HTTP/WS 客户端请求相关的异常基类。 可用于统一捕获所有客户端错误。

:attribute url: 请求 URL(构建异常时提供则非空) :attribute method: 请求方法(GET / POST 等,构建异常时提供则非空) :attribute attempts: 已尝试的请求次数(重试耗尽时提供)

示例:

from ErisPulse.Core.Bases.errors import ClientError
try:
    resp = await sdk.client.get("https://example.com")
except ClientError as e:
    print(f"请求失败: {e} url={e.url}")

class ClientConnectionError(ClientError)

客户端连接异常

DNS 解析失败、连接被拒绝、网络不可达等连接层错误。

示例:

try:
    resp = await sdk.client.get("https://unreachable.example.com")
except ClientConnectionError:
    print("无法连接到服务器")

class ClientTimeoutError(ClientError)

客户端超时异常

连接超时或请求超时。

示例:

try:
    resp = await sdk.client.get("https://slow.example.com", timeout=5)
except ClientTimeoutError:
    print("请求超时")

class HTTPStatusError(ClientError)

HTTP 状态码异常

服务器返回了错误的状态码 (4xx/5xx)。

  • status: int HTTP 状态码
  • message (str): 错误消息

示例:

try:
    resp = await sdk.client.get("https://example.com/404")
except HTTPStatusError as e:
    print(f"状态码: {e.status}")

class WebSocketError(ErisPulseError)

WebSocket 异常基类

WebSocket 连接、通信相关的异常。

class ConnectionRegistryError(ErisPulseError)

连接注册表异常基类

连接池(ErisPulse.connections)的查找、权限与生命周期操作 相关的异常基类,可用于统一捕获所有连接池错误。

class ConnectionNotFoundError(ConnectionRegistryError)

连接不存在

按连接 id 查找失败或目标连接已断开注销时抛出。

:attribute connection_id: 查找的连接 id

class ConnectionPermissionError(ConnectionRegistryError)

连接操作无权限

非 owner 模块尝试关闭他人连接时抛出(连接的关闭权归创建者)。 发送消息与分组操作不受限。

:attribute connection_id: 目标连接 id :attribute owner: 连接的归属 owner(模块名 / 平台名)

class StorageError(ErisPulseError)

存储异常基类

所有存储后端相关的异常基类。

class StorageOperationError(StorageError)

存储操作执行失败

操作执行层错误(写锁竞争超时 / SQL 错误 / 约束冲突等)。默认抛出—— 库可达而操作失败意味着数据未写入,静默返回会让调用方在无感知中丢数据。

与 :class:StorageUnreachableError(连接级不可达)的边界:后者是运行 环境故障,冷却期内快速失败返回 False / None(框架韧性语义, 规则 26),不抛本异常。

class StorageUnreachableError(StorageError)

存储后端不可达

后端连接池创建在自动重试耗尽后仍失败(数据库不可达 / 凭据错误 / 网络隔离等)。框架保持运行,存储操作在冷却期内快速失败并自动重连。

连接状态变化的运行时感知推荐订阅生命周期事件 storage.unreachable / storage.recovered(本异常主要供 直接操作存储底层的场景捕获)。

:attribute backend: 存储后端名(sqlite / mysql / postgres) :attribute cooldown: 冷却时长(秒,进入冷却时提供)

class InteractionError(ErisPulseError)

交互会话异常基类

交互会话管理(等待回复 / 会话租约)相关的异常基类。 可用于统一捕获所有交互会话错误。

class ModuleError(ErisPulseError)

模块系统异常基类

模块加载、调用与通信相关的异常基类。

class ModuleCallError(ModuleError)

模块间调用异常基类

module.call() 跨模块调用相关的异常基类, 可用于统一捕获所有模块间调用错误。

:attribute module: 目标模块名 :attribute method: 目标方法名

class ModuleNotAvailableError(ModuleCallError)

目标模块不可用

调用的模块未注册 / 未启用 / 懒加载唤醒失败时抛出。

class ServiceNotProvidedError(ModuleCallError)

服务未提供

目标模块通过 provides 声明了服务白名单, 调用了不在白名单中的方法(或试图调用私有方法)时抛出。

class ModuleCallTimeoutError(ModuleCallError)

模块间调用超时

目标方法在超时时限内未返回时抛出。

:attribute timeout: 超时时限(秒)

class WebSocketDisconnect(WebSocketError)

WebSocket 断开连接异常

与 starlette.websockets.WebSocketDisconnect 完全兼容。 客户端和服务端 WebSocket 均可使用此异常表示连接断开。

  • code (int): 关闭码 (默认: 1000)
  • reason (str | None): 关闭原因 (可选)

示例:

from ErisPulse.Core.Bases.errors import WebSocketDisconnect
try:
    msg = await ws.receive_text()
except WebSocketDisconnect as e:
    print(f"断开: code={e.code}, reason={e.reason}")

class InteractionCancelled(InteractionError)

交互会话被取消

挂起的 wait_reply / 租约因非超时原因终止时设置到 future 上, 等待方可捕获本异常获取原因;上层 wait_reply 将其转换为返回 None。

:attribute reason: 取消原因(conflict / owner_unload / platform_stop / revoked / cancelled / cleared) :attribute wait_key: 关联的会话键

class SessionOccupiedError(InteractionError)

会话已被其他模块占用

:meth:InteractionManager.hold 获取互斥租约失败时抛出。

:attribute wait_key: 会话键 :attribute owner: 当前占用者(模块名 / 平台名,未知时为 None)

class StrictModeError(ErisPulseError)

严格模式致命错误

当严格模式级别为 2(致命)且检测到违规时,在检查点抛出此异常, 用于中止整个启动流程。

提示 此异常不应被加载器捕获吞掉,应向上传播至初始化协调器

class ShadowError(ErisPulseError)

影子模块异常基类

影子模块机制(ShadowManager 装配 / 转正 / 放弃)相关的异常基类, 可用于统一捕获所有影子模块错误。

class ShadowStateError(ShadowError)

影子模块状态不满足

目标模块未加载 / 已有活跃影子 / 未绑定影子等状态条件 不满足当前操作时抛出(start / dismiss 流程)。

class ShadowSourceError(ShadowError)

影子源不可用

影子源路径不存在、加载器缺失、源文件无可加载模块类 或影子加载失败时抛出(start 流程)。

class ShadowPromoteError(ShadowError)

影子模块转正失败

转正流程中目标未加载、影子未注册 / 未加载、加载器不支持快照 或转正重载失败时抛出(promote 流程)。