Как правильно возвращать ошибки в своем API, Laravel?

Question

[LNK]

Приветствую. Я возвращаю ошибки в своём API в таком формате:

{
    "error" : {
        "error_code" : 1,
        "error_details" : { ... }
    }
}

Ну и возвращается соответствующий HTTP код ошибки. Содержимое error_details варьируется в зависимости от метода API и ошибки. Например, при ошибке валидации поле error_details будет содержать что-то в этом роде:

{
    "count" => "The count field must be an integer."
}

Это вообще как, нормальный подход?
Главный вопрос в том, как именно и где возвращать ошибки? То есть я, конечно, могу вручную делать return в каждом методе своего API, но это не выглядит правильным, к тому же если структура изменится, мне придется менять весь свой код. Может стоит использовать обработчик исключений? В общем хотелось бы услышать ваши советы и опыт по этой теме.

Comments

[Кирилл Мокевнин]

Посмотрите jsonapi.org

[LNK]

Kirill Mokevnin, смотрел уже, но это скорее как стандарт можно использовать, там нет ответов на мои вопросы.

[Кирилл Мокевнин]

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

Answer 1

[Алексей Николаев]

могу вручную делать return в каждом методе своего API, но это не выглядит правильным

Почему? Это нормальная практика. Каждый метод - это часть контроллера, а контроллер должен возвращать ответ. Ответ в Laravel должен быть инстансом Response (массив автоматически конвертируется в него).

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

Для таких случаев Лара предоставляет возможность создать свой собственный тип ответа, например, ApiResponse. Соответственно, после создания будете вызывать в коде как-то так:
return response()->api($code, $data);
Все форматирование будете делать в классе ApiResponse.

Собственно, чтобы создать, регистрируете в сервис-провайдере новый тип response.

Response::macro('api', function ($code, $data) {
    return new ApiResponse($code, $data);
});

Comments

[Wentixon]

Опять худший ответ набрал большее количество голосов м выбрал лучшим! На секундочку, есть полно случаев типовых, к примеру выдача 404 при отсутствии записей. Вы думаете что норм в каждом контроллере проверять существуют ли записи и генерировать ответ? Это нужно делать, как написали практически все снизу в обработчике исключений

[Алексей Николаев]

Wentixon, ну вообще-то, если пойти дальше, то можно вынести логику проверки и генерацию кода в ApiResponse. Что-то, возможно, имеет смысл вынести в посредника. То, что я написал - классическая, проверенная временем практика, в которой нет ничего плохого.

Про типовые ответы я ничего не написал, потому что они и так автоматически выбросятся в очень большом ряде случаев, еще до обращения к api. Я не знаю, что у автора в $data. Возможно, что ему не нужно возвращать eloquent модель, чтобы она сразу сконвертилась в нужный response, а может, он хочет единого и унифицированного механизма обработки ответов. Может, ему нужно, чтобы статус был 200, но свойство status было error.

Для таких случаев создать новый тип response - отличный вариант.

А вот кидать http-коды ответов через исключения, которые не предназначены для того, чтобы в них кидали http-коды, извращение. Исключение происходит тогда, когда в приложении происходит исключительная ситуация. Возврат кода, отличного от 200, или пустой коллекции, исключениями не являются. Эдак можно вообще return упразднить, все через исключения выкидывать, а возвращать в одном месте.

[Wentixon]

Алексей Николаев, так это и нормально, когда есть глобальный обработчик, который все ловит и реагирует на них, при чем в зависимости от типа взаимодействия (консоль, апи) по разному. Вы же в курсе про метод firstOrFail например.. Так вот он именно так и работает. Выбрасывает исключение, оно перехватывается хэндлером и юзер получает 404 страницу.

Таким образом, логика обработки такого события вынесена в одно место.

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

Answer 2

[Игорь Русинов]

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

• Если вы используете встроенную валидацию, то Laravel автоматически возвращает HTTP 422 и json массив с ошибками.
  
• Если для получения модели вы используете метод Model::findOrFail(), то Laravel автоматически выбрасывает ModelNotFoundException и автоматически генерирует для него HTTP 404 ответ.
  
• Laravel автоматически возвращает корректный HTTP 4xx ответ, если пользователь не авторизован.
  
• В остальных случаях можно возвращать ошибки вручную, с использованием хелперов, например: abort(403, 'You don\'t have access to do that');
  

Таким образом, вручную ошибки возвращать тоже придется, но в большинстве случаев Laravel сделает это за вас.

Answer 3

[Alex Wells]

Единого формата ответа с ошибками от http api не существует. Есть некие претенденты, но это такое. Возвращать - не надо, надо кидать эксепшены и обрабатывать в хендлере. Лучше - если будет какой-то один базовый class AppException, с помощью которого вы сможете контроллировать соответствие ваших же кастомных ошибок на наличие нужных полей (кода, http кода, сообщения, мета инфа). Как делаю я (пока что прокатывает):
1) с сервера отдаю к каждой уникальной ошибке (например той, что выходит за рамки валидатора) свой код ошибки, как с error_code. У тривиальных ошибок (типа not found или validation) - их нет, так как на нее указывает http код (типа 404 и 422).
2) так же к каждому эксепшену в коде пишу месседж, который так же отдаю в ответе во время разработки. На продакшене вырубаю дебаг и меседж пропадает из ответа от сервера, остается http код и "свой код".

Если говорить только об validation error, то делаю как с error_details, а потом фронтер разбирается с этим так, как оно вписывается в дизайн.

Answer 4

[Сергей Кривошеев]

Я возвращаю всегда через throw exception универсальный механизм и для своих ошибок и вдруг где пропущу исключение, оно будет обработано фронтендом соответственно.
Также для валидации есть свои exception которые будут с вашими ошибками идти в одном формате(два раза не делать обработку) ну и работают колбэки axios и тд, т.к. Http кодом можно в exception управлять

Answer 5

[motomac]

Если используете OAuth 2.0, можно ошибки возвращать в том же формате, дополнив своими кастомными секциями:

{
  "error": "spaceshuttle_crash",
  "error_description": "Houston, we have problems",
  "error_uri": "https://nasa.com/error.html",
  "my_custom_error_code": 42
}