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

Спецификация стандартизированных ответов адаптеров ErisPulse

Tip

Когда читать этот документ: когда вы реализуете в адаптере возвращаемые значения call_api / Send / Request, требуется убедиться, что структура ответа и коды возврата соответствуют стандарту ErisPulse, или разобраться в значении конкретного retcode — сверяйтесь с этим документом. Если это не нужно — пропустите.

1. Описание

Зачем нужна эта спецификация?

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

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

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

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

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

Имя поля Тип данных Обязательное Описание
status string Да Статус выполнения, должен быть "ok" или "failed"
retcode int64 Да Код возврата, соответствует правилам кодов возврата OneBot12
data any Да Данные ответа; при успехе содержит результат запроса, при неудаче — null
message_id string Да Идентификатор сообщения, используемый для идентификации; при отсутствии — пустая строка
message string Да Сообщение об ошибке; при успехе — пустая строка
{platform_name}_raw any Нет Исходные данные ответа

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

Имя поля Тип данных Обязательное Описание
echo string Нет Если запрос содержит поле echo, возвращается без изменений

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)

Код ошибки Название ошибки Описание
10001 Bad Request Некорректный запрос действия
10002 Unsupported Action Неподдерживаемый запрос действия
10003 Bad Param Некорректные параметры запроса действия
10004 Unsupported Param Неподдерживаемые параметры запроса действия
10005 Unsupported Segment Неподдерживаемый тип сегмента сообщения
10006 Bad Segment Data Некорректные данные сегмента сообщения
10007 Unsupported Segment Data Неподдерживаемые данные сегмента сообщения
10101 Who Am I Не указана учётная запись бота
10102 Unknown Self Неизвестная учётная запись бота

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

Код ошибки Название ошибки Описание
20001 Bad Handler Ошибка реализации обработчика действия
20002 Internal Handler Error Исключение во время выполнения обработчика действия

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

Диапазон кодов ошибок Тип ошибки Описание
31xxx Database Error Ошибка базы данных
32xxx Filesystem Error Ошибка файловой системы
33xxx Network Error Сетевая ошибка
34xxx Platform Error Ошибка платформы бота
35xxx Logic Error Ошибка логики действия
36xxx I Am Tired Реализация решила объявить забастовку

Зарезервированные сегменты ошибок

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

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

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

4.1 Помощники построения ответа: make_response / make_error

Для построения стандартных ответов адаптерам следует использовать два помощника из BaseAdapter, без необходимости вручную писать dict:

# Успех (send / call_api / _do_accept и все места, возвращающие стандартный ответ)
return self.make_response(
    data=result,                    # Данные ответа
    message_id=result.get("message_id", ""),
    raw=result,                     # Исходный ответ платформы → автоматически попадает в поле {platform}_raw
)

# Неудача (status всегда "failed")
return self.make_error(
    retcode=34100,                  # По умолчанию 34600 (SDK Failure); для ошибок платформы следует передавать собственный код 34xxx
    message="Отклонено контролем рисков платформы",
    raw=response,
)
Помощник Сигнатура Семантика
make_response (*, status="ok", retcode=0, data=None, message_id="", message="", raw=None) Собирает структуру по стандарту; если raw не None, автоматически добавляет ключ {platform}_raw (имя платформы берётся из self._platform)
make_error (retcode=34600, message="", raw=None) Сокращение для make_response(status="failed", ...)

Ручное написание эквивалентного dict также допустимо (достаточно совпадения структуры); ценность помощников — в корректной конкатенации имени платформы для {platform}_raw и в том, что полнота полей не будет нарушена.

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

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

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

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

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

Важно различать обе стороны: поднятие на верхний уровень в этом разделе относится только к ответам на действия (исходящим). message_id во входящих событиях message является обязательным полем верхнего уровня согласно базовой спецификации OneBot12, см. стандарт преобразования событий.

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 используется послойно по зонам ответственности:

Сегмент трёх младших разрядов Принадлежность Назначение
340xx Реализация адаптера Семейство операций запросов (Request Not Found / Already Handled / Not Supported / Permission Denied, см. request-action-spec §7)
341xx–345xx Реализация адаптера Ошибки со стороны платформы: права доступа / контроль рисков / ограничения учётной записи и т. п. (реализация определяет три младших разряда самостоятельно, исходная ошибка помещается в {platform}_raw)
346xx Фреймворк ErisPulse (зарезервировано) Перехват самим фреймворком и общие неудачи; адаптерам/модулям не занимать
347xx–349xx Реализация адаптера Прочие ошибки выполнения на стороне платформы

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

Код ошибки Название ошибки Описание
34600 SDK Failure Общая неудача фреймворка (код возврата по умолчанию для make_error())
34601 Action Denied Исходящее действие запрещено областью видимости (scope.actions), вызов не был инициирован, этот ответ возвращается сразу

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

Структура ответа — стандартный ответ об ошибке из §2:

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

5.4 Чек-лист реализации адаптера

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

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

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

Следующие шаги

  • Справочник при реализации возвращаемых значений для каждого DSL: стандарт действий API (поле data стандартных действий), спецификация операций запросов (расширение 34001-34004 для операций запросов), спецификация методов отправки (семантика деградации при неудаче отправки)
  • Диагностика сбоев, связанных с правами: сначала смотрите 34601 (модуль заблокирован scope, фреймворк перехватывает до вызова, см. §5.3), затем 34xxx (действие отправлено, но отклонено на стороне платформы)