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

Общее руководство: Руководство по стандартизации адаптеров —— Принципы стандартизации, стандартные карты, правила именования, режимы обработки различий и контрольный список для разработчиков. Новые адаптеры/новые возможности следует изучить перед началом.

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

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

1. Стандарт типов сессий - Определения и сопоставление типов сессий ErisPulse
2. Стандарт преобразования событий - Стандарты преобразования событий платформы, расширение правил именования, стандартные сегменты сообщений
3. Стандарт ответа API - Стандарт формата ответа API адаптера и требования к расширению
4. Спецификация методов отправки - Назначение имен методов класса Send, параметры и требования к обратному преобразованию
5. Спецификация действий запроса - Требования к полям событий запроса, DSL HandleRequest и требования к реализации адаптера
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
• Порядок определения формы соответствует стандарту (bytes → URL → file:// → путь)
• Имя файла File генерируется по порядку предпочтений (явное filename > basename из URL > basename из пути > значение по умолчанию платформы)
• Ограничения на медиа платформы указаны в документации адаптера
• Неподдерживаемые типы медиа обрабатываются по ступенчатой схеме (снижение к близкому типу или retcode=10002, без выбрасывания исключений и без тихого отбрасывания)

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

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

• Класс HandleRequest реализует _do_accept / _do_reject
• Результат операции имеет стандартный формат ответа API
• Для не поддерживаемых операций возвращается retcode=10002

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

• Руководство по функциональным возможностям платформы - Ознакомьтесь с различиями функциональных возможностей на разных платформах
• Руководство для разработчиков - Разработка пользовательских модулей и адаптеров