Стандартизированный протокол возврата адаптера ErisPulse

1. Описание

Почему существует этот стандарт?

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

Однако протокол ErisPulse имеет некоторые специфические определения:

• 1. В базовых полях поле message_id обязательно, но в стандарте OneBot12 такого поля нет.
• 2. В возвращаемых данных необходимо добавить поле {platform_name}_raw, которое используется для хранения необработанных данных ответа.

2. Базовая структура ответа

Все ответы на действия должны содержать следующие базовые поля:

Необязательные поля:

3. Полный список полей

3.1 Общие поля

Пример успешного ответа

{
    "status": "ok",
    "retcode": 0,
    "data": {
        "message_id": "1234",
        "time": 1632847927.599013
    },
    "message_id": "1234",
    "message": "",
    "echo": "1234",
    "telegram_raw": {...}
}

Пример неудачного ответа

{
    "status": "failed",
    "retcode": 10003,
    "data": null,
    "message_id": "",
    "message": "Отсутствует обязательный параметр: user_id",
    "echo": "1234",
    "telegram_raw": {...}
}

3.2 Спецификация кодов возврата

0 Успешно (OK)

• 0: Успешно (OK)

1xxxx Ошибки запроса (Request Error)

2xxxx Ошибки обработчика действия (Handler Error)

3xxxx Ошибки выполнения действия (Execution Error)

Зарезервированные диапазоны ошибок

• 4xxxx, 5xxxx: Зарезервированные диапазоны, не должны использоваться
• 6xxxx–9xxxx: Другие диапазоны ошибок, доступны для пользовательских реализаций

4. Требования к реализации

1. Все ответы должны содержать поля status, retcode, data и message
2. Если в запросе присутствует непустое поле echo, ответ должен содержать поле echo с тем же значением
3. Коды возврата должны строго соответствовать спецификации OneBot12
4. Сообщения об ошибках (message) должны быть понятны человеку

5. Расширения спецификации

ErisPulse вносит следующие расширения в стандартный структурный ответ OneBot12:

5.1 Обязательное поле message_id

В стандарте OneBot12 поле message_id находится внутри объекта data и не является обязательным. ErisPulse выделяет его на уровень верхнего уровня как обязательное поле:

• Если message_id невозможно получить, его следует установить в пустую строку ""
• Обеспечьте, чтобы message_id всегда существовал, модулям не нужно проверять на null

5.2 Поле {platform}_raw с исходными ответами

В ответе должно содержаться поле {platform}_raw, в котором хранится полная копия исходных данных ответа платформы:

{
    "status": "ok",
    "retcode": 0,
    "data": {"message_id": "1234", "time": 1632847927},
    "message_id": "1234",
    "message": "",
    "telegram_raw": {
        "ok": true,
        "result": {"message_id": 1234, "date": 1632847927, ...}
    }
}

Требования:

• {platform}_raw должен быть глубокой копией исходного ответа, а не ссылкой
• platform должен полностью совпадать с именем платформы, зарегистрированной адаптером (чувствительно к регистру)
• Ошибки в исходном ответе также должны быть сохранены, чтобы облегчить отладку

5.3 Расширенные коды возврата фреймворка (34xxx, пользовательские младшие три цифры в сегменте платформы)

OneBot12 позволяет реализациям использовать пользовательские младшие три цифры в диапазоне 3xxxx. Сегмент 34xxx означает Platform Error (ошибка платформы бота, например, ограничения платформы, вызвавшие сбой). Внутри 34xxx используются низшие три цифры по уровню ответственности:

Фреймворк ErisPulse в настоящее время использует коды 346xx:

Разграничение ответственности: 34601 — это блокировка фреймворком до вызова (модуль не имеет права на действие); 34004 / 34xxx — это ошибки платформы после отправки действия (например, у бота нет прав, он заблокирован). При проверке проблем с правами модуль должен проверять оба типа: сначала 34601 (действие заблокировано scope), затем 34xxx (платформа ограничивает).

Структура ответа соответствует стандартному неудачному ответу §2:

{
    "status": "failed",
    "retcode": 34601,
    "data": null,
    "message_id": "",
    "message": "action 'send' denied by scope.actions"
}

5.5 Проверочный список реализации адаптера

• Включает поля status, retcode, data, message_id, message
• Коды возврата соответствуют спецификации OneBot12 (см. §3.2)
• Поле message_id всегда существует (если невозможно получить, устанавливается в пустую строку)
• Поле {platform}_raw содержит исходные данные ответа платформы

6. Примечания

• Для кодов ошибок 3xxxx последние три цифры могут быть определены реализацией
• Избегайте использования зарезервированных диапазонов ошибок (4xxxx, 5xxxx)
• 34600 / 34601 зарезервированы для фреймворка ErisPulse (см. §5.3), адаптеры/модули должны избегать их использования
• Сообщения об ошибках должны быть краткими и понятными, для облегчения отладки