drf过滤排序分页异常处理
目录
一 过滤Filtering
对于列表数据可能需要根据字段进行过滤，我们可以通过添加django-fitlter扩展来增强支持。
pip install django-filter
DjangoFilterBackend
在配置文件中增加过滤后端的设置：
INSTALLED_APPS = [
...
'django_filters', # 需要注册应用，
]
REST_FRAMEWORK = {
...
'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)
}
在视图中添加filter_fields属性，指定可以过滤的字段
class StudentListView(ListAPIView):
queryset = Student.objects.all()
serializer_class = StudentSerializer
filter_fields = ('age', 'sex')
# 127.0.0.1:8000/four/students/?sex=1
或在视图类中配置
from django_filters.rest_framework import DjangoFilterBackend
class StudentListView(ListAPIView):
queryset = Student.objects.all()
serializer_class = StudentSerializer
filter_backends = [DjangoFilterBackend,]
filter_fields = ('age', 'sex')
SearchFilter(drf自带的过滤器)
from rest_framework.generics import ListAPIView
# OrderingFilter排序、SearchFilter搜索
from rest_framework.filters import OrderingFilter, SearchFilter
class FreeCourseListAPIView(ListAPIView):
queryset = models.Course.objects.filter(is_delete=False, is_show=True).order_by(
"-orders").all()
serializer_class = serializers.FreeCourseModelSerializer
# 局部配置过滤器类
filter_backends = [OrderingFilter, SearchFilter]
# 参与排序的字段: ordering=-price,id,students
ordering_fields = ['price', 'id', 'students']
# 参与搜索的字段: search=python (name字段中带python就ok)
search_fields = ['name', 'brief']
# 携带排序的过滤参数的url: http://127.0.0.1:8000/course/free?ordering=-price 降序
# 携带搜索的过滤参数的url: http://127.0.0.1:8000/course/free?search=python (name字段中带python就ok)
自定义过滤
# filters.py
from rest_framework.filters import BaseFilterBackend
# 自定义过滤器类
class MyFilter(BaseFilterBackend):
# 必须实现filter_queryset方法，返回queryset对象
def filter_queryset(self, request, queryset, view):
# 取出过滤条件
limit = request.query_params.get("limit") # 过滤参数
try:
return queryset[:int(limit)]
except:
return queryset
# views.py
from rest_framework.viewsets import GenericViewSet
from rest_framework.mixins import ListModelMixin
from filters import MyFilter
class CourseView(GenericViewSet, ListModelMixin):
filter_backends = [MyFilter,]
...
from django_filters import FilterSet
from . import models
from django_filters import filters
class CourseFilterSet(FilterSet):
# 区间过滤：field_name关联的Model字段；lookup_expr设置规则；gt是大于，gte是大于等于；
min_price = filters.NumberFilter(field_name='price', lookup_expr='gt')
max_price = filters.NumberFilter(field_name='price', lookup_expr='lt')
class Meta:
model = models.Course
fields = ['course_category', 'students']
# 分类筛选：django-filter：filter_backends配置DjangoFilterBackend，再在filter_fields中配置分组筛选的字段
from django_filters.rest_framework import DjangoFilterBackend
# 自定义过滤器类
from . import filters
class FreeCourseListAPIView(ListAPIView):
queryset = models.Course.objects.filter(is_delete=False, is_show=True).order_by(
"-orders").all()
serializer_class = serializers.FreeCourseModelSerializer
# 局部配置过滤器类
filter_backends = [DjangoFilterBackend]
# 使用基于django-filter自定义过滤器类
filter_class = filters.CourseFilterSet
# 携带分类筛选字段的参数的url: http://127.0.0.1:8000/course/free?min_price=20&max_price=80
二 排序
对于列表数据，REST framework提供了OrderingFilter过滤器来帮助我们快速指明数据按照指定字段进行排序。
使用方法：
在类视图中设置filter_backends，使用rest_framework.filters.OrderingFilter过滤器，REST framework会在请求的查询字符串参数中检查是否包含了ordering参数，如果包含了ordering参数，则按照ordering参数指明的排序字段对数据集进行排序。
前端可以传递的ordering参数的可选字段值需要在ordering_fields中指明。
示例：
from rest_framework.filters import OrderingFilter
class StudentListView(ListAPIView):
queryset = Student.objects.all()
serializer_class = StudentModelSerializer
filter_backends = [OrderingFilter]
ordering_fields = ('id', 'age')
# 127.0.0.1:8000/books/?ordering=-age
# -id 表示针对id字段进行倒序排序
# id 表示针对id字段进行升序排序
如果需要在过滤以后再次进行排序，则需要两者结合!
from rest_framework.generics import ListAPIView
from rest_framework.filters import OrderingFilter
from students.models import Student
from .serializers import StudentModelSerializer
from django_filters.rest_framework import DjangoFilterBackend
class Student3ListView(ListAPIView):
queryset = Student.objects.all()
serializer_class = StudentModelSerializer
filter_fields = ('age', 'sex')
# 因为局部配置会覆盖全局配置,所以需要重新把过滤组件核心类再次声明,
# 否则过滤功能会失效
filter_backends = [OrderingFilter,DjangoFilterBackend]
ordering_fields = ('id', 'age')
三 分页Pagination
REST framework提供了分页的支持。
我们可以在配置文件中设置全局的分页方式，如：
REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
'PAGE_SIZE': 100 # 每页数目
}
也可通过自定义Pagination类，来为视图添加不同分页行为。在视图中通过pagination_clas属性来指明。
class LargeResultsSetPagination(PageNumberPagination):
page_size = 1000
page_size_query_param = 'page_size'
max_page_size = 10000
class BookDetailView(RetrieveAPIView):
queryset = BookInfo.objects.all()
serializer_class = BookInfoSerializer
pagination_class = LargeResultsSetPagination
注意：如果在视图内关闭分页功能，只需在视图内设置
pagination_class = None
可选分页器
1） PageNumberPagination
前端访问网址形式：
GET http://127.0.0.1:8000/students/?page=4
可以在子类中定义的属性：
- page_size 每页数目
- page_query_param 前端发送的页数关键字名，默认为"page"
- page_size_query_param 前端发送的每页数目关键字名，默认为None
- max_page_size 前端最多能设置的每页数量
# 声明分页的配置类
from rest_framework.pagination import PageNumberPagination
class StandardPageNumberPagination(PageNumberPagination):
# 默认每一页显示的数据量
page_size = 2
# 允许客户端通过get参数来控制每一页的数据量
page_size_query_param = "size"
max_page_size = 10
# 自定义页码的参数名
page_query_param = "p"
class StudentAPIView(ListAPIView):
queryset = Student.objects.all()
serializer_class = StudentModelSerializer
pagination_class = StandardPageNumberPagination
# 127.0.0.1/four/students/?p=1&size=5
# APIView
from rest_framework.pagination import PageNumberPagination
# 一 基本使用：url=url=http://127.0.0.1:8000/pager/?page=2&size=3，size无效
class Pager(APIView):
def get(self,request,*args,**kwargs):
# 获取所有数据
ret=models.Book.objects.all()
# 创建分页对象
page=PageNumberPagination()
# 在数据库中获取分页的数据
page_list=page.paginate_queryset(ret,request,view=self)
# 对分页进行序列化
ser=BookSerializer1(instance=page_list,many=True)
return Response(ser.data)
# 二 自定制 url=http://127.0.0.1:8000/pager/?page=2&size=3
# size=30，无效，最多5条
class Mypage(PageNumberPagination):
page_size = 2
page_query_param = 'page'
# 定制传参
page_size_query_param = 'size'
# 最大一页的数据
max_page_size = 5
class Pager(APIView):
def get(self,request,*args,**kwargs):
# 获取所有数据
ret=models.Book.objects.all()
# 创建分页对象
page=Mypage()
# 在数据库中获取分页的数据
page_list=page.paginate_queryset(ret,request,view=self)
# 对分页进行序列化
ser=BookSerializer1(instance=page_list,many=True)
# return Response(ser.data)
# 这个也是返回Response对象，但是比基本的多了上一页，下一页，和总数据条数（了解即可）
return page.get_paginated_response(ser.data)
#ListAPIView
# 声明分页的配置类
from rest_framework.pagination import PageNumberPagination
class StandardPageNumberPagination(PageNumberPagination):
# 默认每一页显示的数据量
page_size = 2
# 允许客户端通过get参数来控制每一页的数据量
page_size_query_param = "size"
max_page_size = 10
# 自定义页码的参数名
page_query_param = "p"
class StudentAPIView(ListAPIView):
queryset = Student.objects.all()
serializer_class = StudentModelSerializer
pagination_class = StandardPageNumberPagination
# 127.0.0.1/four/students/?p=1&size=5
## GenericAPIView
from rest_framework.pagination import PageNumberPagination
class SelfPagination(PageNumberPagination):
page_size = 3
page_size_query_param = "size"
max_page_size = 5
class BookGenericAPIView(GenericAPIView):
book_qs = models.Book.objects.all().filter(is_delete=False)
queryset = book_qs
serializer_class = BookModelSerializer
def get(self, request, *args, **kwargs):
page_obj = SelfPagination()
book_list = page_obj.paginate_queryset(self.book_qs, request, self)
# next_url = page_obj.get_next_link()
# pr_url = page_obj.get_previous_link()
pk = kwargs.get('pk')
if pk:
ser = self.serializer_class(self.get_object())
else:
ser = self.serializer_class(book_list, many=True)
return RespUtil(data=ser.data)
2）LimitOffsetPagination
前端访问网址形式：
GET http://127.0.0.1/four/students/?limit=100&offset=400
可以在子类中定义的属性：
- default_limit 默认限制，默认值与
PAGE_SIZE设置一直 - limit_query_param limit参数名，默认'limit'
- offset_query_param offset参数名，默认'offset'
- max_limit 最大limit限制，默认None
from rest_framework.pagination import LimitOffsetPagination
class StandardLimitOffsetPagination(LimitOffsetPagination):
# 默认每一页查询的数据量,类似上面的page_size
default_limit = 2
limit_query_param = "size"
offset_query_param = "start"
class StudentAPIView(ListAPIView):
queryset = Student.objects.all()
serializer_class = StudentModelSerializer
# 调用页码分页类
# pagination_class = StandardPageNumberPagination
# 调用查询偏移分页类
pagination_class = StandardLimitOffsetPagination
# APIView
# http://127.0.0.1:8000/pager/?offset=4&limit=3
from rest_framework.pagination import LimitOffsetPagination
# 也可以自定制，同简单分页
class Pager(APIView):
def get(self,request,*args,**kwargs):
# 获取所有数据
ret=models.Book.objects.all()
# 创建分页对象
page=LimitOffsetPagination()
# 在数据库中获取分页的数据
page_list=page.paginate_queryset(ret,request,view=self)
# 对分页进行序列化
ser=BookSerializer1(instance=page_list,many=True)
# return page.get_paginated_response(ser.data)
return Response(ser.data)
#ListAPIView
from rest_framework.pagination import LimitOffsetPagination
class StandardLimitOffsetPagination(LimitOffsetPagination):
# 默认每一页查询的数据量,类似上面的page_size
default_limit = 2
limit_query_param = "size"
offset_query_param = "start"
class StudentAPIView(ListAPIView):
queryset = Student.objects.all()
serializer_class = StudentModelSerializer
# 调用页码分页类
# pagination_class = StandardPageNumberPagination
# 调用查询偏移分页类
pagination_class = StandardLimitOffsetPagination
3）CursorPagination
前端访问网址形式：
GET http://127.0.0.1/four/students/?cursor=cD0xNQ%3D%3D
可以在子类中定义的属性：
- cursor_query_param:默认查询字段，不需要修改
- page_size：每页数目
- ordering：按什么排序，需要指定
#APIView
from rest_framework.pagination import CursorPagination
# 看源码，是通过sql查询，大于id和小于id
class Pager(APIView):
def get(self,request,*args,**kwargs):
# 获取所有数据
ret=models.Book.objects.all()
# 创建分页对象
page=CursorPagination()
page.ordering='nid'
# 在数据库中获取分页的数据
page_list=page.paginate_queryset(ret,request,view=self)
# 对分页进行序列化
ser=BookSerializer1(instance=page_list,many=True)
# 可以避免页码被猜到
return page.get_paginated_response(ser.data)
# ListAPIView
class MyCursorPagination(CursorPagination):
page_size=2
ordering='-id'
from rest_framework.generics import ListAPIView
class AuthorListView(ListAPIView):
serializer_class = serializers.AuthorModelSerializer
queryset = models.Author.objects.filter(is_delete=False)
pagination_class =MyCursorPagination
from rest_framework.pagination import PageNumberPagination,LimitOffsetPagination,CursorPagination
class MyPageNumberPagination(PageNumberPagination):
page_size = 2
page_query_param = 'page'
# 定制传参
page_size_query_param = 'size'
# 最大一页的数据
max_page_size = 5
class MyLimitOffsetPagination(LimitOffsetPagination):
default_limit = 2
# 最大一页的数据
max_limit = 5
class MyCursorPagination(CursorPagination):
page_size=2
ordering='-id'
from rest_framework.generics import ListAPIView
class AuthorListView(ListAPIView):
serializer_class = serializers.AuthorModelSerializer
queryset = models.Author.objects.filter(is_delete=False)
pagination_class =MyCursorPagination
四 异常处理 Exceptions
REST framework提供了异常处理,但返回的格式不符合我们要求,我们可以自定义异常处理函数。
from rest_framework.views import exception_handler
def custom_exception_handler(exc, context):
# 先调用REST framework默认的异常处理方法获得标准错误响应对象
response = exception_handler(exc, context)
# 在此处补充自定义的异常处理
if response is None:
response.data['status_code'] = response.status_code
return response
在配置文件中声明自定义的异常处理
REST_FRAMEWORK = {
'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
}
如果未声明，会采用默认的方式，如下
rest_frame/settings.py
REST_FRAMEWORK = {
'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
}
例如：
补充上处理关于数据库的异常
from rest_framework.views import exception_handler as drf_exception_handler
from rest_framework import status
from django.db import DatabaseError
def exception_handler(exc, context):
response = drf_exception_handler(exc, context)
if response is None:
view = context['view']
if isinstance(exc, DatabaseError):
print('[%s]: %s' % (view, exc))
response = Response({'detail': '服务器内部错误'}, status=status.HTTP_507_INSUFFICIENT_STORAGE)
return response
REST framework定义的异常
- APIException 所有异常的父类
- ParseError 解析错误
- AuthenticationFailed 认证失败
- NotAuthenticated 尚未认证
- PermissionDenied 权限决绝
- NotFound 未找到
- MethodNotAllowed 请求方式不支持
- NotAcceptable 要获取的数据格式不支持
- Throttled 超过限流次数
- ValidationError 校验失败
也就是说，很多的没有在上面列出来的异常，就需要我们在自定义异常中自己处理了。
五 自动生成接口文档
REST framework可以自动帮助我们生成接口文档。
接口文档以网页的方式呈现。
自动接口文档能生成的是继承自APIView及其子类的视图。
8.1. 安装依赖
REST framewrok生成接口文档需要coreapi库的支持。
pip install coreapi
8.2. 设置接口文档访问路径
在总路由中添加接口文档路径。
文档路由对应的视图配置为rest_framework.documentation.include_docs_urls，
参数title为接口文档网站的标题。
from rest_framework.documentation import include_docs_urls
urlpatterns = [
...
path('docs/', include_docs_urls(title='站点页面标题'))
]
8.3. 文档描述说明的定义位置
1） 单一方法的视图，可直接使用类视图的文档字符串，如
class BookListView(generics.ListAPIView):
"""
返回所有图书信息.
"""
2）包含多个方法的视图，在类视图的文档字符串中，分开方法定义，如
class BookListCreateView(generics.ListCreateAPIView):
"""
get:
返回所有图书信息.
post:
新建图书.
"""
3）对于视图集ViewSet，仍在类视图的文档字符串中封开定义，但是应使用action名称区分，如
class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
"""
list:
返回图书列表数据
retrieve:
返回图书详情数据
latest:
返回最新的图书数据
read:
修改图书的阅读量
"""
8.4. 访问接口文档网页
浏览器访问 127.0.0.1:8000/docs/，即可看到自动生成的接口文档。
两点说明：
1） 视图集ViewSet中的retrieve名称，在接口文档网站中叫做read
2）参数的Description需要在模型类或序列化器类的字段中以help_text选项定义，如：
class Student(models.Model):
...
age = models.IntegerField(default=0, verbose_name='年龄', help_text='年龄')
...
或
class StudentSerializer(serializers.ModelSerializer):
class Meta:
model = Student
fields = "__all__"
extra_kwargs = {
'age': {
'required': True,
'help_text': '年龄'
}
}
