Django REST Framework教程(8): 分页(Pagination)详解

在前面的DRF系列教程中，我们以博客为例介绍了序列化器, 使用基于类的视图APIView和ModelViewSet开发了针对文章资源进行增删查改的完整API端点，并详细对权限和认证(含jwt认证)进行了总结与演示。在本篇文章中我们将向你演示如何在Django REST Framework中使用分页。

分页

为什么要分页? 当你的数据库数据量非常大时，如果一次将这些数据查询出来, 必然加大了服务器内存的负载,降低了系统的运行速度。一种更好的方式是将数据分段展示给用户。如果用户在展示的分段数据中没有找到自己的内容，可以通过指定页码或翻页的方式查看更多数据，直到找到自己想要的内容为止。

Django REST Framework提供3种分页类，接下来我们会分别进行演示。

• PageNumberPagination类：简单分页器。支持用户按?page=3这种方式查询，你可以通过page_size这个参数手动指定每页展示给用户数据的数量。它还支持用户按?page=3&size=10这种更灵活的方式进行查询，这样用户不仅可以选择页码，还可以选择每页展示数据的数量。对于第二种情况，你通常还需要设置max_page_size这个参数限制每页展示数据的最大数量，以防止用户进行恶意查询(比如size=10000), 这样一页展示1万条数据将使分页变得没有意义。

• LimitOffsetPagination类：偏移分页器。支持用户按?limit=20&offset=100这种方式进行查询。offset是查询数据的起始点，limit是每页展示数据的最大条数，类似于page_size。当你使用这个类时，你通常还需要设置max_limit这个参数来限制展示给用户数据的最大数量。

• CursorPagination类：加密分页器。这是DRF提供的加密分页查询，仅支持用户按响应提供的上一页和下一页链接进行分页查询，每页的页码都是加密的。使用这种方式进行分页需要你的模型有"created"这个字段，否则你要手动指定ordering排序才能进行使用。

使用PageNumberPagination类

DRF中使用默认分页类的最简单方式就是在settings.py中进行全局配置，如下所示：

REST_FRAMEWORK ={
    'DEFAULT_PAGINATION_CLASS':'rest_framework.pagination.PageNumberPagination',
'PAGE_SIZE':2
}

展示效果如下，每页展示两条记录, 不支持用户指定每页展示数据的数量。

但是如果你希望用户按?page=3&size=10这种更灵活的方式进行查询，你就要进行个性化定制。在实际开发过程中，定制比使用默认的分页类更常见，具体做法如下。

第一步: 在app目录下新建pagination.py, 添加如下代码：

#blog/pagination.py

from rest_framework.pagination import PageNumberPagination


class MyPageNumberPagination(PageNumberPagination):
    page_size = 2   # default page size
    page_size_query_param = 'size'  # ?page=xx&size=??
    max_page_size = 10 # max page size

我们自定义了一个MyPageNumberPagination类，该类继承了PageNumberPagination类。我们通过page_size设置了每页默认展示数据的条数，通过page_size_query_param设置了每页size的参数名以及通过max_page_size设置了每个可以展示的最大数据条数。

第二步：使用自定义的分页类

在基于类的视图中，你可以使用pagination_class这个属性使用自定义的分页类，如下所示：

from rest_framework import viewsets
from .pagination import MyPageNumberPagination




class ArticleViewSet(viewsets.ModelViewSet):
    # 用一个视图集替代ArticleList和ArticleDetail两个视图
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    pagination_class = MyPageNumberPagination




    # 自行添加，将request.user与author绑定
    def perform_create(self, serializer):
        serializer.save(author=self.request.user)


    # 自行添加，将request.user与author绑定
    def perform_update(self, serializer):
        serializer.save(author=self.request.user)

展示效果如下所示：

当然定制分页类不限于指定page_size和max_page_size这些属性，你还可以改变响应数据的输出格式。比如我们这里希望把next和previous放在一个名为links的key里，我们可以修改MyPageNumberPagination类，重写get_paginated_response方法：

from rest_framework.pagination import PageNumberPagination
from rest_framework.response import Response




class MyPageNumberPagination(PageNumberPagination):
    page_size = 2   # default page size
    page_size_query_param = 'size'  # ?page=xx&size=??
    max_page_size = 10 # max page size
    def get_paginated_response(self, data):
        return Response({
            'links': {
                'next': self.get_next_link(),
                'previous': self.get_previous_link()
            },
            'count': self.page.paginator.count,
            'results': data
        })

新的展示效果如下所示：

注意：重写get_paginated_response方法非常有用，你还可以给分页响应数据传递额外的内容，比如code状态码等等。

前面的例子中我们只在单个基于类的视图或视图集中使用到了分页类，你还可以修改settings.py全局使用你自定义的分页类，如下所示。展示效果是一样的，我们就不详细演示了。

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'blog.pagination.MyPageNumberPagination',
}

使用LimitOffsetPagination类

使用这个分页类最简单的方式就是在settings.py中进行全局配置，如下所示：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination'
}

展示效果如下所示，从第6条数据查起，每页展示2条。

你也可以自定义MyLimitOffsetPagination类，在单个视图或视图集中使用，或者全局使用。

from rest_framework.pagination import LimitOffsetPagination


class MyLimitOffsetPagination(LimitOffsetPagination):
    default_limit = 5   # default limit per age
    limit_query_param = 'limit'  # default is limit
    offset_query_param = 'offset'  # default param is offset
    max_limit = 10 # max limit per age

使用CursorPagination类

全局使用

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.CursorPagination',
    'PAGE_SIZE': 2
}

展示效果如下所示：

什么? 为什么会出错误? 使用CursorPagination类需要你的模型里有created这个字段，否则你需要手动指定ordering字段。这是因为CursorPagination类只能对排过序的查询集进行分页展示。我们的Article模型只有create_date字段，没有created这个字段，所以会报错。

为了解决这个问题，我们需要自定义一个MyCursorPagination类，手动指定按create_date排序, 如下所示：

#blog/pagination.py

from rest_framework.pagination import CursorPagination


class MyArticleCursorPagination(CursorPagination):
    page_size = 3 # Default number of records per age
    page_size_query_param = 'page_size' 
    cursor_query_param = 'cursor' # Default is cursor
    ordering = '-create_date'

修改settings.py, 使用自己定义的分页类。

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'blog.pagination.MyArticleCursorPagination',
}

响应效果如下所示，你将得到previous和next分页链接。页码都加密了, 链接里不再显示页码号码。默认每页展示3条记录, 如果使用?page_size=2进行查询，每页你将得到两条记录。

当然由于这个ordering字段与模型相关，我们并不推荐全局使用自定义的CursorPagination类，更好的方式是在GenericsAPIView或视图集viewsets中通过pagination_class属性指定，如下所示：

from rest_framework import viewsets
from .pagination import  MyArticleCursorPagination




class ArticleViewSet(viewsets.ModelViewSet):
    # 用一个视图集替代ArticleList和ArticleDetail两个视图
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    pagination_class = MyArticleCursorPagination
    # 自行添加，将request.user与author绑定
    def perform_create(self, serializer):
        serializer.save(author=self.request.user)


    # 自行添加，将request.user与author绑定
    def perform_update(self, serializer):
        serializer.save(author=self.request.user)

函数类视图中使用分页类

注意pagination_class属性仅支持在genericsAPIView和视图集viewset中配置使用。如果你使用函数或简单的APIView开发API视图，那么你需要对你的数据进行手动分页，一个具体使用例子如下所示：

from rest_framework.pagination import PageNumberPagination
class ArticleList0(APIView):
    """
    List all articles, or create a new article.
    """
    def get(self, request, format=None):
        articles = Article.objects.all()


        page = PageNumberPagination()  # 产生一个分页器对象
        page.page_size = 3  # 默认每页显示的多少条记录
        page.page_query_param = 'page'  # 默认查询参数名为 page
        page.page_size_query_param = 'size'  # 前台控制每页显示的最大条数
        page.max_page_size = 10  # 后台控制显示的最大记录条数，防止用户输入的查询条数过大
        ret = page.paginate_queryset(articles, request)
        serializer = ArticleSerializer(ret, many=True)


        return Response(serializer.data)

小结

本文总结了DRF提供的3种分页类并详细演示了如何使用它们，你学会了吗?

大江狗

2020.11.22

相关阅读

Django REST Framework教程(7): 如何使用JWT认证(神文多图)

Django REST Framework教程(5): 认证(Authentication)与权限(Permission)初识

Django REST Framework教程(3): 基于类的视图APIView, GenericAPIView和视图集

文末给大家推荐一本Django开发好书(不是我写的哦)，有少量赠书名额，有兴趣免费获得开发宝典的欢迎留言啊。有兴趣购买的长按二维码即可。

本书结合样例，介绍 Django 的基础知识、主要模块的开发以及权限管理等高级内容，并且通过图书管理系统、博客系统、车费管理系统 3 个项目的开发实战，使读者既能掌握 Django 的重要开发技术，又能对这些知识在项目中的综合应用有深入了解。

本书共有 16 章，分为 3 个篇章，准备篇介绍了 Web 框架以及 Django 的基本知识；入门篇详细讲解了路由系统、模板系统等5 个主要模块的开发过程，并通过图书管理系统和博客系统的开发综合应用这些知识；进阶篇介绍了 AJAX、中间件、权限管理等内容，并完成了车费管理系统的项目开发。

本书讲解详细，内容通俗易懂，案例丰富，适合 Python 进阶读者或 Django 开发入门读者阅读，也可以作为 Web 开发人员或编程爱好者的自学参考。