Обработка ошибок в Wasaby

Механизм обработки ошибок в Wasaby создан для обеспечения единой, унифицированной обработки ошибок обмена данными по сети в рамках всего приложения. Он помогает сообщить пользователю о таких ошибках, а также предлагает варианты решения проблемы.

Сообщение об ошибке для пользователя отображается в виде основного текста ошибки, комментария и изображения персонажа. Наличие комментария и изображения зависит от типа ошибки и места, в котором она возникла. Текст ошибки и комментарий предназначены только для конечного пользователя и не включают в себя какие-либо технические данные, то есть ошибка является «дружелюбной» к пользователю.

Этапы обработки ошибки

Существует три основных этапа обработки ошибок:

  1. Возникновение ошибки

    На этом этапе ошибка возникает при работе с сетью в каком-то контроле и передается в контроллер ошибки для ее дальнейшей обработки.

  2. Обработка ошибки

    На этапе обработки ошибка распознается, а затем формируются настройки для показа ошибки.

  3. Отображение ошибки

    Специальный контрол-контейнер получает настройки для показа ошибки и отображает ее пользователю.

<center></center>

Рис. 1. Этапы обработки ошибки

Рассмотрим каждый этап подробнее.

Возникновение ошибки

Механизм обработки ошибок работает с ошибками при обмене данными по сети, поэтому для обработки можно передать ошибку, полученную:

  • в ответе метода бизнес-логики;
  • в результате работы XMLHttpRequest или fetch;
  • во время загрузки ресурсов, указанных в атрибуте src html тегов.

Чтобы иметь возможность показать полученную ошибку в интерфейсе, нужно передать ее на обработку контроллеру errorController.

Обработка ошибки

Обработка ошибки происходит в контроле Controls/dataSource:error.Controller. Он имеет доступ к специальным функциям - обработчикам.

Функция-обработчик принимает ошибку, а возвращает конфигурацию для ее отображения или undefined. Каждый обработчик предназначен для работы с ошибкой, подходящей под конкретные условия, например, код ошибки. Если ошибка не удовлетворяет условиям обработчика, обработчик вернет undefined. Контроллер передает ошибку по очереди каждому обработчику до тех пор, пока какой-то из них не вернет конфигурацию. Если ни один из обработчиков не смог обработать ошибку, то будет показано диалоговое окно с текстом из свойства message объекта error.

В рамках приложения существуют стандартные обработчики, с которыми работает Контроллер. Они обрабатывают ошибки с кодами:

  • 0 (разрыв соединения)
  • 401 (только на диспетчере)
  • 403
  • 404
  • 500
  • 502
  • 503
  • 504

Помимо стандартных обработчиков, разработчику предоставлена возможность использовать свои собственные обработчики ошибок. Массив со своими обработчиками можно передать в конструктор errorController. Также обработчик можно добавить, передав его методу addHandler. Ошибку с помощью своего обработчика можно обработать прежде стандартных обработчиков, либо после них - в зависимости от задачи.

Схема работы errorController представлена ниже на рисунке.

<center></center>

Рис. 2. Схема работы errorController

Отображение ошибки

После обработки ошибки с помощью errorController вы получите объект — конфигурацию отображения ошибки. Этот объект нужно передать в контейнер ошибки — Controls/dataSource:error.Container.

Режимы отображения ошибки

В зависимости от конфигурации, errorContainer покажет ошибку одним из трех способов:

  • в диалоговом окне;
  • вместо вашего контрола;
  • на всю страницу.

Режимы отображения ошибки errorContainer показаны на рисунке ниже.

<center></center>

Рис. 3. Режимы отображения ошибки

Составные части шаблона ошибки

Шаблон дружелюбной ошибки состоит из четырех частей:

  1. Изображение персонажа.

    Наличие изображения зависит от ширины контрола, в котором произошла ошибка. По стандарту, если ширина контрола не превышает 166 пикселей, то изображение отсутствует.

  2. Сообщение ошибки.

    Сообщение зависит от кода ошибки и содержит краткое описание проблемы, например, «Произошел разрыв соединения».

  3. Предлагаемое действие для решения проблемы (опционально).

    Этот текст предлагает пользователю действие для проблемы, например, «Проверьте подключение к интернету».

  4. Кнопка-ссылка (опционально).

    Кнопка-ссылка также помогает пользователю решить проблему, нажав на эту кнопку. Это может быть, например, ссылка на страницу поддержки или просто кнопка перезагрузки страницы.

Когда нужно самим внедрять механизм

Платформенные компоненты, которые взаимодействуют с сервером (используют данные из SbisService) по умолчанию используют обработку результата ошибки с помощью стандартных обработчиков.

Однако бывают ситуации, когда механизм обработки ошибок нужно внедрить самому:

  1. Если вы разрабатываете собственный контрол.

    Для того, чтобы показать ошибку, вам следует использовать errorController и errorContainer. О том, как это сделать, читайте здесь.

  2. Если согласовано отображение ошибок, которое отличается от стандартных.

    В таком случае нужно использовать собственный обработчик ошибки и придерживаться правил отображения ошибок.

Правила отображения ошибок

  1. Следует формировать сообщение на основе кода ошибки, а не на основе данных из message или details.
  2. Запрещено показывать пользователю технические подробности ошибки.
  3. Ошибка должна отображаться максимально близко к области, в которой она возникла.
  4. Диалоговое окно по центру страницы можно выводить только тогда, когда нет области с компонентом, где можно отобразить шаблон ошибки. Это может быть, например, кнопка создания документа.

Создание ошибок на бизнес-логике

Важно

В Wasaby стандартные обработчики приложения одинаково реагируют как на HTTP код ошибки, полученный в ответе сервера, так и на error_code, который передается в RPCJSON ответе

Генерировать ошибки на бизнес-логике следует в соответствии со статьей.