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

Технические стандарты

Tip

Когда читать этот документ: когда вы разрабатываете или модифицируете адаптер и вам нужно проверить, соответствуют ли преобразование событий, ответы API, методы отправки и т. д. кроссплатформенному стандарту ErisPulse, обращайтесь к соответствующим спецификациям в этом каталоге для сверки. Если не знаете, с чего начать, сначала прочитайте общий обзор ниже.

Общий обзор: Руководство по стандартизации адаптеров — принципы стандартизации, карта стандартов, правила именования, шаблоны обработки различий и чек-лист разработчика. Для новых адаптеров/новых возможностей начните с него.

Этот документ содержит технические стандарты ErisPulse, обеспечивающие согласованность и совместимость между всеми компонентами.

Стандартный список документов

  1. Стандарт типов сессий - Определения и сопоставления типов сессий ErisPulse
  2. Стандарт преобразования событий - Стандарты преобразования событий платформы, расширения правил именования, стандарты сегментов сообщений
  3. Стандарт ответов API - Формат ответов API адаптера и требования к расширению
  4. Спецификация методов отправки - Назначение имен методов Send, параметры и требования к обратному преобразованию
  5. Спецификация действий запроса - Требования к полям событий запроса, DSL запроса (approve/reject), сохранение контекста запроса для гетерогенных точек и требования к реализации адаптера
  6. Стандарт действия API - Единый интерфейс стандартных действий API OneBot12 (управление пользователями/группами/каналами/сообщениями/файлами с фрагментами/мета-действия)
  7. Руководство по стандартизации адаптеров (общие принципы) - Принципы стандартизации/рабочий процесс/правила именования + стандарты интерактивных компонентов (кнопки/клавиатуры/события обратного вызова) и сопоставление с платформами

Обзор стандарта

ErisPulse использует OneBot12 в качестве основного стандарта событий и расширяет его с помощью дополнительных расширений и уточнений.

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

  1. Совместимость: Все стандарты должны быть совместимы со стандартом OneBot12.
  2. Расширяемость: Платформенные функции расширяются с помощью префиксов, чтобы избежать конфликтов.
  3. Согласованность: Ключевые поля, такие как временные метки и форматы идентификаторов, должны обрабатываться единообразно.
  4. Отслеживаемость: Сохраняются исходные данные для отладки и устранения проблем.

Почему нужен стандарт?

1. Обеспечение совместимости между платформами

Форматы событий на разных платформах различаются. Стандартизированный перевод обеспечивает:

  • Код модуля нужно писать только один раз, чтобы он работал на всех платформах
  • Логика обработки событий остается одинаковой
  • Снижение затрат на разработку и обслуживание

2. Стандартизация интерфейсов API

Единый формат ответа API обеспечивает:

  • Модуль может последовательно обрабатывать ошибки API
  • Информация об ошибках единообразна и легко понимаема
  • Структура возвращаемых данных одинакова

3. Повышение качества кода

Стандартные правила помогают:

  • Поддерживать единообразный стиль кода
  • Сокращать конфликты имен
  • Повышать читаемость кода

Преимущества соблюдения стандартов

Для разработчиков адаптеров

  • Четкие правила преобразования
  • Единый формат ответа
  • Легкость отладки и тестирования

Для разработчиков модулей

  • Единый интерфейс событий
  • Предсказуемое поведение API
  • Упрощение разработки для разных платформ

Для конечных пользователей

  • Стабильное поведение системы
  • Единый формат сообщений
  • Хорошая совместимость

Список проверки соответствия стандартам

Преобразование событий

  • Все стандартные поля корректно сопоставлены
  • Платформенные специфичные поля имеют префикс
  • Временные метки преобразованы в 10-значные секундные значения
  • Исходные данные сохранены в {platform}_raw
  • Тип исходного события сохранён в {platform}_raw_type
  • Сформировано поле alt_message для сегментов сообщений
  • Поле request_id присутствует в событиях запроса

Ответы API

  • Содержит поле status
  • Содержит поле retcode
  • Содержит поле data
  • Содержит поле message_id
  • Содержит поле message
  • Коды возврата соответствуют спецификации OneBot12

Назначение методов отправки

  • Используется стиль именования PascalCase
  • Возвращает объект Task
  • Методы-модификаторы возвращают self
  • Имена параметров соответствуют стандарту

Отправка медиа (Image / Voice / Video / File)

  • Параметр file должен поддерживать все следующие формы: HTTP(S) URL / локальный путь / bytes
  • Параметр file должен поддерживать следующие формы по возможности: file:// URI / Base64 / Data URI (при невозможности поддержки возвращать retcode=10002 по убывающей)
  • Порядок определения формы соответствует стандарту (bytes → URL → file:// → путь)
  • Имя файла File генерируется по следующему порядку приоритета (явное filename > basename из URL > basename из пути > платформенный дефолт)
  • Ограничения на медиа платформы указаны в документации адаптера
  • Неподдерживаемые типы медиа обрабатываются по убывающей (снижение к похожим типам или retcode=10002, без выброса исключений и без тихого отбрасывания)

Подробнее см. Спецификация методов отправки §2.1

Операции запросов

  • Класс Request переопределил _do_accept / _do_reject (не переопределять публичные методы accept()/reject())
  • Результат операции соответствует стандартному формату ответа API
  • Неподдерживаемые операции возвращают retcode=10002

Связанные документы