Система исключений и руководство по обработке
Note
Обязательно к прочтению — одна из пяти ключевых статей в разделе "Путь чтения" на главной странице. Необходима для разработки модулей.
Все пользовательские исключения ErisPulse наследуются от ErisPulseError. Исключения底层 библиотек (например, aiohttp, aiomysql и т.д.) будут перехватываться внутри фреймворка и преобразовываться в соответствующие исключения ErisPulse — код бизнес-логики не должен зависеть от типов исключений底层 библиотек.
{!--< tips >!--}
- Для широкого перехвата: перехватите
ErisPulseError(базовый класс всех исключений фреймворка) - Для точной обработки: перехватите по модулям (например,
ModuleCallTimeoutError,StorageOperationError,StorageUnreachableError) - При неудачной операции записи в хранилище по умолчанию выбрасывается
StorageOperationError(начиная с версии 2.12); краткосрочные ошибки, связанные с недоступностью соединения, по-прежнему возвращаютFalse / None / default, а изменения состояния соединения можно отслеживать, подписавшись на событияstorage.unreachable/storage.recovered{!--< /tips >!--}
Обзор исключений
ErisPulseError # Базовый класс всех исключений фреймворка
├── ClientError # Базовый класс исключений HTTP/WS-клиента (Core/client)
│ ├── ClientConnectionError # Ошибки на уровне соединения: неудачное разрешение DNS, отказ в подключении, недоступность сети
│ ├── ClientTimeoutError # Ошибка таймаута запроса
│ └── HTTPStatusError # Ошибки HTTP-статуса (например, 4xx/5xx и raise_for_status)
├── WebSocketError # Базовый класс исключений WebSocket (WS-соединение в Core/client)
│ └── WebSocketDisconnect # Отключение WebSocket (общее для сервера и клиента)
├── ConnectionRegistryError # Базовый класс исключений реестра соединений (Core/connections, начиная с версии 2.10)
│ ├── ConnectionNotFoundError # Соединение не существует или уже отключено и отменено (connections.get/close)
│ └── ConnectionPermissionError # Закрытие чужого соединения без прав (закрытие доступно только создателю)
├── StorageError # Базовый класс исключений хранилища (Core/storage)
│ ├── StorageOperationError # Ошибка выполнения операции с хранилищем (начиная с версии 2.12, операции записи по умолчанию выбрасывают это исключение)
│ └── StorageUnreachableError # Недоступность хранилища (исчерпание попыток повторного подключения: недоступность базы данных, ошибка учетных данных)
├── InteractionError # Базовый класс исключений взаимодействия (Core/Event/interaction)
│ ├── InteractionCancelled # Прерванный ожидаемый ответ/аренда (wait_reply возвращает None)
│ └── SessionOccupiedError # Сессия занята (hold() не удалось получить аренду)
├── ModuleError # Базовый класс исключений модульной системы (Core/module)
│ └── ModuleCallError # Базовый класс исключений вызова модуля
│ ├── ModuleNotAvailableError # Целевой модуль не зарегистрирован/не активирован/не удалось инициализировать (включая ленивое обращение)
│ ├── ServiceNotProvidedError # Целевой модуль не объявил этот сервис (не в белом списке meta.services)
│ └── ModuleCallTimeoutError # Выполнение целевого метода превысило таймаут (по умолчанию 30s)
├── ShadowError # Базовый класс исключений "теневых модулей" (Core/shadow)
│ ├── ShadowStateError # Недопустимое состояние: модуль не загружен/уже есть активный теневой модуль/не привязан (start/dismiss)
│ ├── ShadowSourceError # Недоступный источник теневого модуля: путь не существует/отсутствует загрузчик/ошибка загрузки (start)
│ └── ShadowPromoteError # Ошибка повышения: теневой модуль не зарегистрирован/не загружен/загрузчик не поддерживает снапшот/ошибка перезагрузки (promote)
└── StrictModeError # Критическое нарушение строгого режима (прерывает процесс запуска, loaders/strict)
Структурированные свойства
После перехвата исключения можно прочитать структурированные свойства (без необходимости разбора текстового сообщения):
| Исключение | Свойства |
|---|---|
ClientError (включая подклассы) |
.url URL запроса, .method метод запроса, .attempts количество попыток (когда исчерпаны повторные попытки) |
HTTPStatusError |
.status код состояния, .message сообщение ответа |
WebSocketDisconnect |
.code код закрытия, .reason причина закрытия |
ConnectionNotFoundError |
.connection_id ID соединения |
ConnectionPermissionError |
.connection_id ID целевого соединения, .owner владелец соединения |
StorageUnreachableError |
.backend имя бэкенда (sqlite/mysql/postgres), .cooldown время охлаждения в секундах |
StorageOperationError |
.operation имя операции (set/delete/clear/set_multi/transaction_begin), .key ключ операции |
ModuleCallError (включая подклассы) |
.module имя целевого модуля, .method имя целевого метода |
ModuleCallTimeoutError |
Наследует .module/.method, дополнительно .timeout лимит времени (в секундах) |
InteractionCancelled |
.reason причина отмены, .wait_key ключ сессии |
SessionOccupiedError |
.wait_key ключ сессии, .owner владелец |
StrictModeError |
.violations список нарушений |
from ErisPulse.Core.Bases.errors import ClientError
try:
resp = await sdk.client.post(url, json=payload)
except ClientError as e:
print(f"Запрос не удался {e.method} {e.url}, всего попыток {e.attempts}: {e}")
Описание исключений и места их возникновения
Серия Client — Core/client.py / Core/Bases/client.py
Бросаются при отправке запросов через sdk.client / HTTP-клиент и WebSocket-клиент:
| Исключение | Место возникновения | Типичные сценарии |
|---|---|---|
ClientError |
Уровень обертки запросов | Другие клиентские ошибки (исключения底层 aiohttp уже преобразованы) |
ClientConnectionError |
Этап установки соединения | Целевой сервис недоступен, DNS не разрешается, отказ в подключении |
ClientTimeoutError |
Этап выполнения запроса | Превышен лимит времени запроса |
HTTPStatusError |
raise_for_status() |
Код состояния ответа 4xx/5xx |
from ErisPulse.Core.Bases.errors import ClientTimeoutError
try:
resp = await sdk.client.get("https://api.example.com", timeout=5)
except ClientTimeoutError:
...
Серия WebSocket — Core/client.py (методы send / receive)
| Исключение | Место возникновения | Типичные сценарии |
|---|---|---|
WebSocketError |
Методы отправки/приема | Соединение закрыто, получено неожидаемый тип сообщения,底层 WebSocket-исключения |
WebSocketDisconnect |
Методы отправки/приема | Противоположная сторона нормально закрыла соединение (фреймворк автоматически переподключится) |
Серия реестра соединений — Core/connections.py (начиная с версии 2.10)
| Исключение | Место возникновения | Типичные сценарии |
|---|---|---|
ConnectionNotFoundError |
connections.get / assign / dismiss / close |
ID соединения не существует или уже отключено и отменено |
ConnectionPermissionError |
Вызов conn.close() не владельцем |
Переключение модулей при закрытии чужого соединения (отправка и группировка не ограничены) |
Серия Storage — Core/storage / Core/Bases/sql_base.py
| Исключение | Место возникновения | Типичные сценарии |
|---|---|---|
StorageError |
Уровень хранилища | Базовый класс исключений, связанных с хранилищем |
StorageOperationError |
Пути записи / начало транзакции (начиная с версии 2.12) | Конкуренция на блокировку записи / SQL-ошибка / нарушение ограничений / таймаут начала транзакции — по умолчанию выбрасывается |
StorageUnreachableError |
Этап создания пула соединений | Недоступность базы данных / ошибка учетных данных / сетевая изоляция, исчерпаны попытки повторного подключения |
Семантика неудачи операций с хранилищем (начиная с версии 2.12):
- Операции записи по умолчанию выбрасывают
StorageOperationError(aset/adelete/aclear/set_multiи синхронные аналоги) — если бэкенд доступен, но операция записи не удалась, это означает, что данные не были записаны, и тихое возвращение приведет к потере данных вызывающей стороной; при важных операциях записи используйте try/except и делайте компенсацию- Ошибки на уровне соединения (в периоде охлаждения) по-прежнему возвращают
False/None/default(семантика устойчивости фреймворка), бизнес-код обычно не перехватываетStorageUnreachableError; для отслеживания состояния соединения используйте подписку на события жизненного циклаstorage.unreachable/storage.recovered(см. [События жизненного цикла](lifecycle.md#Состояние подключения хранилища))- Начало транзакции превысило 30 секунд выбрасывает
StorageOperationError(STORAGE_TXN_BEGIN_TIMEOUT_SECS) — бесконечное ожидание долгих транзакций является ошибкой фреймворка, и она должна быть видимой
Поведение при ошибках подключения см. в [Поведение при ошибках подключения](storage-backends.md#Поведение при ошибках подключения).
Взаимодействие — Core/Event/interaction.py
Связано с wait_reply / арендой сессии / таймером напоминания:
| Исключение | Место возникновения | Типичные сценарии |
|---|---|---|
InteractionError |
Уровень взаимодействия | Базовый класс исключений взаимодействия |
InteractionCancelled |
Когда ожидание отменяется | Устанавливается на ожидаемый future (ожидающий код может перехватить и получить .reason) |
SessionOccupiedError |
Не удалось получить аренду hold() |
Сессия уже занята другим владельцем (.owner показывает владельца) |
При отмене ожидания (при выгрузке модуля / завершении платформы / новое ожидание в той же сессии) wait_reply возвращает None, а не выбрасывает исключение (InteractionCancelled преобразуется внутренне); при необходимости различения причин отмены перехватите его напрямую.
Серия Module — Core/module.py (sdk.module.call)
| Исключение | Место возникновения | Типичные сценарии |
|---|---|---|
ModuleError |
Система модулей | Базовый класс исключений модульной системы |
ModuleCallError |
module.call() |
Базовый класс исключений вызова модуля |
ModuleNotAvailableError |
module.call() / ленивое обращение к атрибуту |
Целевой модуль не зарегистрирован / не активирован / не удалось инициализировать |
ServiceNotProvidedError |
module.call() |
Целевой meta.services не объявил этот метод (не в белом списке) |
ModuleCallTimeoutError |
module.call() |
Выполнение целевого корутина превысило лимит времени (по умолчанию 30s) |
"Целевой модуль недоступен" в разных путях доступа:
| Путь доступа | Исключение |
|---|---|
await sdk.module.call("X", "method") |
ModuleNotAvailableError (типизированное) |
sdk.module.X.attr (ленивое обращение к атрибуту, после неудачной инициализации) |
ModuleNotAvailableError |
sdk.module.X (обращение к атрибуту при неактивированном модуле) |
AttributeError (поведение Python, hasattr зависит от этой семантики) |
from ErisPulse.Core.Bases.errors import ModuleNotAvailableError, ServiceNotProvidedError
try:
history = await sdk.module.call("Chat", "get_history", session_id, n=20)
except ModuleNotAvailableError:
... # Целевой модуль не существует / не активирован
except ServiceNotProvidedError:
... # Целевой модуль не предоставляет этот сервис
Серия Shadow — Core/shadow.py (теневые модули)
| Исключение | Место возникновения | Типичные сценарии |
|---|---|---|
ShadowError |
Механизм теневых модулей | Базовый класс исключений для теневых модулей (общий перехват всех ошибок теневых модулей) |
ShadowStateError |
shadow_start() / dismiss_shadow() |
Целевой модуль не загружен / уже есть активный теневой модуль / не привязан (start/dismiss) |
ShadowSourceError |
shadow_start() |
Путь источника не существует / отсутствует загрузчик / класс источника не может быть загружен / ошибка загрузки |
ShadowPromoteError |
promote_shadow() |
Теневой модуль не зарегистрирован / не загружен / загрузчик не поддерживает снапшот / ошибка перезагрузки при повышении |
Внутренняя проверка параметров фреймворка (ValueError)
Проверка параметров конструктора хранилища (пустой тип столбца, Insert не dict, небезопасный тип столбца и т.д.) выбрасывает стандартный ValueError — это относится к ошибкам программирования на этапе разработки, и нормальный бизнес-код не должен перехватывать такие исключения, а должен исправлять вызов.
Не выбрасываются исключения при неудаче стандартных действий адаптера: возвращается словарь с кодом ошибки (retcode), например, retcode=10002 означает, что действие не реализовано — это параллельный канал ошибок по сравнению с клиентским слоем, где "ошибка" выбрасывает ClientError. Разработчику адаптера нужно обрабатывать оба канала.
Рекомендации по перехвату
from ErisPulse.Core import ErisPulseError # Базовый класс экспортируется из Core
try:
...
except ErisPulseError as e:
... # Общий перехват: все пользовательские исключения фреймворка
- Разработка модуля: перехватывайте по мере необходимости (см. выше), в самом внешнем уровне можно использовать
ErisPulseErrorдля общего перехвата - Все исключения экспортируются из
ErisPulse.Core(включаяSessionOccupiedError/InteractionCancelled/StrictModeError), также можно импортировать изErisPulse.Core.Bases.errors - Полное определение находится в
src/ErisPulse/Core/Bases/errors.py
Сворачивание шума при завершении
В процессах, работающих долго, при завершении (или отмене фонового цикла) цикл событий часто выводит серию "шума" от интерпретатора, например, "Task was destroyed but it is pending!". Фреймворк включает сворачивание подобного шума: в окне в 2 секунды одинаковые сообщения понижаются до уровня TRACE и объединяются, выводится только один раз, в конце добавляется суффикс «(ещё N подобных сообщений было свёрнуто)». Это сознательное снижение шума — видимость суффикса не означает, что фреймворк подавил реальное исключение, бизнес-исключения (см. выше) выводятся полностью. Сворачивание применяется только к шуму при завершении интерпретатора, бизнес-исключения не затрагиваются. Какие уровни исключений стоит сохранять, а какие можно понижать/сворачивать, см. в Правила прочности инженерии · Классификация оставляемых исключений.
Связанные документы
Выберите в зависимости от цели диагностики:
- Хранилище возвращает
False/None, хотите понять состояние соединения → [Поведение при ошибках подключения](storage-backends.md#Поведение при ошибках подключения), или подписывайтесь на события [storage.unreachable / storage.recovered](lifecycle.md#Состояние подключения хранилища) wait_replyвозвращаетNone, хотите узнать причину отмены → Система взаимодействия сессий (таблица причин отмены)module.callвыбрасывает исключения вызова модуля → Взаимодействие между модулями- Ошибки подключения / WebSocket → Сетевой клиент (система исключений ClientError) и Пул соединений и трансляция (исключения реестра соединений)