Skip to content

ПредставлениеОшибок.md

Latest commit

 

History

History
157 lines (114 loc) · 10.4 KB

ПредставлениеОшибок.md

File metadata and controls

157 lines (114 loc) · 10.4 KB
Raw

Представление ошибок

Созданная фабрикой или построителем ИнформацияОбОшибке содержит в свойстве Описание пользовательское представление текущего кадра. Для ошибки оно включает её код и сообщение, а для контекста - его сообщение вместе с кодом и сообщением эффективной ошибки. Подсказка и URL берутся только из текущего кадра. Причина хранится отдельно в свойстве Причина. Для полной технической диагностики всей цепочки используйте ДиагностическоеПредставление().

Краткое представление

Для компактного вывода вызовите ДиагностикаОшибок.КраткоеПредставление(). Метод выводит код и сообщение текущей ошибки. Для текущего контекста или внешней обёртки он дополняет их сообщение кодом и сообщением эффективной ошибки, не включая промежуточные кадры:

Сообщить(ДиагностикаОшибок.КраткоеПредставление(Ошибка));
profile.load_failed: Загрузка профиля пользователя -> Не удалось загрузить профиль

Пользовательское представление

ПользовательскоеПредставление() предназначено для пользователей и внешних систем. Оно использует ту же информативную строку, что и краткое представление, а подсказку и URL выводит только для текущего кадра:

Сообщить(ДиагностикаОшибок.ПользовательскоеПредставление(Ошибка));
config.load_failed: Не удалось загрузить конфигурацию

Подсказка:
  Проверьте настройки подключения

URL:
  https://example.org/errors/config-load-failed

Диагностическое представление

ДиагностическоеПредставление() возвращает технический отчёт для логов и отладки. Внешний кадр выводится первым, все промежуточные причины объединяются в блок Причина, раскрываются Данные и добавляется общий стек вызовов первого физического кадра:

Сообщить(ДиагностикаОшибок.ДиагностическоеПредставление(Ошибка));
profile.load_failed: Не удалось загрузить профиль

Данные:
  Идентификатор: 42

Причина:
  1: Сервер закрыл соединение
  2: network.timeout: Превышено время ожидания

Подсказка:
  Повторите запрос

Стек вызовов:
  1: ЗагрузитьПрофиль:42
  2: ЗапуститьПриложение:10

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

Если для одной ошибки нужны несколько представлений или другие результаты разбора, создайте РазборОшибки один раз и вызывайте соответствующие методы у него.

Формат необработанных исключений

Переменная среды ONESCRIPT_ERRORS_FORMAT меняет свойство ИнформацияОбОшибке.Описание у новых ошибок библиотеки. Она читается при создании каждого кадра и поддерживает три значения:

  • user - пользовательское представление текущего кадра; используется по умолчанию;
  • diagnostic - полный диагностический отчёт всей доступной цепочки;
  • sections - отчёт из разделов, заданных в ONESCRIPT_ERRORS_SECTIONS.

Значения и идентификаторы разделов не зависят от регистра, пробелы по краям игнорируются. Неизвестный формат, пустой список или неизвестный раздел безопасно переключают вывод на user.

Для полного отчёта:

ONESCRIPT_ERRORS_FORMAT=diagnostic

Для составного отчёта укажите формат и список разделов через запятую:

ONESCRIPT_ERRORS_FORMAT=sections
ONESCRIPT_ERRORS_SECTIONS=urls,current,causes,stack

Поддерживаются следующие разделы:

  • current - текущая группа с контекстами, данными и местом;
  • causes - группы причин с их контекстами, данными и местом;
  • hints - подсказки;
  • urls - ссылки на документацию;
  • uninspected_contexts - контексты без просмотренной причины в усечённой цепочке;
  • truncation - отметка об усечении цепочки;
  • stack - стек вызовов.

Порядок идентификаторов определяет порядок разделов. Пустые элементы пропускаются, повторный идентификатор выводится один раз, отсутствующий у конкретной ошибки раздел не выводится. ONESCRIPT_ERRORS_SECTIONS игнорируется в режимах user и diagnostic.

Если ни один выбранный раздел не содержит данных, свойство Описание будет пустым. Библиотека не добавляет current автоматически и не переключается на user: состав отчёта в режиме sections полностью задаёт пользователь.

Настройка не меняет результаты явных методов КраткоеПредставление(), ПользовательскоеПредставление() и ДиагностическоеПредставление(). Она также не влияет на нативные исключения OneScript и ошибки других библиотек.

Свойство Описание вычисляется при создании ошибки. Если OneScript добавляет стек только при последующем выбрасывании, раздел stack не может попасть в уже созданную строку задним числом. Он содержит только стек, доступный на момент создания. После перехвата ошибки для актуального стека используйте явный метод ДиагностическоеПредставление().

Режимы diagnostic и sections могут раскрывать пользовательские Данные, места возникновения и стек вызовов. Не включайте их там, где диагностируемые данные могут содержать пароли, токены и другие секреты.

Структурированное представление

Разбор.ВСтруктуру() возвращает данные цепочки без объектов ИнформацияОбОшибке, поэтому результат можно передать сериализатору или обработать программно:

Разбор = ДиагностикаОшибок.Разобрать(Ошибка);
СтруктураОшибки = Разбор.ВСтруктуру();

В результате находятся:

  • Цепочка - физическая цепочка от внешнего кадра к корневому;
  • ЭффективнаяОшибка - первый классифицированный кадр цепочки;
  • ЦепочкаУсечена - признак наличия непросмотренной причины;
  • Стек - стек вызовов внешнего физического кадра.

Каждый кадр цепочки содержит вид, код, сообщение, данные, подсказку, URL и место возникновения. Кадры общего стека преобразуются в структуры с полями ИмяМодуля и НомерСтроки.

Значение Данные передаётся по ссылке, без копирования и дополнительного преобразования. Поэтому изменения исходного мутабельного объекта данных видны и в ранее сформированном структурированном представлении. Библиотека намеренно не зависит от конкретного формата обмена: при необходимости полученную структуру можно сериализовать в JSON библиотекой jason или любым другим сериализатором.