Исключения¶
Исключения… позволяют чисто организовать обработку ошибок в центральном или высокоуровневом месте в структуре программы.
‒ Doug Hellmann, Python Exception Handling Techniques
Обработка исключений в представлениях фреймворка REST¶
Представления фреймворка REST обрабатывают различные исключения и возвращают соответствующие ответы на ошибки.
Обрабатываемыми исключениями являются:
Подклассы
APIException
, поднятые внутри фреймворка REST.Исключение Django
Http404
.Исключение Django
PermissionDenied
.
В каждом случае фреймворк REST возвращает ответ с соответствующим кодом состояния и типом содержимого. В теле ответа будут содержаться любые дополнительные сведения о характере ошибки.
Большинство ответов на ошибки будут содержать ключ detail
в теле ответа.
Например, следующий запрос:
DELETE http://api.example.com/foo/bar HTTP/1.1
Accept: application/json
Может быть получен ответ об ошибке, указывающий на то, что метод DELETE
не разрешен на данном ресурсе:
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 42
{"detail": "Method 'DELETE' not allowed."}
Ошибки валидации обрабатываются несколько иначе, и в качестве ключей в ответе будут указаны имена полей. Если ошибка валидации не относится к конкретному полю, то будет использован ключ «non_field_errors» или любое строковое значение, установленное для параметра NON_FIELD_ERRORS_KEY
.
Пример ошибки валидации может выглядеть следующим образом:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 94
{"amount": ["A valid integer is required."], "description": ["This field may not be blank."]}
Пользовательская обработка исключений¶
Вы можете реализовать пользовательскую обработку исключений, создав функцию-обработчик, которая преобразует исключения, возникающие в представлениях вашего API, в объекты ответа. Это позволит вам контролировать стиль ответов на ошибки, используемый вашим API.
Функция должна принимать пару аргументов, первый из которых - обрабатываемое исключение, а второй - словарь, содержащий любой дополнительный контекст, например, обрабатываемое в данный момент представление. Функция обработчика исключения должна либо вернуть объект Response
, либо вернуть None
, если исключение не может быть обработано. Если обработчик возвращает None
, то исключение будет повторно поднято и Django вернет стандартный ответ HTTP 500 „server error“.
Например, вы можете захотеть убедиться, что все ответы на ошибки включают код состояния HTTP в теле ответа, например, так:
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 62
{"status_code": 405, "detail": "Method 'DELETE' not allowed."}
Чтобы изменить стиль ответа, вы можете написать следующий пользовательский обработчик исключений:
from rest_framework.views import exception_handler
def custom_exception_handler(exc, context):
# Call REST framework's default exception handler first,
# to get the standard error response.
response = exception_handler(exc, context)
# Now add the HTTP status code to the response.
if response is not None:
response.data['status_code'] = response.status_code
return response
Аргумент context не используется обработчиком по умолчанию, но может быть полезен, если обработчику исключения нужна дополнительная информация, например, обрабатываемое в данный момент представление, доступ к которому можно получить в виде context['view']
.
Обработчик исключений также должен быть настроен в ваших настройках, используя клавишу настройки EXCEPTION_HANDLER
. Например:
REST_FRAMEWORK = {
'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
}
Если параметр 'EXCEPTION_HANDLER'
не указан, то по умолчанию используется стандартный обработчик исключений, предоставляемый фреймворком REST:
REST_FRAMEWORK = {
'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
}
Обратите внимание, что обработчик исключений будет вызываться только для ответов, сгенерированных поднятыми исключениями. Он не будет использоваться для любых ответов, возвращаемых непосредственно представлением, например, ответов HTTP_400_BAD_REQUEST
, которые возвращаются общими представлениями при неудачной проверке сериализатора.
Справочник по API¶
APIException¶
Подпись: APIException()
базовый класс для всех исключений, возникающих внутри класса APIView
или @api_view
.
Чтобы обеспечить пользовательское исключение, подкласс APIException
и установите атрибуты .status_code
, .default_detail
, и default_code
на класс.
Например, если ваш API полагается на сторонний сервис, который иногда может быть недоступен, вы можете захотеть реализовать исключение для кода ответа HTTP «503 Service Unavailable». Это можно сделать следующим образом:
from rest_framework.exceptions import APIException
class ServiceUnavailable(APIException):
status_code = 503
default_detail = 'Service temporarily unavailable, try again later.'
default_code = 'service_unavailable'
Проверка исключений API¶
Существует ряд различных свойств, доступных для проверки состояния исключения API. Вы можете использовать их для создания пользовательской обработки исключений в вашем проекте.
Доступными атрибутами и методами являются:
.detail
- Возвращает текстовое описание ошибки..get_codes()
- Возвращает идентификатор кода ошибки..get_full_details()
- Возвращает как текстовое описание, так и идентификатор кода.
В большинстве случаев деталь ошибки будет простым элементом:
>>> print(exc.detail)
You do not have permission to perform this action.
>>> print(exc.get_codes())
permission_denied
>>> print(exc.get_full_details())
{'message':'You do not have permission to perform this action.','code':'permission_denied'}
В случае ошибок валидации деталь ошибки будет представлять собой список или словарь элементов:
>>> print(exc.detail)
{"name":"This field is required.","age":"A valid integer is required."}
>>> print(exc.get_codes())
{"name":"required","age":"invalid"}
>>> print(exc.get_full_details())
{"name":{"message":"This field is required.","code":"required"},"age":{"message":"A valid integer is required.","code":"invalid"}}
ParseError¶
Подпись: ParseError(detail=None, code=None)
Возникает, если запрос содержит неправильно сформированные данные при доступе к request.data
.
По умолчанию это исключение приводит к ответу с кодом состояния HTTP «400 Bad Request».
AuthenticationFailed¶
Подпись: AuthenticationFailed(detail=None, code=None)
Возникает, когда входящий запрос содержит неправильную аутентификацию.
По умолчанию это исключение приводит к ответу с кодом состояния HTTP «401 Unauthenticated», но оно также может привести к ответу «403 Forbidden», в зависимости от используемой схемы аутентификации. Более подробную информацию см. в authentication documentation.
NotAuthenticated¶
Подпись: NotAuthenticated(detail=None, code=None)
Возникает, когда неаутентифицированный запрос не прошел проверку на разрешение.
По умолчанию это исключение приводит к ответу с кодом состояния HTTP «401 Unauthenticated», но оно также может привести к ответу «403 Forbidden», в зависимости от используемой схемы аутентификации. Более подробную информацию см. в authentication documentation.
PermissionDenied¶
Подпись: PermissionDenied(detail=None, code=None)
Возникает, когда аутентифицированный запрос не прошел проверку на разрешение.
По умолчанию это исключение приводит к ответу с кодом состояния HTTP «403 Forbidden».
NotFound¶
Подпись: NotFound(detail=None, code=None)
Возникает, когда ресурс не существует по заданному URL. Это исключение эквивалентно стандартному исключению Django Http404
.
По умолчанию это исключение приводит к ответу с кодом состояния HTTP «404 Not Found».
MethodNotAllowed¶
Подпись: MethodNotAllowed(method, detail=None, code=None)
Возникает, когда происходит входящий запрос, который не сопоставлен с методом-обработчиком на представлении.
По умолчанию это исключение приводит к ответу с кодом состояния HTTP «405 Method Not Allowed».
Неприемлемо¶
Подпись: NotAcceptable(detail=None, code=None)
Возникает, когда поступает запрос с заголовком Accept
, который не может быть удовлетворен ни одним из доступных рендереров.
По умолчанию это исключение приводит к ответу с кодом состояния HTTP «406 Not Acceptable».
UnsupportedMediaType¶
Подпись: UnsupportedMediaType(media_type, detail=None, code=None)
Возникает, если при обращении к request.data
нет парсеров, способных обработать тип содержимого данных запроса.
По умолчанию это исключение приводит к ответу с кодом состояния HTTP «415 Unsupported Media Type».
Дросселированный¶
Подпись: Throttled(wait=None, detail=None, code=None)
Возникает, когда входящий запрос не проходит проверку на дросселирование.
По умолчанию это исключение приводит к ответу с кодом состояния HTTP «429 Too Many Requests».
ValidationError¶
Подпись: ValidationError(detail, code=None)
Исключение ValidationError
несколько отличается от других классов APIException
:
Аргумент
detail
является обязательным, а не опциональным.Аргумент
detail
может представлять собой список или словарь сведений об ошибках, а также может быть вложенной структурой данных. Используя словарь, вы можете указать ошибки на уровне полей при выполнении проверки на уровне объектов в методеvalidate()
сериализатора. Например.raise serializers.ValidationError({'name': 'Please enter a valid name.'})
По соглашению вы должны импортировать модуль serializers и использовать полностью квалифицированный стиль
ValidationError
, чтобы отличить его от встроенной ошибки валидации Django. Например.raise serializers.ValidationError('This field must be an integer value.')
Класс ValidationError
следует использовать для сериализатора и валидации полей, а также классами валидаторов. Он также возникает при вызове serializer.is_valid
с аргументом ключевого слова raise_exception
:
serializer.is_valid(raise_exception=True)
Общие представления используют флаг raise_exception=True
, что означает, что вы можете переопределить стиль ответов на ошибки валидации глобально в вашем API. Для этого используйте пользовательский обработчик исключений, как описано выше.
По умолчанию это исключение приводит к ответу с кодом состояния HTTP «400 Bad Request».
Общие представления ошибок¶
Django REST Framework предоставляет два представления ошибок, подходящих для предоставления общих JSON 500
Server Error и 400
Bad Request ответов. (Стандартные представления ошибок Django предоставляют ответы в формате HTML, что может не подойти для приложения, использующего только API).
Используйте их в соответствии с Django’s Customizing error views documentation.
rest_framework.exceptions.server_error
¶
Возвращает ответ с кодом состояния 500
и типом содержимого application/json
.
Установить как handler500
:
handler500 = 'rest_framework.exceptions.server_error'
rest_framework.exceptions.bad_request
¶
Возвращает ответ с кодом состояния 400
и типом содержимого application/json
.
Установить как handler400
:
handler400 = 'rest_framework.exceptions.bad_request'