Классификатор ошибок

Обзор

XrplErrorClassifier преобразует исключения и ответы об ошибках XRPL в нормализованный объект XrplErrorInfo, который можно использовать в коде приложения, логах, телеметрии или для отображения ошибок пользователю.

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

Связанный код:

• Xrpl/Client/Exceptions/XrplErrorClassifier.cs
• Xrpl/Client/Exceptions/XrplErrorInfo.cs
• Xrpl/Models/Subscriptions/ErrorResponse.cs

Доступные перегрузки

XrplErrorClassifier предоставляет три перегрузки:

Classify(Exception exception)

Используйте эту перегрузку, когда блок catch обрабатывает любой тип исключения. Если исключение является RippledException, классификатор делегирует обработку XRPL-специфичному пути. В противном случае возвращается XrplErrorInfo с Category = Unknown и Subject = Unknown.

Это рекомендуемая перегрузка по умолчанию для большинства кода приложений, так как она хорошо работает с единым блоком catch (Exception e).

Classify(RippledException exception)

Используйте эту перегрузку, когда вызывающий код уже знает, что ошибка пришла из ответа rippled со status = "error". Классификатор читает встроенный ErrorResponse и перенаправляет к перегрузке на основе ответа.

Classify(ErrorResponse response)

Используйте эту перегрузку, когда ErrorResponse уже доступен без прохождения через обработку исключений. Этот путь маппит значения error XRPL в нормализованный XrplErrorInfo.

Как работает классификация

Для обычного Exception

Для не-RippledException классификатор не пытается определить XRPL-специфичную семантику. Он возвращает обобщённый XrplErrorInfo:

• RawError заполняется из имени типа исключения
• RawErrorMessage заполняется из сообщения исключения
• Category и Subject остаются Unknown
• Title устанавливается в internal error
• UserMessage содержит оригинальное сообщение исключения

Такое поведение сохраняет видимость не-XRPL ошибок, не притворяясь, что библиотека понимает их бизнес-смысл.

Для RippledException и ErrorResponse

Для ошибок, пришедших от rippled, классификатор читает payload ошибки XRPL и маппит:

• error
• error_code
• error_message
• метаданные запроса
• предупреждения

в единый экземпляр XrplErrorInfo.

Результирующий объект предоставляет стабильную интерпретацию: некорректный ввод, отсутствующее поле, объект не найден, проблема состояния леджера, неподдерживаемая функция или повторяемое серверное условие.

Поля XrplErrorInfo

XrplErrorInfo содержит как сырые транспортные данные, так и нормализованные метаданные:

• RawError Оригинальный токен ошибки или имя типа исключения для не-XRPL исключений.

• RawErrorCode Необязательный числовой или текстовый код, предоставленный rippled.

• RawErrorMessage Оригинальное читаемое сообщение об ошибке от сервера или исключения.

• Category Высокоуровневый класс ошибки: некорректный ввод, не найдено, ограничение частоты запросов или неизвестная ошибка.

• Subject Основная область, затронутая ошибкой, например: запрос, аккаунт, леджер, адрес или транзакция.

• Title Краткий нормализованный заголовок, подходящий для логов или UI.

• UserMessage Читаемое объяснение, предназначенное для отображения на стороне вызывающего кода.

• IsRetryable Указывает, имеет ли смысл логика повторных попыток.

• IsUserFixable Указывает, может ли вызывающий код исправить данные запроса и повторить попытку.

• Command Имя команды XRPL, когда его можно извлечь из payload запроса.

• FieldName Имя поля запроса, наиболее непосредственно связанного с ошибкой, когда известно.

• FieldValue Значение, связанное с проблемным полем, когда его можно безопасно извлечь.

• Warnings Токены предупреждений, содержащиеся в ответе, если присутствуют.

Рекомендуемый паттерн использования

В большинстве случаев достаточно одного блока catch:

try
{
    var info = await client.AccountInfo(new("rKeiNfRJcDBUhu4rcjQjGLWqa4"));
}
catch (Exception e)
{
    XrplErrorInfo errInfo = XrplErrorClassifier.Classify(e);
}

Этот паттерн упрощает обработку ошибок, сохраняя XRPL-специфичную классификацию, когда исключение является RippledException.

Если вызывающему коду нужна специальная обработка для RippledException, он может перехватить этот тип отдельно. Однако это не требуется просто для получения XrplErrorInfo.

Пример: обычное исключение

try
{
    throw new NotImplementedException("Test exception");
}
catch (Exception e)
{
    XrplErrorInfo errInfo = XrplErrorClassifier.Classify(e);
}

В этом примере классификатор возвращает обобщённую нормализованную структуру для не-XRPL исключения.

Пример: ошибка вызова XRPL

try
{
    var info = await client.AccountInfo(new("rKeiNfRJcDBUhu4rcjQjGLWqa4"));
}
catch (Exception e)
{
    XrplErrorInfo errInfo = XrplErrorClassifier.Classify(e);
}

Если исходная ошибка — это ответ об ошибке rippled, тот же блок catch всё равно выдаёт XRPL-специфичную классификацию.

Когда перехватывать RippledException отдельно

Используйте отдельный catch (RippledException e) только когда вызывающему коду явно нужен:

• прямой доступ к e.Response
• другой поток управления для ошибок XRPL RPC по сравнению с инфраструктурными исключениями
• кастомное логирование сырых payload ответов до нормализации

В остальных случаях catch (Exception e) с последующим XrplErrorClassifier.Classify(e) обычно достаточно.