Помилки

Коли ваш код викидає помилку, ця помилка зупинить дію та птаха і відобразиться користувачу на сторінці польотів.

Існує 5 різних типів помилок, які можуть відображатися на сторінці польотів. 2 типи помилок викидаються ядром Blackbird, інші 3 можуть бути викинуті кодом додатка. Ми розглянемо кожну з цих помилок тут і як їх викидати.

1. Помилка конфігурації

Призначення цієї помилки — повідомити користувача, що вони допустили помилку і тільки вони можуть її вирішити. Це зазвичай відбувається при неправильно налаштованих змінних, значеннях або середовищах. Тому цей тип помилки називається помилкою конфігурації. Прикладами помилок конфігурації є:

• Надсилання неправильного типу файлу.
• Надсилання значень, які виглядають неправильними при аналізі.
• Спроба перевищити ліміти, які встановлені підключеним додатком.
• Коли підключений додаток вказує на проблему з автентифікацією або авторизацією (401).
• Створення, наприклад, проєктів у якійсь неприпустимій конфігурації.

Коли викидається помилка конфігурації, опис повинен вказувати користувачу, як вирішити проблему.

Помилку конфігурації можна викинути, викидаючи виняток класу PluginMisconfigurationException. Приклад, взятий з додатка memoQ, показано нижче:

try
{
    var result = projectService.Service.CreateProjectFromTemplate(newProject);
    var response = projectService.Service.GetProject(result.ProjectGuid);

    return new(response);

} catch (System.ServiceModel.FaultException ex)
{
    if (ex.Message == "Message.ResourceNotFound.ProjectTemplate")
        throw new PluginMisconfigurationException("The selected project template does not exist. Please select a different template.");
    else if (ex.Message == "An online project with the same name already exists.")
        throw new PluginMisconfigurationException("An online project with the same name already exists. Please configure a unique name.");
    throw;
}

Примітка: Ця помилка також зазвичай викидається, коли ви перевіряєте, чи правильні вхідні параметри.

2. Додаток не відповідає

Призначення цієї помилки — повідомити користувача, що підключений додаток має проблеми, з якими ні ви (розробник додатка), ні користувач нічого не можете зробити. Це зазвичай трапляється, коли додаток викидає несподівану проблему (500), або коли API викидає помилку, яка призначена для користувача, а не для розробника додатка. Прикладами є:

• Коли код помилки від запиту API дорівнює 500 (як зазначено раніше).
• Коли підключений додаток не працює (недоступний).
• Коли досягнуто певного обмеження швидкості (що не може бути вирішено логікою очікування та повторних спроб у додатку).

Помилку “додаток не відповідає” можна викинути за допомогою класу PluginApplicationException.

Примітка: Ця помилка зазвичай може оброблятися в базовому класі rest клієнта, який обробляє більшість викликів API.

3. Несподівана проблема додатка

Усі інші помилки, які викидаються вашим додатком, з’являються як несподівані помилки. Мета полягає в мінімізації кількості несподіваних помилок. Якщо виникає несподівана помилка, відповідальністю розробника додатка є або обробити помилку в коді, або викинути будь-який з інших 2 типів помилок.

Коротко:

• Якщо ні користувач, ні розробник додатка нічого не можуть зробити -> PluginApplicationException.
• Якщо користувач повинен щось зробити -> PluginMisconfigurationException.
• Якщо розробник додатка повинен щось зробити -> будь-який інший виняток.

Ще кілька рекомендацій:

• Перехоплюйте стандартні помилки HTTP. Наприклад, 401 Unauthorized повинен інформувати користувача, що його облікові дані можуть бути неправильними.
• Якщо кінцеві точки надають додаткову інформацію у своїх тілах (можливо, у якомусь json), ця інформація повинна передаватися користувачу, замість простого “400 bad request”.
• Помилки часу виконання слід уникати за будь-яку ціну. Перевіряйте на нульові посилання, порожні масиви тощо. У вашому IDE не повинно бути ніяких попереджень.
• Не забудьте перевірити, чи правильно працює ваш аналіз JSON, і повідомити користувача, якщо тут є проблема.
• Заздалегідь перевірте, чи правильні вхідні параметри, які використовує користувач. Якщо вони неправильні, повідомте користувача, як їх виправити.