errors — библиотека структурированных ошибок для OneScript.
Она дополняет стандартную ИнформацияОбОшибке средствами для создания, распространения и диагностики ошибок:
стабильными машинными кодами, структурированными данными, контекстом выполнения, подсказками и представлением
цепочки причин.
С помощью библиотеки можно:
- обрабатывать ошибки по стабильному коду, не анализируя текст сообщения;
- использовать готовый каталог стандартных ошибок аргументов, операций, ресурсов, сети и данных;
- сохранять исходную причину при переходе между уровнями приложения;
- добавлять контекст без изменения кода исходной ошибки;
- прикреплять к ошибкам структурированные диагностические данные;
- находить нужные ошибки и группы ошибок во всей цепочке причин;
- формировать пользовательское и диагностическое представления;
- проверять контракты аргументов с помощью стандартных структурированных ошибок.
- OneScript 2.0.0 или новее;
- OPM для установки зависимостей и сборки пакета.
Установите пакет из OPM:
opm install errorsПосле установки подключите пакет в сценарии:
#Использовать errorsДля проекта с файлом packagedef добавьте зависимость:
Описание.ЗависитОт("errors");На границе приложения задайте стабильный предметный код, сохранив исходную ошибку в цепочке причин:
#Использовать errors
Попытка
Порт = Число("не число");
Исключение
ВызватьИсключение ФабрикаОшибок.Обернуть(
ИнформацияОбОшибке(),
"config.invalid_port",
"Некорректное значение порта"
);
КонецПопытки;Пользовательское представление содержит код и сообщение приложения:
config.invalid_port: Некорректное значение порта
Исходное исключение остаётся доступно через ДиагностикаОшибок.
Новая ошибка может содержать машинный код, сообщение и произвольные данные:
Ошибка = ФабрикаОшибок.Создать(
"validation.invalid_email",
"Некорректный адрес электронной почты",
Новый Структура("Адрес", Адрес)
);
ВызватьИсключение Ошибка;Код предназначен для программной обработки, а сообщение можно изменять и локализовывать независимо от него.
СтандартныеОшибки предоставляет именованные фабрики для распространённых сбоев.
Они возвращают готовую ИнформацияОбОшибке с локализованным сообщением и стабильным кодом:
Ошибка = СтандартныеОшибки.РесурсНеНайден("config.json");
ВызватьИсключение Ошибка;Такая ошибка имеет код resource.not_found. Для обработки без строковых литералов используйте
КодыСтандартныхОшибок:
Если ДиагностикаОшибок.Содержит(Ошибка, КодыСтандартныхОшибок.РесурсНеНайден()) Тогда
// Обработка отсутствующего ресурса
КонецЕсли;Если стандартную ошибку нужно дополнить данными, подсказкой или URL, используйте одноимённую функцию
ПостроителиСтандартныхОшибок:
Ошибка = ПостроителиСтандартныхОшибок.РесурсНеНайден("config.json")
.Данные("Каталог", КаталогНастроек)
.Подсказка("Проверьте путь к файлу")
.Построить();Полный каталог фабрик и рекомендации по выбору близких кодов приведены в руководстве по стандартным ошибкам.
Контекст описывает выполнявшуюся операцию, но сохраняет код исходной ошибки:
Ошибка = ФабрикаОшибок.ОбернутьКонтекстом(
Ошибка,
"Загрузка профиля пользователя",
Новый Структура("Идентификатор", ИдентификаторПользователя)
);Если на границе подсистемы нужен новый код, используйте ФабрикаОшибок.Обернуть().
ПостроительОшибки подходит для поэтапного добавления данных, подсказки, URL и причины:
Ошибка = Новый ПостроительОшибки("http.proxy_error", "Не удалось подключиться через прокси")
.Данные("Адрес", АдресПрокси)
.Подсказка("Проверьте адрес прокси и сетевое подключение")
.URL("https://example.org/errors/http-proxy-error")
.Причина(Причина)
.Построить();Пользовательское представление содержит код, сообщение, подсказку и URL:
http.proxy_error: Не удалось подключиться через прокси
Подсказка:
Проверьте адрес прокси и сетевое подключение
URL:
https://example.org/errors/http-proxy-error
Разбор один раз просматривает цепочку и предоставляет выборки ошибок, контекстов и снимков кадров:
Разбор = ДиагностикаОшибок.Разобрать(Ошибка);
Если Разбор.Ошибки().Содержит("network.timeout") Тогда
Сообщить(Разбор.ПользовательскоеПредставление());
КонецЕсли;Для простой проверки без сохранения разбора используйте фасад:
Если ДиагностикаОшибок.Содержит(Ошибка, "network.timeout") Тогда
Сообщить("Сервис не ответил вовремя");
КонецЕсли;ПроверкаАргументов выбрасывает стандартные структурированные ошибки при нарушении
контракта:
ПроверкаАргументов.ПроверитьТип("Порт", Порт, Тип("Число"));
ПроверкаАргументов.ПроверитьДиапазон("Порт", Порт, 1, 65535);Например, неверный тип приводит к ошибке со стабильным кодом argument.invalid_type.
По умолчанию свойство ИнформацияОбОшибке.Описание содержит пользовательское представление. Полную диагностику
можно включить без изменения кода приложения:
ONESCRIPT_ERRORS_FORMAT=diagnostic
Для выбора отдельных разделов используйте составной режим:
ONESCRIPT_ERRORS_FORMAT=sections
ONESCRIPT_ERRORS_SECTIONS=current,causes,stack
Диагностические форматы могут раскрывать данные ошибки и стек вызовов. Правила и список разделов приведены в руководстве по представлению ошибок.
| API | Назначение |
|---|---|
ФабрикаОшибок |
Создание ошибок, контекстов и обёрток |
СтандартныеОшибки |
Готовые стандартные ошибки |
КодыСтандартныхОшибок |
Именованные стандартные машинные коды |
ПостроителиСтандартныхОшибок |
Обогащаемые стандартные ошибки |
ПроверкаАргументов |
Guard-проверки входных параметров |
ДиагностикаОшибок |
Поиск, разбор и представление ошибок |
ВидыКадровОшибок |
Строковые виды распознанных кадров |
ПостроительОшибки |
Поэтапное формирование ошибки |
РазборОшибки |
Сохранённый разбор цепочки причин |
СнимокКадраОшибки |
Безопасный снимок одного кадра цепочки |
ВыборкаОшибок |
Фильтрация и группировка ошибок |
- Обзор документации
- Создание ошибок
- Стандартные ошибки
- Поиск в цепочке
- Представление ошибок
- Запускаемые примеры
Установите зависимости:
opm install -l --devЗапустите тесты:
oneunit executeСоберите пакет:
opm build .