官方文档原文
基于类的视图
REST framework 提供了一个 APIView
类,它继承于 Django 的 View
类。
APIView
类与 View
类有所不同:
传递给处理方法的
request
对象是 REST framework 的Request
实例,而不是 Django 的HttpRequest
实例。处理方法可能返回 REST framework 的
Response
,而不是 Django 的HttpResponse
。该视图将管理内容协商,并在响应中设置正确的渲染器。任何
APIException
异常都会被捕获并进行适当的响应。传入的请求会进行认证,在请求分派给处理方法之前将进行适当的权限检查(允许或限制)。
像往常一样,使用 APIView
类与使用常规 View
类非常相似,传入的请求被分派到适当的处理方法,如 .get()
或 .post()
。此外,可以在类上设置许多属性(AOP)。
一个例子:
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):
"""
列出系统中的所有用户
* 需要 token 认证。
* 只有 admin 用户才能访问此视图。
"""
authentication_classes = (authentication.TokenAuthentication,)
permission_classes = (permissions.IsAdminUser,)
def get(self, request, format=None):
"""
Return a list of all users.
"""
usernames = [user.username for user in User.objects.all()]
return Response(usernames)
上例用到的 authentication_classes
和 permission_classes
属于 API 策略属性(policy attributes)。
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 的 Http404 和PermissionDenied
异常,并返回相应的错误响应。
如果需要自定义 API 返回的错误响应,应该重写此方法。
.initialize_request(self, request, *args, **kwargs)
确保传递给处理方法的请求对象是 Request
的一个实例,而不是通常的 Django HttpRequest
。
通常不需要重写此方法。
.finalize_response(self, request, response, *args, **kwargs)
确保从处理方法返回的任何 Response
对象将被呈现为正确的内容类型,这由内容协商确定。
通常不需要重写此方法。