Django REST framework - 异常

Django REST framework 提供了一系列异常类，它们会在 API 视图引发错误时使用。这些异常类确保在请求过程中发生错误时能够返回适当的 HTTP 响应。

可处理的异常

以下几个异常类是“可处理的”，这意味着 REST framework 提供了默认的异常处理程序，可以返回一个适当的错误响应，而不是引发异常并显示回溯。

APIException

所有 API 异常都应继承自 APIException。这个基类提供了一些核心功能：

• status_code 属性用于指定要返回的 HTTP 状态代码。
• default_detail 属性用于指定错误的默认描述，这将在错误消息中返回。
• default_code 属性用于指定错误的默认代码，例如用于序列化器验证错误。

如果你需要自定义异常，你可以继承 APIException 并设置这些属性。

例如：

from rest_framework.exceptions import APIException

class MyCustomException(APIException):
    status_code = 403
    default_detail = '自定义错误消息'
    default_code = 'custom_error_code'

然后，在你的视图中引发这个异常：

raise MyCustomException()

ValidationError

ValidationError 是一个特殊的异常类，用于指示由于用户提供的数据无效而无法处理请求。这通常用于序列化器验证错误。它与 APIView 的 get_validation_exception 方法结合使用，为序列化器错误提供一个清晰的错误响应。

ParseError

当请求无法被解析时引发此异常。这可能是因为请求的内容类型不受支持，或者解析器无法处理请求正文。

AuthenticationFailed

当提供的认证凭据无效，或者请求未包含任何凭据时引发此异常。这通常用于认证类无效的情况。

NotAuthenticated

当请求未包含任何认证凭据时引发此异常。这通常用于需要身份验证的视图，但请求没有提供任何凭据。

PermissionDenied

当请求已通过身份验证，但用户没有执行所请求操作的权限时引发此异常。这通常用于权限类拒绝访问的情况。

NotFound

当请求的对象不能被找到时引发此异常。这通常用于需要特定对象的视图，但对象不存在。

MethodNotAllowed

当请求的方法对于请求的端点不被允许时引发此异常。这通常用于不允许特定 HTTP 方法（例如 POST）的视图。

NotAcceptable

当服务器无法使用请求中指定的媒体类型提供内容时引发此异常。这通常发生在请求的 Accept 头部中没有可用的媒体类型。

Throttled

当请求被限流时引发此异常。这通常用于限流类限制请求速率的情况。

异常处理

REST framework 提供了默认的异常处理程序，该处理程序知道如何处理上述所有可处理的异常。它会返回一个包含错误详细信息和状态代码的 JSON 响应。

然而，有时你可能需要自定义异常处理。为此，你可以创建一个自定义的异常处理函数，并在你的 Django 设置中指定它。

例如：

# 自定义异常处理函数
def custom_exception_handler(exc, context):
    # 调用默认的异常处理程序
    response = exception_handler(exc, context)
    
    # 如果有响应，修改它
    if response is not None:
        response.data['custom_error'] = '这是一个自定义错误消息'
    
    return response

然后，在你的 settings.py 文件中添加：

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
}

这将使用你的自定义异常处理函数来处理所有 API 异常。

错误响应格式

默认的错误响应格式是 JSON，包含一个错误消息和一个错误代码（如果适用）。

例如：

{
    "detail": "错误消息",
    "code": "错误代码"
}

然而，你可以通过设置 NON_FIELD_ERRORS_KEY 来自定义这个格式。

总结

Django REST framework 提供了全面的异常处理机制，使得在 API 开发中能够有效地处理和返回错误信息。通过使用内置的异常类和自定义异常处理函数，你可以确保你的 API 返回一致且有用的错误响应，从而提升用户体验和 API 的可维护性。