API RESTful - Обработка ошибок

При обработке запроса API RESTful, если в запросе пользователя произошла ошибка или что-то неожиданное произошло на сервере, вы можете просто отправить исключение, чтобы уведомить пользователя о том, что что-то пошло не так. Если вы можете определить причину ошибки (например, запрошенный ресурс не существует), вам следует рассмотреть возможность исключения исключения вместе с соответствующим кодом состояния HTTP (например, yii\web\NotFoundHttpException представляет код состояния 404). Yii отправит ответ вместе с соответствующим кодом состояния и текстом HTTP. Yii также будет включать сериализованное представление исключения в теле ответа. Например:

HTTP/1.1 404 Not Found
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
    "name": "Not Found Exception",
    "message": "The requested resource was not found.",
    "code": 0,
    "status": 404
}

В следующем списке приведены коды состояния HTTP, которые используются в инфраструктуре Yii REST:

  • 200: ОК. Все работало должным образом.
  • 201: Ресурс был успешно создан в ответ на запрос POST. Заголовок Location содержит URL-адрес, указывающий на только что созданный ресурс.
  • 204: запрос был обработан успешно, и ответ не содержит содержимого тела (например, запрос DELETE).
  • 304: Ресурс не был изменен. Вы можете использовать кэшированную версию.
  • ошибка 400, неверный запрос. Это может быть вызвано различными действиями пользователя, такими как предоставление недопустимых данных JSON в теле запроса, предоставление недопустимых параметров действия и т. д.
  • 401: Ошибка аутентификации.
  • 403: Уполномоченному пользователю не разрешен доступ к указанной конечной точке API.
  • 404: запрошенный ресурс не существует.
  • 405: Метод не разрешен. Проверьте заголовок Allow заголовки разрешенных методов HTTP.
  • 415: Неподдерживаемый тип носителя. Недопустимый запрошенный тип контента или номер версии.
  • 422: Ошибка проверки данных (например, в ответ на запрос POST). Пожалуйста, проверьте тело ответа на подробные сообщения об ошибках.
  • 429: Слишком много запросов. Запрос был отклонен из-за ограничения скорости.
  • 500 - внутренняя ошибка сервера. Это может быть вызвано внутренними ошибками программы.

Настройка ответа на ошибку

Иногда вы можете настроить формат ответа по умолчанию. Например, вместо того чтобы полагаться на использование разных HTTP-статусов для указания различных ошибок, вы всегда хотели бы использовать 200 как статус HTTP и приложить фактический код состояния HTTP как часть структуры JSON в ответе, как показано ниже,

HTTP/1.1 200 OK
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
    "success": false,
    "data": {
        "name": "Not Found Exception",
        "message": "The requested resource was not found.",
        "code": 0,
        "status": 404
    }
}

Для достижения этой цели вы можете ответить на событие beforeSend компонента ответа в конфигурации приложения:

return [
    // ...
    'components' => [
        'response' => [
            'class' => 'yii\web\Response',
            'on beforeSend' => function ($event) {
                $response = $event->sender;
                if ($response->data !== null && Yii::$app->request->get('suppress_response_code')) {
                    $response->data = [
                        'success' => $response->isSuccessful,
                        'data' => $response->data,
                    ];
                    $response->statusCode = 200;
                }
            },
        ],
    ],
];

Вышеприведенный код будет переформатировать ответ (как для успешных, так и для неудавшихся ответов), как объясняется, когда параметр suppress_response_code передается как параметр GET.