Лучшая практика обработки ошибок и исключений для C# API

Question

Я пишу простой и маленький API, который запускает кучу веб-запросов и работает с ответами. Пользователь только вызывает метод и обеспечивает обратный вызов, где он может работать с данными, что-то вроде следующего:

var someData = new SomeData(); 
API.GetSomeDataFromTheWeb((d)=>{someData = d;}); 

Для каждого ответа я реализовал конкретный класс проведения данных. Кроме того, я хочу, чтобы пользователь самостоятельно обрабатывал любую возникающую ошибку и исключение. Это может быть WebException, исключение JsonSerializationException или любая пользовательская ошибка, которая может произойти. Как передать эти разные исключения и ошибки пользователю, который затем может извлечь из него необходимую информацию для обработки этих исключений и ошибок?

Answer 1

библиотека (или API) разработка имеет дело с немного обработки исключений по-другому от того, как его обрабатываются в разработке приложений -

1. Как вы уже писали в своем ответе, вы хотели бы, чтобы пользователь принял решение. Это важно, так как библиотека может использоваться в нескольких сценариях &, что невозможно предсказать каждую ситуацию, когда библиотека будет использоваться и иметь политику на месте. Это должно быть приложение, которое знает контекст & может иметь политику для него.

2. Проверьте аргументы, переданные вашим API (приложением). Выбросьте исключение, если они неверны.

3. Государство - Откат частично выполненной операции

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

   В таком случае желательно вернуться в исходное состояние и сообщить вызывающей стороне об ошибке.

   Пример

   try 
   { 
       // Database operations starts 
       // perform database operations 
       transaction.Commit(); 
   } 
   catch // anything goes wrong 
   { 
       // rollback 
       transaction.RollBack(); 
   
       // Rethowing the *Same* exception 
       throw; 
   } 
   

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

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

В таком случае может быть полезно поймать один тип &, выкинуть еще одно новое исключение.

try 
{ 
    // Database operations starts 
    // perform database operations 
    transaction.Commit(); 
} 
catch (DataException ex) 
{ 
    // rollback 
    transaction.RollBack(); 

    // I'm keeping the original error but lying about the stack stace 
    throw new InvalidOperationException(name, ex); 
} 

Теперь, позвольте мне рассказать о том, как создавать исключения.

Выбросить исключение, если API не может выполнить свою задачу полностью.Несколько вопросов, которые следует иметь в виду:

1. Выберите тип (тип, основанный на исключении), который наиболее значим. Это даст возможность коду в стеке вызовов надлежащим образом обрабатывать конкретный случай.

   В случае отсутствия исключения .Net, которое соответствует точной семантике, создайте пользовательский.

2. Если вы создаете иерархию пользовательских исключений. Лучше держать иерархию мелкой. Чтобы создать несколько базовых классов, поскольку базовые классы действуют как способ обработки всех ошибок как одна ошибка. В тех же строках никогда не бросайте System.Exception

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

Edit 1:

/// <summary> 
    /// Reads an Employee by its ID 
    /// </summary> 
    /// <param name="ID">Unique identifier</param> 
    /// <param name="dbContext">Contains inforamtion about how to connect to database</param> 
    /// <returns>Employee linked to ID; Null if no record is linked</returns> 
    public Employee ReadEmployee(string ID, IDataBaseContext dbContext) 
    { 
     if(string.IsNullOrWhiteSpace(ID)) 
      throw new ArgumentException("Unique id must be supplied to read the record"); 

     // Validate if the database can be accessed using db Context, if not throw another exception. 
     // Because it's preventing the API from doing its job 

     // read and return the record 
    } 

Я воскрешу ошибку только тогда, когда я не могу выполнить операцию чтения. Если после чтения данных возвращается null, все в порядке, API выполнил свою работу.

Что делать с нулевым значением, это то, что я разрешу вызывающему абоненту решить.

Возможно, в диалоговом окне поиска будет отображаться пустой результат при возврате null.

Но это может быть исключение в другом деловом случае.

Answer 2

Используйте throw WebException("your message") вот так. Используйте любое исключение, которое вы хотите. Пользователь должен будет поймать его и получить сообщение, используя ex.Message свойство (где ex это имя исключения)