Основные концепции
Note
Обязательно к прочтению для L1 Core — 2-я из «Пяти статей L1 Core» на главной странице документации (Введение в разработку модулей → Основные концепции → Класс-обёртка Event → Описание файлов конфигурации → Перехват исключений).
Какие компоненты проходит сообщение от отправки пользователем до ответа бота? За что отвечают адаптеры и за что модули? Прочитав эту статью, вы сможете самостоятельно отвечать на вопросы по дизайну, возникающие при написании обработчиков, вместо того чтобы просто копировать примеры.
Событийно-ориентированная архитектура
ErisPulse использует событийно-ориентированную архитектуру: все взаимодействия передаются и обрабатываются через события.
Поток событий
Пользователь отправляет сообщение
│
▼
Платформа принимает
│
▼
Адаптер принимает нативное событие платформы
│
▼
Преобразование в стандартное событие OneBot12
│
▼
Передача в систему событий
│
▼
Распределение зарегистрированным обработчикам
│
▼
Модуль обрабатывает событие
│
▼
Отправка ответа через адаптер
│
▼
Платформа отображает пользователю
Стандарт OneBot12
ErisPulse использует OneBot12 в качестве основного стандарта событий. OneBot12 — это универсальный стандарт интерфейса приложений чат-ботов, определяющий единый формат событий.
Все адаптеры преобразуют события, специфичные для платформы, в формат OneBot12, обеспечивая согласованность кода.
Основные компоненты
1. Объект SDK
SDK — это единая точка входа для всей функциональности, предоставляющая доступ к основным компонентам.
from ErisPulse import sdk
# Доступ к основным модулям
sdk.storage # Система хранения
sdk.config # Система конфигурации
sdk.logger # Система логирования
sdk.adapter # Система адаптеров
sdk.module # Система модулей
sdk.router # Система маршрутизации
sdk.client # HTTP-клиент
sdk.lifecycle # Система жизненного цикла
Warning
Импортируйте единообразно из корня: from ErisPulse.Core import adapter / import ErisPulse.Core.adapter
Такая запись привязывается к экземпляру менеджера (синглтону AdapterManager), а не к субмодулю —
re-export пакета ErisPulse.Core затеняет одноимённый субмодуль. При написании тестов, патчинге или
когда требуется сам объект модуля, всегда используйте корневой импорт from ErisPulse import sdk
(sdk.adapter — это и есть экземпляр менеджера).
2. Объект Event
Объект Event инкапсулирует данные события и предоставляет удобные методы доступа.
@command("info")
async def info_handler(event):
# Получение информации о событии
event_id = event.get_id()
user_id = event.get_user_id()
platform = event.get_platform()
text = event.get_text()
# Отправка ответа
await event.reply(f"Пользователь: {user_id}, платформа: {platform}")
3. Адаптеры
Адаптеры — это мост между ErisPulse и внешними платформами.
Обязанности:
- Приём нативных событий платформы
- Преобразование в стандартный формат OneBot12
- Отправка событий в стандартном формате на платформу
Примеры адаптеров:
- Адаптер Yunhu: взаимодействие с платформой Юньху
- Адаптер Telegram: взаимодействие с Telegram Bot API
- Адаптер OneBot11: взаимодействие с приложениями, совместимыми с OneBot11
- Адаптер Email: обработка отправки и получения электронной почты
4. Модули
Модули — это базовые единицы расширения функциональности, которые могут:
- регистрировать обработчики событий
- реализовывать бизнес-логику
- вызывать адаптеры для отправки сообщений
- использовать сервисы, предоставляемые основными модулями
Механизм обнаружения модулей
ErisPulse обнаруживает установленные модули с помощью Python-механизма importlib.metadata.entry_points. Модуль объявляет точку входа в pyproject.toml:
[project.entry-points."erispulse.module"]
MyModule = "my_package:Main"
При инициализации SDK сканируются все точки входа группы erispulse.module, классы модулей регистрируются в ModuleManager, а затем инициализируются по очереди после топологической сортировки по зависимостям.
Минимальный рабочий модуль
from ErisPulse.Core.Bases import BaseModule
from ErisPulse import sdk
class Main(BaseModule):
def __init__(self):
self.sdk = sdk
self.logger = sdk.logger.get_child("MyModule")
async def on_load(self, event):
self.logger.info("Модуль загружен")
async def on_unload(self, event):
self.logger.info("Модуль выгружен")
Жизненный цикл модуля
- Регистрация: SDK обнаруживает класс модуля и регистрирует его в менеджере
- Загрузка: создаётся экземпляр модуля, вызывается
on_load(event)(event = {"module_name": "MyModule"}) - Выгрузка: вызывается
on_unload(event), ресурсы очищаются
Стратегия загрузки
Поведение загрузки модуля объявляется через get_load_strategy():
from ErisPulse.loaders import ModuleLoadStrategy
class Main(BaseModule):
@staticmethod
def get_load_strategy():
return ModuleLoadStrategy(
lazy_load=True, # Ленивая загрузка (по умолчанию True)
priority=0 # Приоритет загрузки; чем больше число, тем раньше инициализация
)
lazy_load=True(по умолчанию): модуль инициализируется только при первом обращении черезsdk.MyModule, что сокращает время запускаlazy_load=False: модуль инициализируется сразу при запуске SDK; подходит для модулей, которым нужно прослушивать события жизненного цикла или выполнять запланированные задачиpriority: модули с одинаковым приоритетом загружаются в порядке регистрации; чем больше число, тем раньше инициализация
Подробное описание механизма ленивой загрузки см. в Система ленивой загрузки.
Типы событий
ErisPulse поддерживает 5 типов событий:
| Тип события | Декоратор | Описание |
|---|---|---|
| События сообщений | @message.on_message() |
Любые сообщения, отправленные пользователями (личные и групповые чаты) |
| События команд | @command("name") |
Сообщения, начинающиеся с префикса команды (например, /hello) |
| События уведомлений | @notice.on_friend_add() и др. |
Системные уведомления (добавление в друзья, изменение участников группы и т.д.) |
| События запросов | @request.on_friend_request() и др. |
Запросы пользователей (заявки в друзья, приглашения в группы) |
| Мета-события | @meta.on_connect() и др. |
События системного уровня (подключение, отключение, heartbeat) |
Подробное использование и примеры кода для каждого типа событий см. в Введение в обработку событий.
Основные модули
Storage (Хранилище)
Система хранения пар "ключ-значение", основанная на SQLite, для постоянного хранения данных.
# Установка значения
sdk.storage.set("key", "value")
# Получение значения
value = sdk.storage.get("key", "default_value")
# Массовая операция
sdk.storage.set_multi({
"key1": "value1",
"key2": "value2"
})
# Транзакция
with sdk.storage.transaction():
sdk.storage.set("key1", "value1")
sdk.storage.set("key2", "value2")
Config (Конфигурация)
Управление конфигурационными файлами в формате TOML.
# Получение конфигурации
config = sdk.config.getConfig("MyModule", {})
# Установка конфигурации
sdk.config.setConfig("MyModule", {"key": "value"})
# Чтение вложенной конфигурации
value = sdk.config.getConfig("MyModule.subkey", "default")
Logger (Журналирование)
Модульная система журналирования.
# Запись в лог
sdk.logger.info("Это информационное сообщение")
sdk.logger.warning("Это предупреждение")
sdk.logger.error("Это ошибка")
# Получение поджурнала
child_logger = sdk.logger.get_child("submodule")
child_logger.info("Журнал подмодуля")
Синтаксис доступа по атрибутам
Помимо использования метода get_child(), вы можете использовать атрибутный доступ для создания поджурнала, что является более компактным синтаксическим сахаром:
# Создание поджурнала через атрибутный доступ
sdk.logger.mymodule.info("Сообщение модуля")
# Поддержка вложенного доступа
sdk.logger.mymodule.database.info("Сообщение базы данных")
Router (Маршрутизация)
Управление маршрутизацией HTTP и WebSocket, основанное на FastAPI + Uvicorn. Поддерживает маршрутизацию с помощью декораторов, промежуточные слои, группировку, ограничение скорости, CORS.
from ErisPulse.Core import HttpRequest
@sdk.router.get("MyModule", "/api")
async def handler(request: HttpRequest):
data = await request.json()
return {"status": "ok"}
Полный API маршрутизатора (WebSocket, промежуточные слои, ограничение скорости, CORS и т.д.) см. в Маршрутизаторе.
Client (Сетевой клиент)
Единый сетевой клиент, объединяющий HTTP-запросы, WebSocket-соединения, управление пула соединений, автоматические повторы, таймауты, статистику запросов и интеграцию событий жизненного цикла.
from ErisPulse.Core import client
# HTTP-запрос
resp = await client.get("https://api.example.com/users")
data = await resp.json()
# С повторами и таймаутом
resp = await client.get(url, timeout=30, max_retries=3)
# WebSocket-соединение
ws = await client.ws_connect("wss://example.com/ws")
async for text in ws.iter_text():
await ws.send_text(f"Эхо: {text}")
Полный API сетевого клиента см. в Сетевом клиенте.
Отправка сообщений SendDSL
Адаптеры предоставляют интерфейс отправки сообщений в виде цепочки вызовов.
Базовая отправка
# Получение экземпляра адаптера
yunhu = sdk.adapter.get("yunhu")
# Отправка сообщения
await yunhu.Send.To("user", "U1001").Text("Hello")
# Указание аккаунта для отправки
await yunhu.Send.Using("bot1").To("group", "G1001").Text("Сообщение в группу")
Цепочка модификаторов
# Упоминание пользователя
await yunhu.Send.To("group", "G1001").At("U2001").Text("@сообщение")
# Ответ на сообщение
await yunhu.Send.To("group", "G1001").Reply("msg123").Text("Ответ")
# Упоминание всех
await yunhu.Send.To("group", "G1001").AtAll().Text("Объявление")
Методы ответа Event
Объект Event предоставляет удобные методы ответа:
@command("test")
async def test_handler(event):
# Простой текстовый ответ
await event.reply("Содержимое ответа")
# Отправка изображения
await event.reply("http://example.com/image.jpg", method="Image")
# Отправка голосового сообщения
await event.reply("http://example.com/voice.mp3", method="Voice")
Система ленивой загрузки
ErisPulse по умолчанию включает ленивую загрузку модулей: модуль инициализируется только при первом обращении (например, sdk.MyModule), что значительно ускоряет запуск.
from ErisPulse.loaders import ModuleLoadStrategy
class Main(BaseModule):
@staticmethod
def get_load_strategy():
return ModuleLoadStrategy(
lazy_load=True, # Включение ленивой загрузки (по умолчанию)
priority=0 # Приоритет загрузки; чем больше число, тем раньше инициализация
)
Сценарии, требующие отключения ленивой загрузки (lazy_load=False):
- Модули, прослушивающие события жизненного цикла (например,
core.init.complete) - Модули, запускающие запланированные задачи или фоновые сервисы
- Модули, которым необходимо завершить инициализацию до загрузки других модулей
Подробное описание механизма ленивой загрузки и важных замечаний см. в Система ленивой загрузки.
Следующие шаги
- Продолжайте по пути L1: следующая статья — Класс-обёртка Event; освойте все методы чтения и записи объекта события
- Хотите учиться в процессе написания кода: Введение в обработку событий содержит готовые к копированию варианты обработчиков для каждого типа событий; Примеры типовых задач охватывает сохранение данных, запланированные задачи, контроль прав доступа и другие распространённые функции