django rest_framework 分页

# 简介

本文主要介绍在drf框架中如何对查询的数据进行分页，在drf框架中有提供该基础功能的使用案例和文档，详情参考drf-pagination-官网文档 (opens new window)

# 内置分页方式

drf框架中默认提供几种分页方式，并封装成了模块提供给开发者调用，主要是以下几种：

PageNumberPagination，主要是提供page和page_size进行分页。
- page，当前页数
- page_size，每页展示的数量
LimitOffsetPagination，提供limit和offset进行分页
- limit，当前分页展示的数量
- offset，当前数据是从第几行开始。
CursorPagination，对结果集中提供前进与后退的链接来进行操作，不允许随意跳动到任意位置。

# 自定义分页

框架本身提供了分类的模块，但在实际工作中并不适用，所以我们可以通过继承的方式对内置的分页模块中的部分属性进行覆盖，以符合自身业务。

class LargeResultsSetPagination(PageNumberPagination):
    page_size = 1000
    page_size_query_param = 'page_size'
    max_page_size = 10000

class StandardResultsSetPagination(PageNumberPagination):
    page_size = 100   
    page_size_query_param = 'page_size'
    max_page_size = 1000

1
2
3
4
5
6
7
8
9

参数：

page_size：请求接口未指明时，默认使用该值来查询数据量
max_page_size：这个是限制一页最大能展示的数量。
page_size_query_param：前端请求分页数量的字段

上面是部分常用的字段，如果有特殊业务可以看源码再进行修改。

# 自定义分页响应数据

在内置的分页类PageNumberPagination中响应的数据格式如下：

{
    "count": 总数,
    "next": 下一页的链接,
    "previous": 上一页的链接,
    "results": 分页后的数据
}

1
2
3
4
5
6

但实我们在业务中可能并不需要next和previous，只需要保留count和results两个字段，这个时候我们可以通过重写get_paginated_response方法需要对响应的数据进行裁剪。

class LargeResultsSetPagination(PageNumberPagination):
    page_size = 1000
    page_size_query_param = 'page_size'
    max_page_size = 10000

    def get_paginated_response(self, data):
        return Response(OrderedDict([
            ('count', self.page.paginator.count),
            ('results', data)
        ]))

1
2
3
4
5
6
7
8
9
10

# 配置

# 全局

在settings.py中可以设置全局的分页模式，在REST_FRAMEWORK中设置DEFAULT_PAGINATION_CLASS，该key是指定分页模式使用哪个分页类，而这里使用的是drf框架中内置的分页类LimitOffsetPagination，并设置参数PAGE_SIZE指定每页默认展示的数量。

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
    'PAGE_SIZE': 100
}

1
2
3
4

该项配置会对全局生效，也就是每一个view的List查询都会走该分页模式。

# 局部

在某些业务场景是不需要分页的，或者不同的接口需要使用的分页模式不同，那么上面的全局配置方法就不适用的了，这个时候就需要使用局部配置的方式。

首先不进行全局模式，在需要分页的View中添加pagination_class并设置对应的分页模式类，这里使用的是自定义的分页类，该配置只会在本View中生效。

class BillingRecordsView(generics.ListAPIView):
    queryset = Billing.objects.all()
    serializer_class = BillingRecordsSerializer
    pagination_class = LargeResultsSetPagination

1
2
3
4

上次更新: 2025/05/07, 05:17:56

← django 警告 while time zone support is active django-prometheus使用及源码分析→