ViewSets
在路由确定了用于请求的控制器之后，控制器负责了解请求并生成适当的输出。—— Ruby on Rails 文档
Django REST framework 允许您将一组相关视图的逻辑组合在一个单独的类中，称为 ViewSet。在其他框架中，您可能会发现概念上类似的实现，名为 “Resources” 或 “Controllers” 。
ViewSet 类只是一种基于类的视图类型，它不提供任何方法处理程序，如 .get() 或 .post()，而是提供诸如 .list() 和 .create() 之类的操作。
ViewSet 的方法处理程序使用 .as_view() 方法在最终确定视图时绑定相应操作。
通常，与其在 urlconf 中显式地注册视图集中的视图，倒不如用路由器类注册视图集，它自动为您确定 urlconf。
举个栗子
让我们定义一个简单的视图集，可用于列出或检索系统中的所有用户。
from django.contrib.auth.models import User
from django.shortcuts import get_object_or_404
from myapps.serializers import UserSerializer
from rest_framework import viewsets
from rest_framework.response import Response
class UserViewSet(viewsets.ViewSet):
"""
A simple ViewSet for listing or retrieving users.
"""
def list(self, request):
queryset = User.objects.all()
serializer = UserSerializer(queryset, many=True)
return Response(serializer.data)
def retrieve(self, request, pk=None):
queryset = User.objects.all()
user = get_object_or_404(queryset, pk=pk)
serializer = UserSerializer(user)
return Response(serializer.data)
如果需要，我们可以将此视图集绑定到两个单独的视图中，如下所示：
user_list = UserViewSet.as_view({'get': 'list'})
user_detail = UserViewSet.as_view({'get': 'retrieve'})
通常我们不会这样做，而是用一个路由器注册视图集，并允许自动生成 urlconf。
from myapp.views import UserViewSet
from rest_framework.routers import DefaultRouter
router = DefaultRouter()
router.register(r'users', UserViewSet, base_name='user')
urlpatterns = router.urls
您通常希望使用提供默认行为集合的现有基类，而不是编写自己的视图集。举个栗子：
class UserViewSet(viewsets.ModelViewSet):
"""
用于查看和编辑用户实例的视图集。
"""
serializer_class = UserSerializer
queryset = User.objects.all()
使用 ViewSet 类比使用 View 类有两个主要优点。
- 重复的逻辑可以组合成一个类。在上面的示例中，我们只需要指定一次
queryset，它将在多个视图中使用。 - 通过使用 routers，我们不再需要处理自己的 URL 连接。
这两者各有优缺点。使用常规视图和 URL 配置文件更加明确，并为您提供更多控制。如果您想快速启动和运行，或者当您拥有大型 API 并希望始终执行一致的 URL 配置时， ViewSets 非常有用。
视图集操作
REST framework 中包含的默认路由器将为一套标准的创建/检索/更新/销毁样式操作提供路由，如下所示：
class UserViewSet(viewsets.ViewSet):
"""
示例空视图集演示由路由器类处理的标准操作。
如果您使用的是格式后缀，请确保每个操作还包括 `format=None` 关键字参数。
"""
def list(self, request):
pass
def create(self, request):
pass
def retrieve(self, request, pk=None):
pass
def update(self, request, pk=None):
pass
def partial_update(self, request, pk=None):
pass
def destroy(self, request, pk=None):
pass
反思视图集操作
在调度期间，ViewSet 上提供了以下属性。
basename—— 用于创建的 URL 名称的基础。action—— 当前操作的名称 (例如，list，create)。detail—— 布尔值指示当前动作是否配置为列表或详细视图。suffix—— 视图集类型的显示后缀 - 反射详细属性。
您可以检查这些属性以根据当前操作调整行为。例如，您可以限制除了与 list 类似的所有权限：
def get_permissions(self):
"""
实例化并返回该视图所需的权限列表。
"""
if self.action == 'list':
permission_classes = [IsAuthenticated]
else:
permission_classes = [IsAdmin]
return [permission() for permission in permission_classes]
标记路由的额外操作
如果你有可路由的特殊方法，你可以用 @action 装饰器来标记它们。与常规操作一样，额外的操作可以用于对象列表或单个实例。要指出这一点，设置 detail 参数为 True 或 False。路由器将相应地配置其 URL 模式。例如，DefaultRouter 将在其 URL 模式中配置包含 pk 的详细操作。
更完整的额外操作例子：
from django.contrib.auth.models import User
from rest_framework import status, viewsets
from rest_framework.decorators import action
from rest_framework.response import Response
from myapp.serializers import UserSerializer, PasswordSerializer
class UserViewSet(viewsets.ModelViewSet):
"""
提供标准操作的视图集
"""
queryset = User.objects.all()
serializer_class = UserSerializer
@action(methods=['post'], detail=True)
def set_password(self, request, pk=None):
user = self.get_object()
serializer = PasswordSerializer(data=request.data)
if serializer.is_valid():
user.set_password(serializer.data['password'])
user.save()
return Response({'status': 'password set'})
else:
return Response(serializer.errors,
status=status.HTTP_400_BAD_REQUEST)
@action(detail=False)
def recent_users(self, request):
recent_users = User.objects.all().order('-last_login')
page = self.paginate_queryset(recent_users)
if page is not None:
serializer = self.get_serializer(page, many=True)
return self.get_paginated_response(serializer.data)
serializer = self.get_serializer(recent_users, many=True)
return Response(serializer.data)
另外，装饰器可以为路由视图设置额外的参数。举个栗子：
@action(methods=['post'], detail=True, permission_classes=[IsAdminOrIsSelf])
def set_password(self, request, pk=None):
...
这些装饰器将默认路由 GET 请求，但也可以通过设置 methods 参数来接受其他 HTTP 方法。例如：
@action(methods=['post', 'delete'], detail=True)
def unset_password(self, request, pk=None):
...
两个新的操作将在 url ^users/{pk}/set_password/$ 和 ^users/{pk}/unset_password/$ 上可用。
要查看所有额外操作，请调用 .get_extra_actions() 方法。
反转操作 urls
如果你需要获取操作的 URL，请使用 .reverse_action() 方法。这是 Reverse() 的便利封装，它自动传递视图的 request 对象，并在 url_name 前加上 .basename 属性。
请注意，basename 是路由器在 ViewSet 注册期间提供的。如果不使用路由器，则必须向 .as_view() 方法提供 basename 参数。
使用上一节中的示例：
>>> view.reverse_action('set-password', args=['1'])
'http://localhost:8000/api/users/1/set_password'
或者，您可以使用 @action 装饰器设置的 url_name 属性。
>>> view.reverse_action(view.set_password.url_name, args=['1'])
'http://localhost:8000/api/users/1/set_password'
.reverse_action() 的 url_name 参数应该与 @action 装饰器匹配相同的参数。此外，此方法可用于反转默认操作，例如 list 和 create。
API 参考
ViewSet
ViewSet 类继承自 APIView。您可以使用任何标准属性 (例如 permission_classes，authentication_classes) 来控制视图集上的 API 策略。
ViewSet 类不提供任何操作的实现。为了使用 ViewSet 类，您将重写该类并显式地定义操作的实现。
GenericViewSet
GenericViewSet 类继承自 GenericAPIView ，并提供默认的 get_object，get_queryset 方法和其他通用视图基本行为，但默认情况下不包含任何操作。
为了使用 GenericViewSet 类，您将重写该类，或混合所需的 mixin 类，或者显式定义操作实现。
ModelViewSet
ModelViewSet 类继承自 GenericAPIView，并通过混合各种 mixin 类的行为来包含各种操作的实现。
ModelViewSet 类提供的操作有 .list()，.retrieve()，.create()，.update()，.partial_update() 和.destroy()。
举个栗子
因为 ModelViewSet 扩展了 GenericAPIView ，所以通常需要至少提供 queryset 和 serializer_class 属性。例如：
class AccountViewSet(viewsets.ModelViewSet):
"""
用于查看和编辑帐户的简单 ViewSet。
"""
queryset = Account.objects.all()
serializer_class = AccountSerializer
permission_classes = [IsAccountAdminOrReadOnly]
注意，您可以使用 GenericAPIView 提供的任何标准属性或方法重写。例如，要动态确定它应该操作的查询集的 ViewSet，可以这样做：
class AccountViewSet(viewsets.ModelViewSet):
"""
一个简单的视图集，用于查看和编辑与用户相关的帐户。
"""
serializer_class = AccountSerializer
permission_classes = [IsAccountAdminOrReadOnly]
def get_queryset(self):
return self.request.user.accounts.all()
然而注意，当从您的 ViewSet 中移除 queryset 属性，任何关联的路由器将无法自动导出模型的 base_name，因此您必须指定 base_name kwarg 作为路由器注册的一部分。
还要注意，尽管这个类默认情况下提供了完整的创建/列表/检索/更新/销毁操作集，但是可以使用标准权限类来限制可用操作。
ReadOnlyModelViewSet
ReadOnlyModelViewSet 类也继承自 GenericAPIView。与 ModelViewSet 一样，它还包括各种操作的实现，但与 ModelViewSet 不同，它只提供“只读”操作，.list() 和 .retrieve()。
举个栗子
与 ModelViewSet 一样，您通常需要至少提供 queryset 和 serializer_class 属性。例如：
class AccountViewSet(viewsets.ReadOnlyModelViewSet):
"""
用于查看帐户的简单 ViewSet。
"""
queryset = Account.objects.all()
serializer_class = AccountSerializer
同样，与 ModelViewSet 一样，您可以使用 GenericAPIView 可用的任何标准属性和方法重写。
自定义视图集基类
您可能需要提供自定义 ViewSet 类，这些类没有完整的 ModelViewSet 操作集，或者以其他方式自定义行为。
举个栗子
要创建提供 create，list 和 retrieve 操作的基本视图集类，请继承 GenericViewSet，并混合所需的操作：
from rest_framework import mixins
class CreateListRetrieveViewSet(mixins.CreateModelMixin,
mixins.ListModelMixin,
mixins.RetrieveModelMixin,
viewsets.GenericViewSet):
"""
提供“检索”、“创建”和“列表”操作的视图集。
若要使用它，请重写该类并设置 “.queryset” 和 “.serializer_class” 属性。
"""
pass
通过创建自己的基本 ViewSet 类，可以提供在 API 中的多个视图集中重用的通用行为。
浙公网安备 33010602011771号