ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Система исключений и руководство по обработке

Note

Обязательно к прочтению — одна из пяти ключевых статей в разделе "Путь чтения" на главной странице. Необходима для разработки модулей.

Все пользовательские исключения ErisPulse наследуются от ErisPulseError. Исключения底层 библиотек (например, aiohttp, aiomysql и т.д.) будут перехватываться внутри фреймворка и преобразовываться в соответствующие исключения ErisPulse — код бизнес-логики не должен зависеть от типов исключений底层 библиотек.

{!--< tips >!--}

  1. Для широкого перехвата: перехватите ErisPulseError (базовый класс всех исключений фреймворка)
  2. Для точной обработки: перехватите по модулям (например, ModuleCallTimeoutError, StorageOperationError, StorageUnreachableError)
  3. При неудачной операции записи в хранилище по умолчанию выбрасывается 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) и Пул соединений и трансляция (исключения реестра соединений)