• 视图集
    • 举个栗子
    • 操作视图集
    • 标记额外的路由行为
    • action 跳转
  • API 参考
    • ViewSet
    • GenericViewSet
    • ModelViewSet
    • ReadOnlyModelViewSet
  • 自定义视图集基类

    官方原文链接

    视图集

    在路由决定了哪个控制器用于请求后，控制器负责理解请求并产生适当的输出。
    — Ruby on Rails 文档

    Django REST framework 允许将一组相关视图的逻辑组合到一个称为 ViewSet 的类中。在其他框架中，您可能会发现概念上类似的实现，名为 “Resources” 或 “Controllers” 。

    ViewSet 类只是一种基于类的 View，它不提供任何处理方法，如 .get() 或 .post()，而是提供诸如 .list() 和 .create() 之类的操作。

    ViewSet 只在用 .as_view() 方法绑定到最终化视图时做一些相应操作。

    通常，不是在 urlconf 中的视图集中明确注册视图，而是使用路由器类注册视图集，这会自动为您确定 urlconf。

    举个栗子

    定义一个简单的视图集，可以用来列出或检索系统中的所有用户。 

    1. from django.contrib.auth.models import User
    2. from django.shortcuts import get_object_or_404
    3. from myapps.serializers import UserSerializer
    4. from rest_framework import viewsets
    5. from rest_framework.response import Response
    7. class UserViewSet(viewsets.ViewSet):
    9.     def list(self, request):
    10.         queryset = User.objects.all()
    11.         serializer = UserSerializer(queryset, many=True)
    12.         return Response(serializer.data)
    14.     def retrieve(self, request, pk=None):
    15.         queryset = User.objects.all()
    16.         user = get_object_or_404(queryset, pk=pk)
    17.         serializer = UserSerializer(user)
    18.         return Response(serializer.data)

    如果需要，可以将这个视图集合成两个单独的视图，如下所示：

    1. user_list = UserViewSet.as_view({'get': 'list'})
    2. user_detail = UserViewSet.as_view({'get': 'retrieve'})

    通常情况下，我们不会这样做，而是用路由器注册视图集，并允许自动生成 urlconf。

    1. from myapp.views import UserViewSet
    2. from rest_framework.routers import DefaultRouter
    4. router = DefaultRouter()
    5. router.register(r'users', UserViewSet, base_name='user')
    6. urlpatterns = router.urls

    不用自己编写视图集，通常使用默认提供的现有基类。例如：

    1. class UserViewSet(viewsets.ModelViewSet):
    2.     """
    3.     用于查看和编辑用户实例的视图。
    4.     """
    5.     serializer_class = UserSerializer
    6.     queryset = User.objects.all()

    使用 ViewSet 类比使用 View 类有两个主要优点。

    • 重复的逻辑可以合并成一个类。在上面的例子中，我们只需要指定一次查询集，它将在多个视图中使用。
    • 通过使用 routers，我们不再需要处理自己的 URL 配置。

    这两者各有优缺点。使用常规视图和 URL 配置文件更加明确，并为您提供更多控制。如果想要更快速的开发出一个应用，或者需要使大型 API 的 URL 配置始终保持一致，视图集会非常有用。

    操作视图集

    REST framework 中包含的默认 routes 将为一组标准的 create / retrieve / update / destroy 风格 action 提供路由，如下所示：

    1. class UserViewSet(viewsets.ViewSet):
    2.     """
    3.     这些方法将由路由器负责处理。
    5.     如果要使用后缀，请确保加上 `format = None` 关键字参数
    6.     """
    8.     def list(self, request):
    9.         pass
    11.     def create(self, request):
    12.         pass
    14.     def retrieve(self, request, pk=None):
    15.         pass
    17.     def update(self, request, pk=None):
    18.         pass
    20.     def partial_update(self, request, pk=None):
    21.         pass
    23.     def destroy(self, request, pk=None):
    24.         pass

    在调度期间，当前 action 的名称可以通过 .action 属性获得。您可以检查 .action 以根据当前 action 调整行为。

    例如，您可以将权限限制为只有 admin 才能访问 list 以外的其他 action，如下所示：

    1. def get_permissions(self):
    2.     """
    3.     实例化并返回此视图所需的权限列表。
    4.     """
    5.     if self.action == 'list':
    6.         permission_classes = [IsAuthenticated]
    7.     else:
    8.         permission_classes = [IsAdmin]
    9.     return [permission() for permission in permission_classes]

    标记额外的路由行为

    如果需要路由特定方法，则可以用 @detail_route 或 @list_route 装饰器进行修饰。

    @detail_route 装饰器在其 URL 模式中包含 pk，用于支持需要获取单个实例的方法。@list_route 修饰器适用于在对象列表上操作的方法。

    举个栗子：

    1. from django.contrib.auth.models import User
    2. from rest_framework import status
    3. from rest_framework import viewsets
    4. from rest_framework.decorators import detail_route, list_route
    5. from rest_framework.response import Response
    6. from myapp.serializers import UserSerializer, PasswordSerializer
    8. class UserViewSet(viewsets.ModelViewSet):
    9.     """
    10.     提供标准操作的视图集
    11.     """
    12.     queryset = User.objects.all()
    13.     serializer_class = UserSerializer
    15.     @detail_route(methods=['post'])
    16.     def set_password(self, request, pk=None):
    17.         user = self.get_object()
    18.         serializer = PasswordSerializer(data=request.data)
    19.         if serializer.is_valid():
    20.             user.set_password(serializer.data['password'])
    21.             user.save()
    22.             return Response({'status': 'password set'})
    23.         else:
    24.             return Response(serializer.errors,
    25.                             status=status.HTTP_400_BAD_REQUEST)
    27.     @list_route()
    28.     def recent_users(self, request):
    29.         recent_users = User.objects.all().order('-last_login')
    31.         page = self.paginate_queryset(recent_users)
    32.         if page is not None:
    33.             serializer = self.get_serializer(page, many=True)
    34.             return self.get_paginated_response(serializer.data)
    36.         serializer = self.get_serializer(recent_users, many=True)
    37.         return Response(serializer.data)

    另外，装饰器可以为路由视图设置额外的参数。例如…

    1.     @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf])
    2.     def set_password(self, request, pk=None):
    3.        ...

    这些装饰器默认路由 GET 请求，但也可以使用 methods 参数接受其他 HTTP 方法。例如：

    1.     @detail_route(methods=['post', 'delete'])
    2.     def unset_password(self, request, pk=None):
    3.        ...

    这两个新操作将在 urls ^users/{pk}/set_password/$ 和 ^users/{pk}/unset_password/$ 上。

    action 跳转

    如果你需要获取 action 的 URL ，请使用 .reverse_action() 方法。这是 .reverse() 的一个便捷包装，它会自动传递视图的请求对象，并将 url_name 与 .basename 属性挂接。

    请注意，basename 是在 ViewSet 注册过程中由路由器提供的。如果您不使用路由器，则必须提供.as_view() 方法的 basename 参数。

    使用上一节中的示例：

    1. >>> view.reverse_action('set-password', args=['1'])
    2. 'http://localhost:8000/api/users/1/set_password'

    url_name 参数应该与 @list_route 和 @detail_route 装饰器的相同参数匹配。另外，这可以用来反转默认 list 和 detail 路由。

    API 参考

    ViewSet

    ViewSet 类继承自 APIView。您可以使用任何标准属性（如 permission_classes，authentication_classes）来控制视图上的 API 策略。

    ViewSet 类不提供任何 action 的实现。为了使用 ViewSet 类，必须继承该类并明确定义 action 实现。

    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 属性。例如：

    1. class AccountViewSet(viewsets.ModelViewSet):
    2.     """
    3.     用于查看和编辑 Account
    4.     """
    5.     queryset = Account.objects.all()
    6.     serializer_class = AccountSerializer
    7.     permission_classes = [IsAccountAdminOrReadOnly]

    请注意，您可以覆盖 GenericAPIView 提供的任何标准属性或方法。例如，要动态确定它应该操作的查询集的ViewSet，可以这样做：

    1. class AccountViewSet(viewsets.ModelViewSet):
    2.     """
    3.     A simple ViewSet for viewing and editing the accounts
    4.     associated with the user.
    5.     """
    6.     serializer_class = AccountSerializer
    7.     permission_classes = [IsAccountAdminOrReadOnly]
    9.     def get_queryset(self):
    10.         return self.request.user.accounts.all()

    但请注意，从 ViewSet 中删除 queryset 属性后，任何关联的 router 将无法自动导出模型的 base_name，因此您必须将 base_name kwarg 指定为 router 注册的一部分。

    还要注意，虽然这个类默认提供了完整的 create / list / retrieve / update / destroy 操作集，但您可以通过使用标准权限类来限制可用操作。

    ReadOnlyModelViewSet

    ReadOnlyModelViewSet 类也从 GenericAPIView 继承。与 ModelViewSet 一样，它也包含各种操作的实现，但与 ModelViewSet 不同的是它只提供 “只读” 操作，.list() 和 .retrieve()。

    举个栗子：

    与 ModelViewSet 一样，您通常需要提供至少 queryset 和 serializer_class 属性。例如：

    1. class AccountViewSet(viewsets.ReadOnlyModelViewSet):
    2.     """
    3.     A simple ViewSet for viewing accounts.
    4.     """
    5.     queryset = Account.objects.all()
    6.     serializer_class = AccountSerializer

    同样，与 ModelViewSet 一样，您可以覆盖GenericAPIView 可用的任何标准属性和方法。

    自定义视图集基类

    您可能需要使用没有完整 ModelViewSet 操作集的自定义 ViewSet 类，或其他自定义行为。

    举个栗子：

    要创建提供 create， list 和 retrieve 操作的基本视图集类，请从 GenericViewSet 继承，并混合（mixin ）所需的操作：

    1. from rest_framework import mixins
    3. class CreateListRetrieveViewSet(mixins.CreateModelMixin,
    4.                                 mixins.ListModelMixin,
    5.                                 mixins.RetrieveModelMixin,
    6.                                 viewsets.GenericViewSet):
    7.     """
    8.     A viewset that provides `retrieve`, `create`, and `list` actions.
    10.     To use it, override the class and set the `.queryset` and
    11.     `.serializer_class` attributes.
    12.     """
    13.     pass

    通过创建自己的基本 ViewSet 类，能够提供可在 API 中的多个视图集中重用的常见行为。