errors

errors — библиотека структурированных ошибок для OneScript.

Она дополняет стандартную ИнформацияОбОшибке средствами для создания, распространения и диагностики ошибок: стабильными машинными кодами, структурированными данными, контекстом выполнения, подсказками и представлением цепочки причин.

С помощью библиотеки можно:

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

Навигация

• Установка
• Типовые задачи
• Публичный API
• Документация и примеры
• Разработка

Требования

• 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

API	Назначение
ФабрикаОшибок	Создание ошибок, контекстов и обёрток
СтандартныеОшибки	Готовые стандартные ошибки
КодыСтандартныхОшибок	Именованные стандартные машинные коды
ПостроителиСтандартныхОшибок	Обогащаемые стандартные ошибки
ПроверкаАргументов	Guard-проверки входных параметров
ДиагностикаОшибок	Поиск, разбор и представление ошибок
ВидыКадровОшибок	Строковые виды распознанных кадров
ПостроительОшибки	Поэтапное формирование ошибки
РазборОшибки	Сохранённый разбор цепочки причин
СнимокКадраОшибки	Безопасный снимок одного кадра цепочки
ВыборкаОшибок	Фильтрация и группировка ошибок

Документация и примеры

• Обзор документации
• Создание ошибок
• Стандартные ошибки
• Поиск в цепочке
• Представление ошибок
• Запускаемые примеры

Разработка

Установите зависимости:

opm install -l --dev

Запустите тесты:

oneunit execute

Соберите пакет:

opm build .