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

Основные концепции

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; освойте все методы чтения и записи объекта события
  • Хотите учиться в процессе написания кода: Введение в обработку событий содержит готовые к копированию варианты обработчиков для каждого типа событий; Примеры типовых задач охватывает сохранение данных, запланированные задачи, контроль прав доступа и другие распространённые функции