Django REST framework——Generic views

基于类的视图的一个主要优点是它们允许您组合可重用行为的方式。REST框架通过提供一些提供常用模式的预构建视图来利用这一点。
REST框架提供的这些通用视图让你快速构建与您的数据库模型紧密相关的API视图。
如果通用视图不适合您的API需求，您可以直接使用常规APIView类，或者重用通用视图使用的mixins和基类来组成您自己的可重用通用视图集。

（Mixins是一种语言概念，允许程序员将一些代码注入到一个类中。Mixin编程是一种软件开发的风格，其中功能单元在一个类中创建，然后与其他类混合。mixin类扮演父类的角色，包含其他类想要的功能。然后，一个子类可以继承或简单地重用此功能，但不能作为专业化的手段。通常，mixin将会将所需的功能导出到子类中，而不会创建一个单一的“is a”关系。这是mixins和继承的概念之间的重要区别，因为子类仍然可以继承父类的所有功能，但是，不必一定应用关于子对象“作为一种”父语义的语义。）

例子：

通常，在使用通用视图时，您将覆盖视图，并设置多个雷类属性。

from django.contrib.auth.models import User
from myapp.serializers import UserSerializer
from rest_framework import generics
from rest_framework.premissions import IsAdminUser

class UserList(generics.ListCreateAPIView):
	queryset=User.objects.all()
	serializer_class=UserSerializer
	permission_classes=(IsAdminUser,)

对于更复杂的情况,您可能还希望覆盖视图类上的各种方法.例如:

class UserList(generics.ListCreateAPIView):
	queryset=User.objects.all()
	serializer_class=UserSerializer
	permission_classes=(IsAdminUser,)

	def list(self,request):
		#Note the use of 'get_queryset()' instead of 'self.queryset'
		queryset=self.get_queryset()
		serializer=UserSerializer(queryset,many=True)
		return Response(serializer.data)

对于非常简单的情况,您可能希望使用.as_view()方法传递任何类属性.
例如,您的URLcconf可能包含以下条目:

url(r'^/users/',ListCreateAPIView.as_view(queryseet=User.objects.all(),serializer_class=UserSerializer),name='user-list')

API参考

GenericAPIView

此类扩展了REST框架的APIView类，为标准列表和详细信息视图添加了常用的行为。
提供的每个具体通用视图都是通过将GenericAPIView与一个或多个mixin类组合而构建的。

属性

基本属性:

以下属性控制基本视图行为。

queryset - 应该用于从此视图返回对象的查询集。通常，您必须设置此属性，或覆盖get_queryset()方法。如果要覆盖视图方法，则必须调用get_queryset()而不是直接访问此属性，因为queryset将被评估一次，并且将为所有后续请求缓存这些结果。
serializer_class - 应该用于验证和反序列化输入以及序列化输出的序列化程序类。通常，您必须设置此属性，或覆盖get_serializer_class()方法。
lookup_filed - 应该用于执行单个模型实例的对象查找的模型字段。默认为’pk’。请注意，使用超链接API时，如果需要使用自定义值，则需要确保API视图和序列化程序类都设置查找字段。
lookup_url_kwag - 应该用于对象查找的URL关键字参数。URL conf应包含与此值对应的关键字参数。如果未设置，则默认使用与lookup_field相同的值。

Pagination(分页):

与列表视图一起使用时，以下属性用于控制分页。

pagination_class - 分页列表结果时应使用的分页类。默认值与DEFAULT_PAGINATION_CLASS设置相同，即“rest_framework.pagination.PageNumberPagination”。设置pagination_class = None将禁用此视图上的分页。

Filtering:

filter_backends - 应该用于过滤查询集的过滤器后端类列表。默认值与DEFAULT_FILTER_BACKENDS设置相同。

Methods

基本方法:

get_queryset(self)

返回应该用于列表视图的查询集，该查询集应该用作详细视图中查找的基础。默认返回queryset属性指定的查询集。

应始终使用此方法而不是直接访问self.queryset，因为self.queryset仅被评估一次，并且这些结果将被缓存用于所有后续请求。

可以重写以提供动态行为，例如返回查询集，该查询集特定于发出请求的用户。

例如:

def get_queryset(self):
	user=self.request.user
	return user.account.all()

get_object(self)

返回应该用于详细视图的对象实例。默认使用lookup_field参数来过滤基本查询集。

可以重写以提供更复杂的行为，例如基于多个URL kwarg的对象查找。

例如:

def get_object(self):
	queryset=self.get_queryset()
	filter={}
	for field in self.multiple_lookup_fields:
		filter[field]=self.kwargs[field]
	obj=get_object_or_404(queryset,**filter)
	self.check_object_permission(self.request,obj)
	return obj

请注意，如果您的API不包含任何对象级权限，您可以选择性地排除self.check_object_permissions，并只从get_object_or_404查找中返回该对象。

filter_queryset(self,queryset)

给定一个查询集，使用正在使用的任何过滤后端过滤它，返回一个新的查询集。

例如:

def filter_queryset(self,queryset):
	filter_backends=(CategoryFilter,)

	if 'geo_route' in self.request.query_params:
		filter_backends=(GeoRouteFilter,CategoryFilter)
	elif 'geo_point' in self.request.query_params:
		filter_backends=(GeoPointFilter,CategoryFilter)

	for backend in list(filter_backends):
		queryset=backend().filter_queryset(self.request,queryset,view=self)
	return queryset

get_serializer_class(self)

返回应该用于序列化程序的类。默认返回serializer_class属性。可以重写以提供动态行为，例如使用不同的序列化程序进行读写操作，或者为不同类型的用户提供不同的序列化程序。

例如:

def get_serializer_class(self):
	if self.request.user.is_staff:
		return FullAccountSerializer
	return BasicAccountSerializer

保存和删除钩子

mixin类提供了以下方法，并提供了对象保存或删除行为的轻松覆盖。

perform_create(self,serializer) - 保存新对象实例时由CreateModelMixin调用
perform_update(self,serializer) - 保存现有对象实例时由UpdateModelMixin调用
perform_destory(self,instance) - 删除对象实例时由DestroyModelMixin调用。

这些挂钩对于设置请求中隐含的属性特别有用，但不是请求数据的一部分。例如，您可以根据请求用户或基于URL关键字参数在对象上设置属性。

def perform_create(self,serializer):
	serializer.save(user=self.request.user)

这些覆盖点对于添加在保存对象之前或之后发生的行为（例如通过电子邮件发送确认或记录更新）也特别有用。

def perform_update(self,serializer):
	instance=serializer.save()
	send_email_confirmation(user=self.request.user,modified=instance)

您还可以通过引发ValidationError()来使用这些钩子来提供额外的验证。如果您需要在数据库保存点应用某些验证逻辑，这可能很有用。例如：

def perform_create(self,serializer):
	queryset=SignupRequest.objects.filter(user=self.request.user)
	if queryset.exists():
		raise ValidationError('You have already signed up')
	serializer.save(user=self.request.user)

注意：这些方法替换了旧版本的2.x pre_save，post_save，pre_delete和post_delete方法，这些方法已不再可用。

其他方法:

您通常不需要覆盖以下方法，但如果您使用GenericAPIView编写自定义视图，则可能需要调用它们。

get_serializer_context(self) - 返回包含应提供给序列化程序的任何额外上下文的字典。默认包括“request”，“view”和“format”键
get_serializer(self,instance=None,data=None,many=False,partial=False) - 返回一个序列化程序实例
get_paginated_response(self,data) - 返回分页样式的Response对象。
paginate_queryset(self,queryset) - 如果需要，可以返回一个查询集，返回页面对象;如果没有为此视图配置分页，则为“无”
filter_queryset(self,queryset) - 给定一个查询集，使用正在使用的任何过滤后端过滤它，返回一个新的查询集。

Mixins

mixin类提供用于提供基本视图行为的操作。请注意，mixin类提供了操作方法，而不是直接定义处理程序方法，例如.get()和.post()。这允许更灵活的行为组合。mixin类可以从rest_framework.mixins导入。

ListModelMixin

提供.list(request,* args,** kwargs)方法，用于实现列出查询集。如果填充了查询集，则返回200 OK响应，并将查询集的序列化表示作为响应的主体。可选地，可以对响应数据进行分页。

CreateModelMixin

提供.create(request,* args,** kwargs)方法，用于实现创建和保存新模型实例。如果创建了一个对象，则返回201 Created响应，该对象的序列化表示形式为响应的主体。如果表示包含名为url的键，则响应的Location标头将填充该值。如果为创建对象而提供的请求数据无效，则将返回400 Bad Request响应，并将错误详细信息作为响应的主体。

RetrieveModelMixin

提供.retrieve(request,* args,** kwargs)方法，该方法实现在响应中返回现有模型实例。如果可以检索对象，则返回200 OK响应，并将对象的序列化表示作为响应的主体。否则它将返回404 Not Found。

UpdateModelMixin

提供.update(request,* args,** kwargs)方法，用于实现更新和保存现有模型实例。还提供了.partial_update(request,* args,** kwargs)方法，类似于update方法，但更新的所有字段都是可选的。这允许支持HTTP PATCH请求。如果对象被更新，则返回200 OK响应，其中对象的序列化表示作为响应的主体。如果为更新对象而提供的请求数据无效，则将返回400 Bad Request响应，并将错误详细信息作为响应的主体。

DestoryModelMixin

提供.destroy(request，* args，** kwargs)方法，用于实现对现有模型实例的删除。如果删除了一个对象，则返回204 No Content响应，否则返回404 Not Found。

具体view类

以下类是具体的通用视图。如果您使用的是通用视图，这通常是您将要工作的级别，除非您需要大量自定义的行为。可以从rest_framework.generics导入视图类。

CreateAPIView

用于仅创建端点。
提供post方法处理程序。
Extends:GenericAPIView,CreateModelMixin

ListAPIView

用于只读端点以表示模型实例的集合。
提供get方法处理程序。
Extends:GenericAPIView,ListModelMixin

RetrieveAPIView

用于只读端点以表示单个模型实例。
提供get方法处理程序。
Extends:GenericAPIView,RetrieveModelMixin

DestoryAPIView

用于单个模型实例的仅删除端点。
提供删除方法处理程序。
Extends:GenericAPIView,DestoryModelMixin

UpdateAPIView

用于单个模型实例的仅更新端点。
提供put和patch方法处理程序。
Extends:GenericAPIView,UpdateModelMixin

ListCreateAPIView

用于读写端点以表示模型实例的集合。
提供get和post方法处理程序。
Extends:GenericAPIView,ListModelMixin,CreateModelMixin

RetrieveUpdateAPIView

用于读取或更新端点以表示单个模型实例。
提供get，put和patch方法处理程序。
Extends:GenericAPIView,RetrieveModelMixin,UpdateModelMixin

RetrieveDestoryAPIView

用于读取或删除端点以表示单个模型实例。
提供get和delete方法处理程序。
Extends:GenericAPIView,RetrieveModelMixin,DestoryModelMixin

RetrieveUpdateDestoryAPIView

用于读写 - 删除端点以表示单个模型实例。
提供get，put，patch和delete方法处理程序。
Extends:GenericAPIView,RetrieveModelMixin,UpdateModelMixin,DestoryModelMixin

自定义通用视图

通常，您会想要使用现有的通用视图，但使用一些略微自定义的行为。如果您发现自己在多个位置重复使用某些自定义行为，则可能需要将该行为重构为一个公共类，然后您可以根据需要将其应用于任何视图或视图集。

创建自定义mixins

例如，如果您需要根据URL conf中的多个字段查找对象，则可以创建如下所示的mixin类：

class MultipleFieldLookupMin(object):
	"""
	Apply this mixin to any view or viewset to get multiple field filtering based on a 'lookup_fields' attribute,instead of the default single field filtering.
	"""
	def get_object(self):
		queryset=self.get_queryset()                  #Get the base queryset
		queryset=self.filter_queryset(queryset)   #Apply any filter backends
		filter={}
		for field in self.lookup_fields:
			if self.kwargs[field]:  #Ignore empty fields
				filter[field]=self.kwargs[field]
		obj=get_object_or_404(queryset,**filter) #Lookup the object
		self.check_object_permissions(self.request,obj)
		return obj

然后，只要您需要应用自定义行为，就可以将此mixin简单地应用于视图或视图集。

class RetrieveUserView(MultipleFieldLookupMixin,generics.RetrieveAPIView):
	queryset=User.objects.all()
	serializer_class=UserSerializer
	lookup_fields=('account,'username')

如果您需要使用自定义行为，则使用自定义mixins是一个不错的选择。

创建自定义基类

如果您在多个视图中使用mixin，则可以更进一步，创建自己的一组基本视图，然后可以在整个项目中使用。例如：

class BaseRetrieveView(MultipleFieldLookupMixin,generics.RetrieveAPIView)
	pass
class BaseRetrieveUpdateDestoryView(MultipleFieldLookupMixin,generics.RetrieveUpdateDestoryAPIView)
	pass

如果您的自定义行为始终需要在整个项目中的大量视图中重复，那么使用自定义基类是一个不错的选择。

PUT as create

在3.0版之前，REST框架将处理后的PUT混合为更新或创建操作，具体取决于对象是否已存在。
允许PUT作为创建操作是有问题的，因为它必然暴露有关对象存在或不存在的信息。透明地允许重新创建先前删除的实例也不一定是比仅返回404响应更好的默认行为。
两种样式“PUT as 404”和“PUT as create”在不同情况下都可以有效，但从版本3.0开始，我们现在使用404行为作为默认值，因为它更简单，更明显。
如果您需要通用的PUT-as-create行为，您可能希望将类似此类的AllowPUTAsCreateMixin类作为mixin包含在您的视图中。

第三方包

以下第三方包提供了其他通用视图实现。

Django REST Framework bulk

django-rest-framework-bulk包实现了通用视图mixin以及一些常见的具体通用视图，以允许通过API请求应用批量操作。

Django Rest Multiple Models

Django Rest Multiple Models提供了一个通用视图（和mixin），用于通过单个API请求发送多个序列化模型和/或查询集。