Технические стандарты
Tip
Когда читать этот документ: когда вы разрабатываете или модифицируете адаптер и вам нужно проверить, соответствуют ли преобразование событий, ответы API, методы отправки и т. д. кроссплатформенному стандарту ErisPulse, обращайтесь к соответствующим спецификациям в этом каталоге для сверки. Если не знаете, с чего начать, сначала прочитайте общий обзор ниже.
Общий обзор: Руководство по стандартизации адаптеров — принципы стандартизации, карта стандартов, правила именования, шаблоны обработки различий и чек-лист разработчика. Для новых адаптеров/новых возможностей начните с него.
Этот документ содержит технические стандарты ErisPulse, обеспечивающие согласованность и совместимость между всеми компонентами.
Стандартный список документов
- Стандарт типов сессий - Определения и сопоставления типов сессий ErisPulse
- Стандарт преобразования событий - Стандарты преобразования событий платформы, расширения правил именования, стандарты сегментов сообщений
- Стандарт ответов API - Формат ответов API адаптера и требования к расширению
- Спецификация методов отправки - Назначение имен методов Send, параметры и требования к обратному преобразованию
- Спецификация действий запроса - Требования к полям событий запроса, DSL запроса (approve/reject), сохранение контекста запроса для гетерогенных точек и требования к реализации адаптера
- Стандарт действия API - Единый интерфейс стандартных действий API OneBot12 (управление пользователями/группами/каналами/сообщениями/файлами с фрагментами/мета-действия)
- Руководство по стандартизации адаптеров (общие принципы) - Принципы стандартизации/рабочий процесс/правила именования + стандарты интерактивных компонентов (кнопки/клавиатуры/события обратного вызова) и сопоставление с платформами
Обзор стандарта
ErisPulse использует OneBot12 в качестве основного стандарта событий и расширяет его с помощью дополнительных расширений и уточнений.
Основные принципы
- Совместимость: Все стандарты должны быть совместимы со стандартом OneBot12.
- Расширяемость: Платформенные функции расширяются с помощью префиксов, чтобы избежать конфликтов.
- Согласованность: Ключевые поля, такие как временные метки и форматы идентификаторов, должны обрабатываться единообразно.
- Отслеживаемость: Сохраняются исходные данные для отладки и устранения проблем.
Почему нужен стандарт?
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
Связанные документы
- Руководство по функциональным возможностям платформы - Ознакомьтесь с различиями функциональных возможностей на разных платформах
- Руководство для разработчиков - Разработка пользовательских модулей и адаптеров