django--drf-过滤、排序、分页、异常处理、自动生成api说明文档

过滤Filtering

pip install django-filter

注册扩展

配置过滤

REST_FRAMEWORK = {
# 过滤后端
 'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)
}

在视图中添加过滤字段

class BookInfoViewSet(ReadOnlyModelViewSet):
 """使⽤ReadOnlyModelViewSet实现返回列表数据和单⼀数据
 """
 queryset = BookInfo.objects.all()
 serializer_class = serializers.BookInfoSerializer
 # 只有登录⽤户才能访问
 permission_classes = [IsAuthenticated, MyPermission]
 # 过滤字段
 filter_fields = ('btitle', 'bread')

可以多条件查询
eg: 127.0.0.1:8000/books/?btitle=测试put&id=8

排序OrderingFilter

位置

from  rest_framework.filters import OrderingFilter

对于列表数据，REST framework提供了OrderingFilter过滤器来帮助我们快速指明数据按照指定字段进⾏排序

前端可以传递的ordering参数的可选字段值需要在ordering_fields中指明。
eg: 127.0.0.1:8000/books/?ordering=-bread -代表降序

class BookInfoViewSet(ReadOnlyModelViewSet):
 """使⽤ReadOnlyModelViewSet实现返回列表数据和单⼀数据
 """
 queryset = BookInfo.objects.all()
 serializer_class = serializers.BookInfoSerializer
 # 只有登录⽤户才能访问
 permission_classes = [IsAuthenticated, MyPermission]
 # 过滤字段
 filter_fields = ('btitle', 'bread')
 
 # 排序 在类视图中设置filter_backends，使⽤rest_framework.filters.OrderingFilter过滤器
 filter_backends = [OrderingFilter]
 ordering_fields = ('id', 'bread', 'bpub_date')

如果要进行筛选加排序，应该如下

from django_filters.rest_framework import DjangoFilterBackend 
from  rest_framework.pagination import PageNumberPagination

在ordering_fields添加多种方法

分⻚Pagination

eg:http://127.0.0.1:8000/books/?page=1&page_size=2

全局配置

REST_FRAMEWORK = {
 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
 'PAGE_SIZE': 100 # 每⻚数⽬
}

视图中关闭分⻚功能 pagination_class = None

局部配置

class LargeResultsSetPagination(PageNumberPagination):
 """⾃定义分⻚器"""
 page_size = 2 # 每⻚记录条数
 page_size_query_param = 'page_size' # 接受每⻚条数的关键字
 max_page_size = 10 # 每⻚最多记录条数


class BookInfoViewSet(ReadOnlyModelViewSet):
 """使⽤ReadOnlyModelViewSet实现返回列表数据和单⼀数据
 """
 queryset = BookInfo.objects.all()
 serializer_class = serializers.BookInfoSerializer
 # 只有登录⽤户才能访问
 permission_classes = [IsAuthenticated, MyPermission]
 # 过滤字段
 filter_fields = ('btitle', 'bread')
 # 排序
 filter_backends = [OrderingFilter]
 ordering_fields = ('id', 'bread', 'bpub_date')
 # 分⻚
 pagination_class = LargeResultsSetPagination#只能添加一个分页类

可以在⼦类中定义的属性：
• page_size 每⻚数⽬
• page_query_param 前端发送的⻚数关键字名，默认为"page"
• page_size_query_param 前端发送的每⻚数⽬关键字名，默认为None
• max_page_size 前端最多能设置的每⻚数量

偏移分页 LimitOffsetPagination
可以在⼦类中定义的属性：
• default_limit 默认限制，默认值与PAGE_SIZE设置⼀致 默认是2
• limit_query_param limit参数名，默认'limit'
• offset_query_param offset参数名，默认'offset'
• max_limit 最⼤limit限制，默认None

from rest_framework.pagination import LimitOffsetPagination
class BookListView(ListAPIView):
 queryset = BookInfo.objects.all().order_by('id')
 serializer_class = BookInfoSerializer
 pagination_class = LimitOffsetPagination
# 127.0.0.1:8000/books/?offset=3&limit=2 
#offset从第几条开始，limit前端页面显示几条（会受max_page_size显示的限制）

异常处理 Exceptions

rest framework提供了异常处理，但也可以自定义异常处理函数
新建exceptions.py

from rest_framework.views import exception_handler
from rest_framework import status
from django.db import DatabaseError
from rest_framework.response import Response
def custom_exception_handler(exc, context):
 """⾃定义异常
 补充捕获DRF以外的异常信息
 """
 response = exception_handler(exc, context)
 print(exc)
 if response is None:
 if isinstance(exc, DatabaseError):
 response = Response({'detail': '服务器内部错误'}, status=status.HTTP_507_INSUFFICIENT_STORAGE)
 return response

需要在setting中配置

# DRF配置
REST_FRAMEWORK = {
 # 指定⾃定义的异常处理
 'EXCEPTION_HANDLER': 'exceptions.custom_exception_handler'
}

REST framework自带定义的异常
• APIException 所有异常的⽗类
• ParseError 解析错误
• AuthenticationFailed 认证失败
• NotAuthenticated 尚未认证
• PermissionDenied 权限拒绝
• NotFound 未找到
• MethodNotAllowed 请求⽅式不⽀持
• NotAcceptable 要获取的数据格式不⽀持
• Throttled 超过限流次数
• ValidationError 校验失败

⾃动⽣成接⼝⽂档

REST framework可以⾃动帮助我们⽣成接⼝⽂档。
接⼝⽂档以⽹⻚的⽅式呈现。
⾃动接⼝⽂档能⽣成的是继承⾃APIView及其⼦类的视图。

安装依赖包pip install coreapi

设置接⼝⽂档访问路径

from rest_framework.documentation import include_docs_urls
urlpatterns = [
 ...
 url(r'^docs/', include_docs_urls(title='My API title'))
]

多个⽅法的视图，在类视图的⽂档字符串中，分开⽅法定义.

class BookListCreateView(generics.ListCreateAPIView):
 """
 get:
 返回所有图书信息.
 post:
 新建图书.
 """

对于视图集ViewSet，仍在类视图的⽂档字符串中分开定义，但是应使⽤action名称区分

class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
 """
 list:
 返回图书列表数据
 retrieve:
 返回图书详情数据
 latest:
 返回最新的图书数据
 read:
 修改图书的阅读量
 """

新版的restframework需要指定默认schema

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema'
}

补充两点说明：
1） 视图集ViewSet中的retrieve名称，在接⼝⽂档⽹站中叫做read
2）参数的Description需要在序列化器类的字段中以help

写api说明文档的还有swagger扩展 具体用法：> https://www.bbsmax.com/A/qVde1oGndP/
django3 python3 > https://cloud.tencent.com/developer/article/1576613