• 基于类的视图
    • API 策略属性(policy attributes)
    • API 策略实例方法(policy instantiation methods)
    • API 策略实现方法(policy implementation methods)
    • 方法调度
  • 基于方法的视图
    • @api_view()
    • API 策略装饰器 (policy decorators)
    • View schema 装饰器

    官方原文链接

    基于类的视图

    REST framework 提供了一个 APIView 类,它继承于 Django 的 View 类。

    APIView 类与不同的 View 类有所不同:

    • 传递给处理方法的 request 对象是 REST framework 的 Request 实例,而不是 Django 的 HttpRequest 实例。
    • 处理方法可能返回 REST framework 的 Response,而不是 Django 的 HttpResponse 。该视图将管理内容协商,并在响应中设置正确的渲染器。
    • 任何 APIException 异常都会被捕获并进行适当的响应。
    • 传入的请求会进行认证,在请求分派给处理方法之前将进行适当的权限检查(允许或限制)。

    像往常一样,使用 API​​View 类与使用常规 View 类非常相似,传入的请求被分派到适当的处理方法,如 .get().post()。此外,可以在类上设置许多属性(AOP)。

    举个栗子:

    1. from rest_framework.views import APIView
    2. from rest_framework.response import Response
    3. from rest_framework import authentication, permissions
    4. from django.contrib.auth.models import User
    5. class ListUsers(APIView):
    6. """
    7. 列出系统中的所有用户
    8. * 需要 token 认证。
    9. * 只有 admin 用户才能访问此视图。
    10. """
    11. authentication_classes = (authentication.TokenAuthentication,)
    12. permission_classes = (permissions.IsAdminUser,)
    13. def get(self, request, format=None):
    14. """
    15. Return a list of all users.
    16. """
    17. usernames = [user.username for user in User.objects.all()]
    18. return Response(usernames)

    注意:REST Framework 中的 APIViewGenericAPIView,各种 MixinsViewsets 包含许多方法和属性,刚开始要全部理解是比较困难的。这里除了文档,有一个 Classy Django REST Framework 资源,它提供了一个可以在线浏览的参照,包含所有属性和方法。

    API 策略属性(policy attributes)

    以下属性用于增加扩展视图的功能,AOP。

    .renderer_classes
    设置渲染器

    .parser_classes
    设置解析器

    .authentication_classes
    设置认证器

    .throttle_classes

    .permission_classes
    设置权限验证器

    .content_negotiation_class

    API 策略实例方法(policy instantiation methods)

    以下策略实例方法通常不需要我们重写。

    .get_renderers(self)

    .get_parsers(self)

    .get_authenticators(self)

    .get_throttles(self)

    .get_permissions(self)

    .get_content_negotiator(self)

    .get_exception_handler(self)

    API 策略实现方法(policy implementation methods)

    在分派到处理方法之前会调用以下方法。

    .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 的 Http404PermissionDenied 异常,并返回相应的错误响应。

    如果需要自定义 API 返回的错误响应,应该重写此方法。

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

    确保传递给处理方法的请求对象是 Request 的一个实例,而不是通常的 Django HttpRequest

    通常不需要重写此方法。

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

    确保从处理方法返回的任何 Response 对象将被呈现为正确的内容类型,这由内容协商确定。

    通常不需要重写此方法。

    基于方法的视图

    REST framework 也允许使用基于函数的视图。它提供了一套简单的装饰器来包装你的函数视图,以确保它们接收 Request(而不是 Django HttpRequest)实例并允许它们返回 Response(而不是 Django HttpResponse),并允许你配置该请求的处理方式。

    @api_view()

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

    api_view 是一个装饰器,用 http_method_names 来设置视图允许响应的 HTTP 方法列表,举个栗子,编写一个简单的视图,手动返回一些数据。

    1. from rest_framework.decorators import api_view
    2. @api_view()
    3. def hello_world(request):
    4. return Response({"message": "Hello, world!"})

    该视图将使用 settings 中指定的默认渲染器,解析器,认证类等。

    默认情况下,只有 GET 方法会被接受。其他方法将以 "405 Method Not Allowed" 进行响应。要改变这种行为,请指定视图允许的方法,如下所示:

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

    API 策略装饰器 (policy decorators)

    为了覆盖默认设置,REST framework 提供了一系列可以添加到视图中的附加装饰器。这些必须在 @api_view 装饰器之后(下方)。例如,要创建一个使用 throttle 来确保它每天只能由特定用户调用一次的视图,请使用 @throttle_classes 装饰器,传递一个 throttle 类列表:

    1. from rest_framework.decorators import api_view, throttle_classes
    2. from rest_framework.throttling import UserRateThrottle
    3. class OncePerDayUserThrottle(UserRateThrottle):
    4. rate = '1/day'
    5. @api_view(['GET'])
    6. @throttle_classes([OncePerDayUserThrottle])
    7. def view(request):
    8. return Response({"message": "Hello for today! See you tomorrow!"})

    这些装饰器对应于 APIView 上设置的策略属性。

    可用的装饰器有:

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

    每个装饰器都有一个参数,它必须是一个类列表或者一个类元组。

    View schema 装饰器

    要覆盖函数视图的默认 模式生成(schema generation),可以使用 @schema 装饰器。这必须在 @api_view 装饰器之后(下方)。例如:

    1. from rest_framework.decorators import api_view, schema
    2. from rest_framework.schemas import AutoSchema
    3. class CustomAutoSchema(AutoSchema):
    4. def get_link(self, path, method, base_url):
    5. # override view introspection here...
    6. @api_view(['GET'])
    7. @schema(CustomAutoSchema())
    8. def view(request):
    9. return Response({"message": "Hello for today! See you tomorrow!"})

    该装饰器将采用一个 AutoSchema 实例,一个 AutoSchema 子类实例或 ManualSchema 实例,如 Schemas 文档(先放官链)中所述。您也可以传 None 以从 模式生成(schema generation) 中排除视图。

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