基于函数的视图、基于类的视图的使用,见Django Rest Framework:进一步理解序列化之基于函数的视图和Django Rest Framework:进一步理解序列化之基于类的视图。
这里有关于一、三的简单使用示例:用Django Rest Framework实现豆瓣API。
一,通用视图API Reference
1,GenericAPIView
该类扩展了REST framework 的 APIView
类,为标准列表和详细视图添加了通常所需的行为。
每个具体的通用视图都是通过将 GenericAPIView
类和一个或多个 minxin
类相互结合来构建的。
1,属性:
基本设置:
queryset
—— 用于从该视图返回对象的查询集。通常,您必须设置此属性,或重写get_queryset()
方法。如果您正在重写视图方法,那么重要的是调用 get_queryset(),而不是直接访问此属性,因为 queryset 将被评估一次,并且这些结果将被缓存用于所有后续请求。serializer_class
—— 用于验证和反序列化输入以及序列化输出的序列化类。通常,您必须设置此属性,或重写get_serializer_class()
方法lookup_field
—— 应该用于执行单个模型实例的对象查找的模型字段。默认为 ‘pk’。注意,在使用超链接 API 时,如果需要使用自定义值,则需要确保 API 视图和序列化器类都设置查找字段。lookup_url_kwarg
—— 用于对象查找的 URL 关键字参数。URL conf 应该包含与此值相对应的关键字参数。如果取消设置默认值,使用与 lookup_field 相同的值。
分页:
与列表视图一起使用时,以下属性用于控制分页。pagination_class
—— 在对列表结果进行分页时应该使用的分页类。默认为与 DEFAULT_PAGINATION_CLASS 设置相同的值,即 ‘rest_framework.pagination.PageNumberPagination’,需要在settings.py中进行如下配置。设置 pagination_class = None 将禁用此视图的分页。
# 分页设置
REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
# 每页显示多少条数据
'PAGE_SIZE': 2
}
过滤:
filter_backends
—— 用于过滤查询集的过滤后端类列表。默认值与 DEFAULT_FILTER_BACKENDS设置的值相同。
2,方法
基本方法:
get_queryset(self)
返回用于列表视图的查询集,并用作详细视图中查询的基础。默认返回 queryset 属性指定的查询集。
应该始终使用此方法,而不是直接访问 self.queryset,因为 self.queryset 只被评估一次,并且这些结果将被缓存用于所有后续请求。
可以重写来提供动态行为,例如返回查询集,这是针对请求的用户所特有的。
def get_queryset(self):
user = self.request.user
return user.accounts.all()
get_object(self)
返回用于详细视图的对象实例。默认使用 lookup_field 参数来过滤基本查询集。
可以重写以提供更复杂的行为,例如基于多个 URL kwarg 的对象查找。
如果 API 不包含任何对象级权限,您可以选择性地排除 self.check_object_permissions,并简单地从 get_object_or_404 查找中返回对象。
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_permissions(self.request, obj)
return obj
- 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_destroy(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)
其他方法:
通常不需要重写以下方法,但使用 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)
—— 根据需要为查询集分页,或者返回一个页面对象;如果没有为该视图配置分页,则为 None。
pg = PageNumberPagination()
p = pg.paginate_queryset(queryset=q, request=request)
# 将分页后的数据传递MySerializer,生成JSON数据对象
serializer = MySerializer(instance=p, many=True)
filter_queryset(self, queryset)
—— 给定一个查询集,使用任何后端过滤器进行过滤,返回一个新的查询集。
2,Mixins类
mixin 类
提供用于提供基本视图行为的操作。请注意,mixin 类提供了操作方法,而不是直接定义处理方法,如 .get() 和 .post()。这允许更灵活的行为组合。
mixin 类可以从 rest_framework.mixins
导入。
1,ListModelMixin
:
提供 .list(request,*args,**kwargs) 方法
,它实现列出查询集。
如果填充了查询集,则返回 200 OK 响应,并将查询集的序列化表示作为响应的主体。响应数据可以选择分页。
2,CreateModelMixin
:
提供 .create(request,* args,** kwargs)
方法,用于实现创建和保存新模型实例。
如果对象被创建,则返回一个 201 Created 响应,并将该对象的序列化表示形式作为响应的主体。如果该表示包含名为 url 的键,则响应的 Location header 将填充该值。
如果为创建对象而提供的请求数据无效,则将返回 400 Bad Request 响应,并将错误详细信息作为响应的主体。
**
就像之前用到的那样,将HTTP的请求处理绑定到具体方法就可以了。
**
class SnippetList(mixins.ListModelMixin,
mixins.CreateModelMixin,
generics.GenericAPIView):
queryset = Snippet.objects.all()
serializer_class = SnippetSerializer
def get(self, request, *args, **kwargs):
return self.list(request, *args, **kwargs)
def post(self, request, *args, **kwargs):
return self.create(request, *args, **kwargs)
3,RetrieveModelMixin
:
提供 .retrieve(request,* args,** kwargs)
方法,用于实现在响应中返回现有模型实例。
如果可以检索对象,则返回一个 200 OK 响应,并将对象的序列化表示作为响应的主体。否则它将返回 404 Not Found。
4,UpdateModelMixin
:
提供 .update(request,* args,** kwargs)
方法,用于实现更新和保存现有模型实例。
还提供了 .partial_update(request,* args,** kwargs) 方法,该方法与 update 方法类似,不同之处在于更新的所有字段都是可选的。这允许支持 HTTP PATCH 请求。
如果对象被更新,则返回 200 OK 响应,并将对象的序列化表示作为响应的主体。
如果为更新对象而提供的请求数据无效,则将返回 400 Bad Request 响应,并将错误详细信息作为响应的主体。
5,DestroyModelMixin
:
提供 .destroy(request,* args,** kwargs)
方法,用于实现对现有模型实例的删除。
如果对象被删除,则返回 204 No Content,否则它将返回 404 Not Found。
**
同样的使用方法
**
class SnippetDetail(mixins.RetrieveModelMixin,
mixins.UpdateModelMixin,
mixins.DestroyModelMixin,
generics.GenericAPIView):
queryset = Snippet.objects.all()
serializer_class = SnippetSerializer
def get(self, request, *args, **kwargs):
return self.retrieve(request, *args, **kwargs)
def put(self, request, *args, **kwargs):
return self.update(request, *args, **kwargs)
def delete(self, request, *args, **kwargs):
return self.destroy(request, *args, **kwargs)
3,具体视图类 (Concrete View Classes)
以下类是具体的通用视图。如果你使用通用视图,这通常是你要工作的级别,除非你需要大量定制的行为。
可以从 rest_framework.generics
导入具体视图类。
CreateAPIView
用于仅创建端点。
提供 post 方法处理程序。
扩展:GenericAPIView,CreateModelMixinListAPIView
用只读端点表示模型实例的集合。
提供 get 方法处理程序。
扩展:GenericAPIView,ListModelMixinRetrieveAPIView
用只读端点表示单个模型实例。
提供 get 方法处理程序。
扩展:GenericAPIView, RetrieveModelMixinDestroyAPIView
用于仅删除单个模型实例的端点。
提供 delete 方法处理程序。
扩展:GenericAPIView, DestroyModelMixinUpdateAPIView
用于只更新单个模型实例的端点。
提供 put 和 patch 方法处理程序。
扩展:GenericAPIView, UpdateModelMixinListCreateAPIView
用读写端点来表示模型实例的集合。
提供 get 和 post 方法处理程序。
扩展:GenericAPIView, ListModelMixin, CreateModelMixinRetrieveUpdateAPIView
用于读取或更新端点以表示单个模型实例。
提供 get,put 和 patch 方法处理程序。
扩展:GenericAPIView, RetrieveModelMixin, UpdateModelMixinRetrieveDestroyAPIView
用于读取或删除端点以表示单个模型实例。
提供 get 和 delete 方法处理程序。
扩展:GenericAPIView, RetrieveModelMixin, DestroyModelMixinRetrieveUpdateDestroyAPIView
用于读写删除端点以表示单个模型实例。
提供 get ,put,patch 和 delete 方法处理程序。
扩展:GenericAPIView, RetrieveModelMixin, UpdateModelMixin,
DestroyModelMixin
二,自定义通用视图
1,创建自定义 mixins
例如,如果您需要根据 URL conf 中的多个字段查找对象,则可以创建如下所示的 mixin 类:
class MultipleFieldLookupMixin(object):
"""
将此 mixin 应用于任何视图或视图集,以基于`lookup_fields`属性获得多个字段过滤,而不是默认的单字段过滤。
"""
def get_object(self):
queryset = self.get_queryset() # 获取基本查询集
queryset = self.filter_queryset(queryset) # 应用过滤器
filter = {
}
for field in self.lookup_fields:
if self.kwargs[field]: # 忽略空字段
filter[field] = self.kwargs[field]
obj = get_object_or_404(queryset, **filter) # 查找对象
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')
2,创建自定义基类
如果要在多个视图中使用 mixin,则可以更进一步,创建自己的一组基本视图,然后可以在整个项目中使用。例如:
class BaseRetrieveView(MultipleFieldLookupMixin,
generics.RetrieveAPIView):
pass
class BaseRetrieveUpdateDestroyView(MultipleFieldLookupMixin,
generics.RetrieveUpdateDestroyAPIView):
pass
三,视图集
Django REST framework 允许您将一组相关视图的逻辑组合在一个单独的类中,称为 ViewSet
。
ViewSet 类只是一种基于类的视图类型,它不提供任何方法处理程序,如 .get() 或 .post(),而是提供诸如 .list()
和 .create()
之类的操作。
1,一个例子
定义一个简单的视图集,可用于列出或检索系统中的所有用户:
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()
通过上面的例子,可以知道,与使用 View 类相比,使用ViewSet有两个主要优点:
- 重复的逻辑可以组合成一个类。在上面的示例中,我们只需要指定一次 queryset,它将在多个视图中使用。
- 通过使用 routers,我们不再需要处理自己的 URL 连接。
2,视图集操作
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
3,反思视图集操作
在调度期间,ViewSet 上提供了以下属性。
basename
—— 用于创建的 URL 的基础名称。action
—— 当前操作的名称 (例如,list,create)。detail
—— 布尔值指示当前动作是否配置为列表或详细视图。suffix
—— 视图集类型的显示后缀 - 反射详细属性。
可以检查这些属性以根据当前操作调整行为。例如,可以限制除了与 list 类似的所有权限:
"""
实例化并返回该视图所需的权限列表。
"""
if self.action == 'list':
permission_classes = [IsAuthenticated]
else:
permission_classes = [IsAdmin]
return [permission() for permission in permission_classes]
4,标记路由的额外操作
如果有可路由的特殊方法,可以用 @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()
方法。
5,反转操作 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 Reference
1,ViewSet
ViewSet 类
继承自 APIView
。您可以使用任何标准属性 (例如 permission_classes,authentication_classes) 来控制视图集上的 API 策略。
ViewSet 类不提供任何操作的实现。为了使用 ViewSet 类,您将重写该类并显式地定义操作的实现。
2,GenericViewSet
GenericViewSet 类
继承自 GenericAPIView
,并提供默认的 get_object,get_queryset 方法和其他通用视图基本行为,但默认情况下不包含任何操作。
为了使用 GenericViewSet 类,您将重写该类,或混合所需的 mixin 类,或者显式定义操作实现。
3,ModelViewSet
ModelViewSet 类
继承自 GenericAPIView
,并通过混合各种 mixin 类
的行为来包含各种操作的实现。
ModelViewSet 类提供的操作有:.list(),.retrieve(),.create(),.update(),.partial_update() 和 .destroy()。
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
作为路由器注册的一部分。
4,ReadOnlyModelViewSet
ReadOnlyModelViewSet 类
也继承自 GenericAPIView
。与 ModelViewSet 一样,它还包括各种操作的实现,但与 ModelViewSet 不同,它只提供“只读”操作、.list()
和 .retrieve()
。
class AccountViewSet(viewsets.ReadOnlyModelViewSet):
"""
用于查看帐户的简单 ViewSet。
"""
queryset = Account.objects.all()
serializer_class = AccountSerializer