Дизайн клиента API. Как лучше возвращать ошибки от API?

Question

[Станислав Гамаюнов]

Приветствую.


Есть вопрос по дизайну работы с ошибками в клиенте некоего API. Как лучше, красивее, проще в работе, более true, более модно-стильно-молодёжно, как вам, разработчикам больше понравилось бы?

$result = $apiFacade->getData();
if ($result->isSuccess()) {
    echo 'success: ' . $result->getData() . PHP_EOL;
} else {
    if (ApiClient::ERROR_NOT_ENOUGHT_UNITS === $result->getError()->getCode()) {
        // some actions for this error
    } elseif (ApiClient::ERROR_OBJECT_NOT_EXISTS === $result->getError()->getCode()) {
        // some actions for this error
    } else {
        // some actions for other errors
    }
}

try {
    $result = $apiFacade->getData();
} catch (ApiNotEnoughtUnitsException $exception) {
    // $exception->getCode() вернёт код ошибки
    // $exception->getMessage() вернёт текст ошибки
    // some actions for this error
} catch (ApiObjectNotExistsException $exception) {
    // some actions for this error
} catch (ApiException $exception) {
    // some actions for other errors
}
echo 'success: ' . $result . PHP_EOL;

Речь здесь идёт об ошибках, получаемых в ответе API.


На мой взгляд, бросаться исключениями — хорошо. Если где-то в приложении я не обработаю исключение, его поймает глобальный exception_handler и я об этом узнаю из логов или оповещений. С другой стороны, существует вероятность возникновения ситуации, когда ошибка API будет ожидаемым результатом и мне нужно будет получить, какие-то подробности об этой ошибке. В таком случае, в клиенте мне нужно будет создать экземпляр исключения, записать в его поля эти самые подробности и только потом выбросить его. Не слишком мутно?


Кто сталкивался, ещё какие есть плюсы и минусы у этих подходов?

Answer 1

[Андрей Апанасик]

Исключения и какой-нибудь глобальный обработчик.

p.s. if на switch бы заменить)

switch($result->getError()->getCode()) {
      case  ApiClient::ERROR_NOT_ENOUGHT_UNITS:
        //...
        break;
      case ApiClient::ERROR_OBJECT_NOT_EXISTS:
        //...
        break;
      default:
        //...
        break;
}

Comments

[Станислав Гамаюнов]

Да, так более читаемо.
Спасибо.

Answer 2

[EugeneOZ]

Бросаться исключениями — плохо, потому что незначительная и никого не интересующая 404 при удалении объекта может оборвать стек выполнения и выдать пользователю бээээ на экран. Исключениями бросаются в языках со строгой типизацией, потому что там нельзя «вдруг» вернуть false вместо ожидаемого типа. В Go эта проблема решена тем, что там можно вернуть несколько значений.

Comments

[Станислав Гамаюнов]

В моём случае никакого пользователя не существует, существует только скрипт. Но это дела это, конечно же, не меняет.

Важнее то, что гипотетический пользователь получит «бээээ» на экран только тогда, когда я (или другой разработчик) не написал обработку исключения.

Грубо говоря, моя задача состоит в том, что бы правильно обработать возникающие при запросах ошибки. А вопрос состоит в том, какой способ возврата этих ошибок выбрать.

[Stdit]

Поскольку «какая-нибудь ошибка», о которой забыл разработчик, будет являться наследником ApiException, то она поймается так или иначе на нижнем уровне, и «бээ» не будет. А вот писать после кажого вызова «if ($result !== false)» надоест уже после первой недели работы с кодом.

[EugeneOZ]

Только лишь от того, что эксепшен наследуется от кастомного класса, никакой гарантии перехвата не появляется.
Писать if ($result) не сложнее, чем писать try catch.

[Станислав Гамаюнов]

Если у нас есть код

} catch (ApiException $exception) {
    // some actions for other errors
}

то гарантия перехвата исключения-наследника класса ApiException как бы есть.

Если исключение будет брошено не кодом клиента, а кодом, например обёртки над cURL, то в коде клиента API оно должно быть поймано и преобразовано в ApiTransportException, например, и затем выброшено дальше и затем поймано с помощью вышеупомянутого кода.

Или я что-то упускаю?

[EugeneOZ]

Хех, «если у нас есть код» можно сказать вообще про все исключения.
Как программист узнает, что внутри кода клиента что-то там собирается бросить исключение? Какого класса будет это исключение — где об этом написано? Зачем ему держать это в голове?

[Станислав Гамаюнов]

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

if (in_array($result->getError()->getCode(), [ApiClient::ERROR_NOT_ENOUGHT_UNITS, ApiClient::ERROR_DAYLIMIT_EXCEEDED])) {
    // some actions for this errors
} elseif (ApiClient::ERROR_OBJECT_NOT_EXISTS === $result->getError()->getCode()) {
    // some actions for this error
} else {
    // some actions for other errors
}

Но это уже что-то не то :)

А в случае с исключениями у нас для этого будет иерархия.

[EugeneOZ]

Вам не нужен ответ на вопрос, спорьте сами с собой, не просите других мешать вам спорить с самим собой.

[Станислав Гамаюнов]

Как программист узнает, что внутри кода клиента что-то там собирается бросить исключение? Какого класса будет это исключение — где об этом написано? Зачем ему держать это в голове?

Я полагаю, у программиста есть очевидные причины ожидать исключения от библиотеки, с которой он работает. Ровно как и ошибки в любом другом виде. Речь только о том, удобнее ли исключения для обработки или нет.

Вы ведь сейчас не пытаетесь сказать, что использовать исключения это плохо потому, что пропущенные они могут прерывать выполнение скрипта?

[EugeneOZ]

«Очевидные причины» это довольно забавный и универсальный ответ :)
По очевидным причинам бесполезно Вам тут что-либо отвечать, Вы уже упёрлись в исключения и чего-то хотите услышать ещё :)
Всего доброго.

[Станислав Гамаюнов]

И вам счастья.

Answer 3

[Stdit]

Я сталкивался. Когда-то тоже ломал голову над этим вопросом, и не нашел однозначного ответа, потому что всякий способ имеет как сильные, так и слабые стороны. Пробовал разные варианты, включая велосипеды, возврат кода ошибки и даже возврат ассоциативных массивов типа {status, result}. Многие не рекомендовали бросать исключения, аргументируя тем, что исключение должно оставаться исключением, а не становиться бизнес-логикой (в том числе, когда параметры исключения передаются в его конструктор при его бросании, в зависимости от типа исключения). В целом же, на практике оказалось, что это достаточно удобно, уменьшает количество условий, проверок, код становится короче и читается проще, багов становится меньше. На скорости работы почти не отражается. В нескольких поздних проектах на php обработка ошибок модели была сделана похожим образом. При реализации rest-api на эту модель достаточно просто создаются контроллеры. Возможно у кого-то есть другой опыт и он поделится негативными впечатлениями от исключений, но после выбора такого подхода мне жалеть не приходилось. Так что, как разработчику, такой способ контроля ошибок вполне бы подошел.

Comments

[Станислав Гамаюнов]

Спасибо, хороший ответ.

[Станислав Гамаюнов]

Только что пришла в голову мысль об ещё одном преимуществе использования исключений. Оно заключается в использовании иерархии, примерно как SPL Exceptions. Можно будет отлавливать схожие ошибки, перехватывая например ApiInvalidArgumentException, наследниками которого являются ApiInvalidObjectIdFormatException и т.д.

Осталось только описать иерархию и сгенерировать набор исключений из списка ошибок API.

[Stdit]

Ради этой иерархии весь сырбор и затевается. Так, например, PDO или Memcached могут бросать свои исключения, и их можно ловить отдельно и что-то с ними делать, например писать в лог. Но слишком большую иерархию делать нет смысла — будет хаос из классов и рутина в поддержке этого ансамбля.

[Станислав Гамаюнов]

Точно. В работе клиента API сторонним может быть разве что исключение от транспорта (обёртки cURL, например). Такие исключения, я считаю, должны ловиться внутри клиента и там же обрабатываться (например повторить запрос через секунду, если сервис был временно недоступен), либо преобразовываться в ApiTransportException, например, и выбрасываться дальше.

Answer 4

[anitspam]

Если ошибка неустранимая силами клиента и он завершает работу после возникновения такой ошибки, то это исключительная ситуация, работаем с исключениями, пользователю показываем «Попробуйте позже», самому API сообщаем, что «я завершился» (если этому API надо что-нибудь сообщать).

Если клиент предполагает работать дальше (не хватает денег на постройку? пользователю показываем «Не хватает денег», API сообщаем «ок, не хватает, так хватает», клиент продолжает работать с текущим количеством денег), то это не исключение, а нормальная работа.

Comments

[Станислав Гамаюнов]

Звучит очень убедительно. Кажется, такой подход самый верный идеологически.
Спасибо за ответ.

Answer 5

[Сергей]

Может я ошибаюсь, но в Вашем примере все зависит от

$apiFacade->getData()

Если в этом методе может быть брошено исключение, то нужно их обрабатывать. Если ошибка и код всегда возвращаются как результат работы метода getData, то нужно использовать первый вариант. Если getData бросить исключение, то оно и в первом примере тоже будет. Только Вы его не обработали.
То есть обработка ошибок АПИ в клиенте зависит от того, в каком виде АПИ возвращает ошибки в клиент.

Comments

[Станислав Гамаюнов]

Вот о том, как $apiFacade->getData() должен возвращать ошибки и речь.

[Сергей]

Тогда вопрос я бы изменил на 'В каком виде АПИ должно возвращать ошибки?'

Исключения так называются, так как возникают в исключительных ситуациях, типа неожиданный разрыв соединения, отсутствие файла при очередной попытке считать с него данные, когда только что он был доступен и т.д. Такие вещи желательно обрабатывать на уровне АПИ и возвращать в виде обычного ответа с флагом error => TRUE. Для обработки таких ошибок должна быть отдельная функция. Тогда получится что типа

$result = $apiFacade->getData();
if ($result->isSuccess()) {
    echo 'success: ' . $result->getData() . PHP_EOL;
} else 
    echo errorHandler($result);

Теперь 2й вариант более громоздкий и менее правильный. Всю работу за юзера должен делать программист. В данном случае автор клиента — юзер, автор АПИ — программист

[Станислав Гамаюнов]

Тогда вопрос я бы изменил на 'В каком виде АПИ должно возвращать ошибки?'

Речь всё же не о том, как API должен возвращать ошибки, а о том, как клиент API должен возвращать ошибки приложению.

Исключения так называются, так как возникают в исключительных ситуациях, типа неожиданный разрыв соединения, отсутствие файла при очередной попытке считать с него данные, когда только что он был доступен и т.д. Такие вещи желательно обрабатывать на уровне АПИ и возвращать в виде обычного ответа с флагом error => TRUE.

Опять же, вопрос был про работу клиента API. Тот API, для которого я пишу клиент мне неподвластен. И да, он и возвращает мне ответ с кодом ошибки. Но дальше клиент должен вернуть ответ приложению так, что бы приложению было удобно его обрабатывать. И применять различную логику при обработке разных ошибок прямо рядом с выполнением запроса, а не в глобальной странной функции errorHandler().

За ответ, конечно, спасибо. Но попробуйте перечитать вопрос, что бы лучше понять его.

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

www.php.net/manual/ru/spl.exceptions.php

[EugeneOZ]

Автор хочет эксепшены и пытается подавить голос разума, топик он создал, чтобы его уговорили использовать эксепшены. Не мешайте человеку :)
Я разделяю Вашу точку зрения :)