Django REST framework

类视图

Django 的类视图是一种令人欢迎的创新，摒弃了旧式的视图风格。

— Reinout van Rees

REST framework 提供了一个 APIView 类，该类继承自 Django 的 View 类。

与普通的 View 类相比，APIView 类具有以下不同之处：

传递给处理方法的请求将是 REST framework 的 Request 实例，而不是 Django 的 HttpRequest 实例。
处理方法可以返回 REST framework 的 Response，而不是 Django 的 HttpResponse。视图将管理内容协商并设置响应的正确渲染器。
任何 APIException 异常都将被捕获并转换为适当的响应。
在将请求分发到处理方法之前，将对传入的请求进行身份验证并运行适当的权限和 / 或限速检查。

使用 APIView 类与使用普通的 View 类几乎相同，通常，传入的请求会被分发到适当的方法，如 .get() 或 .post()。此外，可以在类上设置许多属性以控制 API 策略的各个方面。

例如：

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import authentication, permissions
from django.contrib.auth.models import User

class ListUsers(APIView):
    """
    查看系统中所有用户的列表。
    * 需要令牌身份验证。
    * 只有管理员用户才能访问此视图。
    """
    authentication_classes = [authentication.TokenAuthentication]
    permission_classes = [permissions.IsAdminUser]

    def get(self, request, format=None):
        """
        返回所有用户的列表。
        """
        usernames = [user.username for user in User.objects.all()]
        return Response(usernames)

注意：Django REST Framework 的 APIView、GenericAPIView、各种 Mixins 和 Viewsets 之间的完整方法、属性和关系可能最初比较复杂。除了此处的文档外，Classy Django REST Framework 资源还提供了每个 Django REST Framework 类视图的可浏览参考，包括完整的方法和属性。

API 策略属性

以下属性控制 API 视图的可插拔方面。

.renderer_classes

.parser_classes

.authentication_classes

.throttle_classes

.permission_classes

.content_negotiation_class

API 策略实例化方法

以下方法由 REST framework 用于实例化各种可插拔的 API 策略。通常你不需要重写这些方法。

.get_throttles(self)

.get_permissions(self)

.get_content_negotiator(self)

.get_exception_handler(self)

API 策略实现方法

以下方法在分发到处理方法之前被调用。

.check_permissions(self, request)

.check_throttles(self, request)

.perform_content_negotiation(self, request, force=False)

分发方法

以下方法直接由视图的 .dispatch() 方法调用。在调用处理方法（如 .get()、.post()、put()、patch() 和 .delete()）之前或之后执行任何需要的操作。

.initial(self, request, args, *kwargs)

在调用处理方法之前执行任何需要的操作。此方法用于强制执行权限和限流，并进行内容协商。通常你不需要重写此方法。

.handle_exception(self, exc)

处理方法抛出的任何异常将传递给此方法，该方法要么返回一个 Response 实例，要么重新抛出异常。默认实现处理 rest_framework.exceptions.APIException 的任何子类以及 Django 的 Http404 和 PermissionDenied 异常，并返回适当的错误响应。如果你需要自定义 API 返回的错误响应，应重写此方法。

.initialize_request(self, request, args, *kwargs)

确保传递给处理方法的请求对象是 Request 实例，而不是通常的 Django HttpRequest。通常你不需要重写此方法。

.finalize_response(self, request, response, args, *kwargs)

确保从处理方法返回的任何 Response 对象将根据内容协商渲染成正确的内容类型。通常你不需要重写此方法。

基于函数的视图

说 [类视图] 总是更优的解决方案是错误的。

— Nick Coghlan

REST framework 还允许你使用普通的基于函数的视图。它提供了一组简单的装饰器，这些装饰器包装你的基于函数的视图，以确保它们接收 Request 实例（而不是通常的 Django HttpRequest），并允许它们返回 Response（而不是 Django 的 HttpResponse），并允许你配置如何处理请求。

@api_view()

签名： @api_view(http_method_names=['GET'])

此功能的核心是 api_view 装饰器，它接受一个 HTTP 方法列表，你的视图应该对此作出响应。例如，以下是如何编写一个非常简单的视图，手动返回一些数据：

from rest_framework.decorators import api_view
from rest_framework.response import Response

@api_view()
def hello_world(request):
    return Response({"message": "Hello, world!"})

此视图将使用设置中指定的默认渲染器、解析器、身份验证类等。默认情况下只接受 GET 方法。其他方法将响应 “405 方法不被允许”。要更改此行为，指定视图允许的方法，如下所示：

@api_view(['GET', 'POST'])
def hello_world(request):
    if request.method == 'POST':
        return Response({"message": "Got some data!", "data": request.data})
    return Response({"message": "Hello, world!"})

API 策略装饰器

为了覆盖默认设置，REST framework 提供了一组额外的装饰器，可以添加到你的视图中。这些必须放在（在下面）@api_view 装饰器之后。例如，要创建一个使用限流来确保一个特定用户每天只能调用一次的视图，使用 @throttle_classes 装饰器，传递一个限流类列表：

from rest_framework.decorators import api_view, throttle_classes
from rest_framework.throttling import UserRateThrottle

class OncePerDayUserThrottle(UserRateThrottle):
    rate = '1/day'

@api_view(['GET'])
@throttle_classes([OncePerDayUserThrottle])
def view(request):
    return Response({"message": "Hello for today! See you tomorrow!"})

这些装饰器对应于上面描述的 APIView 子类上设置的属性。

可用的装饰器有：

@renderer_classes(...)
@parser_classes(...)
@authentication_classes(...)
@throttle_classes(...)
@permission_classes(...)

这些装饰器中的每一个都接受一个参数，该参数必须是类的列表或元组。

视图模式装饰器

要覆盖基于函数的视图的默认模式生成，你可以使用 @schema 装饰器。这必须放在（在下面）@api_view 装饰器之后。例如：

from rest_framework.decorators import api_view, schema
from rest_framework.schemas import AutoSchema

class CustomAutoSchema(AutoSchema):
    def get_link(self, path, method, base_url):
        # 这里覆盖视图内省...

@api_view(['GET'])
@schema(CustomAutoSchema())
def view(request):
    return Response({"message": "Hello for today! See you tomorrow!"})

此装饰器接受一个 AutoSchema 实例、AutoSchema 子类实例或 ManualSchema 实例，如模式文档所述。你可以传递 None 以将视图排除在模式生成之外。

@api_view(['GET'])
@schema(None)
def view(request):
    return Response({"message": "Will not appear in schema!"})

Django REST framework - 视图

类视图