搜索菜单
当前位置: 首页 > Python > Django Rest Framework 三种分页配置详解：PageNumber、LimitOffset 与 Cursor

Django Rest Framework 三种分页配置详解：PageNumber、LimitOffset 与 Cursor

叶初
叶初
发布时间：2026-10-13 | 6人浏览过
原创

本文详解 Django Rest Framework 中的三种分页实现方式。通过全局配置与视图级配置，分别演示 PageNumberPagination（页码分页）、LimitOffsetPagination（偏移量分页）及 CursorPagination（加密游标分页）的具体用法。涵盖序列化类定义、分页器参数配置及 API 测试示例，帮助开发者高效处理大数据量展示。

DRF 分页机制概述与全局配置

前言

当数据库中存储了数千万条数据时，直接全量读取会引发严重的内存压力，甚至导致内存溢出。因此，我们需要采用分批读取的策略，以减轻系统负担。

在前端展示层面，同样需要对数据进行分页处理，以提升用户体验和加载效率。

本文将深入解析 DRF（Django Rest Framework）提供的三种主流分页机制及其配置方法。

全局配置


REST_FRAMEWORK = {
  # 对所有分页器生效，但优先级低
  'PAGE_SIZE': 5, # 每页显示5条数据
}

首先，我们需要准备用于测试分页的数据模型以及对应的序列化类。


from django.db import models

class Test(models.Model):
  """用于测试分页的数据表"""
  name = models.CharField(max_length=64)

接下来，生成用于测试的数据记录。


# 在Python脚本中调用Django环境
import os

if __name__ == '__main__':
  # 将下面的'blog095.settings'改为项目对应的名称后直接执行即可生成记录
  os.environ.setdefault('DJANGO_SETTINGS_MODULE', > 'blog095.settings')
  import django
  django.setup()
  from blog.models import Test # 导入数据表
  [Test.objects.create(name="花千骨%s" % str(i)) for i in range(100)]

定义用于测试数据的序列化类。


from rest_framework.serializers import ModelSerializer
from blog.models import Test # 导入数据表

class TestSerializer(ModelSerializer):
  """用于测试分页的序列化类"""
  class Meta:
    model = Test
    fields = '__all__'

第一种方式：PageNumberPagination（页码分页）。该方式允许用户指定查询第 n 页，并设定每页显示的数据条数。

第一步：配置分页器类。

PageNumberPagination 页码分页实现


from rest_framework import pagination

class PageNumberPagination(pagination.PageNumberPagination):
  """查第n页，每页显示n条数据"""
  page_size = 10 # 指定每页显示多少条数据
  page_size_query_param = 'size' # URL参数中每页显示条数的参数
  page_query_param = 'page' # URL中页码的参数
  max_page_size = None # 每页最多显示多少条数据

第二步：在视图文件中应用该分页器。


from rest_framework.response import Response
from rest_framework.views import APIView
from rest_framework.serializers import ModelSerializer
from blog.models import Test # 导入数据表
from blog import pagination # 导入上面的分页配置

class Test01View(APIView):
  def get(self, request):
    queryset = Test.objects.all()

    # 1. 实例化分页器对象
    page_obj = pagination.PageNumberPagination()

    # 2. 使用自己配置的分页器调用分页方法进行分页
    page_data = page_obj.paginate_queryset(queryset, request)

    # 3. 序列化我们分页好的数据
    ser_obj = TestSerializer(page_data, many=True)

    # # 4. 返回数据
    # return Response(ser_obj.data)

    # 4. 返回带上一页/下一页连接的页面
    return page_obj.get_paginated_response(ser_obj.data)

第三步：进行访问测试。


如上图所示，当指定 page=10 且 size=5 时，接口返回了相应的分页数据。

第二种方式：LimitOffsetPagination（偏移量分页）。该方式允许指定从第 n 个位置开始，向后查询 n 条数据。

第一步：配置分页器类。

LimitOffsetPagination 偏移量分页实现


from rest_framework import pagination

class LimitOffsetPagination(pagination.LimitOffsetPagination):
  """在第n个位置，向后查n条数据"""
  default_limit = 1 # 指定默认查多少条数据
  limit_query_param = 'limit' # URL中指定查多少条数据的参数
  offset_query_param = 'offset' # URL中指定从第几条数据开始查的参数
  max_limit = 999 # 最大显示多少条数据

第二步：在视图文件中应用该分页器。


from rest_framework.response import Response
from rest_framework.views import APIView
from rest_framework.serializers import ModelSerializer
from blog.models import Test # 导入数据表
from blog.pagination import LimitOffsetPagination # 导入上面的分页配置


class Test02View(APIView):
  def get(self, request):
    queryset = Test.objects.all()

    # 1. 实例化分页器对象
    page_obj = LimitOffsetPagination()

    # 2. 使用自己配置的分页器调用分页方法进行分页
    page_data = page_obj.paginate_queryset(queryset, request)

    # 3. 序列化我们分页好的数据
    ser_obj = TestSerializer(page_data, many=True)

    # # 4. 返回数据
    # return Response(ser_obj.data)

    # 4. 返回带上一页/下一页连接的页面
    return page_obj.get_paginated_response(ser_obj.data)

第三步：进行访问测试。

***

第三种方式：CursorPagination（加密游标分页）。这是一种基于加密游标的分页机制，适用于大数据量且对性能要求较高的场景。

第一步：配置分页器类。

CursorPagination 加密游标分页实现


from rest_framework import pagination

class CursorPagination(pagination.CursorPagination):
  """加密游标的分页"""
  cursor_query_param = 'cursor' # 游标(这是加密的游标)
  # ordering = '-id' # 从后往前取数据
  ordering = 'id'
  page_size = 1 # 每页显示的条数

第二步：在视图文件中应用该分页器。


from rest_framework.response import Response
from rest_framework.views import APIView
from rest_framework.serializers import ModelSerializer
from blog.models import Test # 导入数据表
from blog.pagination import CursorPagination # 导入上面的分页配置

class Test03View(APIView):
  def get(self, request):
    queryset = Test.objects.all()

    # 1. 实例化分页器对象
    page_obj = CursorPagination()

    # 2. 使用自己配置的分页器调用分页方法进行分页
    page_data = page_obj.paginate_queryset(queryset, request)

    # 3. 序列化我们分页好的数据
    ser_obj = TestSerializer(page_data, many=True)

    # # 4. 返回数据
    # return Response(ser_obj.data)

    # 4. 返回带上一页/下一页连接的页面
    return page_obj.get_paginated_response(ser_obj.data)

完成配置后，即可通过浏览器或客户端工具进行功能测试。

此外，DRF 的视图系统还支持生成带有上一页/下一页导航按钮的页面结构。

ModelViewSet 中的分页配置与导航


from rest_framework.viewsets import ModelViewSet

class Test04View(ModelViewSet):
  queryset = Test.objects.all()
  serializer_class = TestSerializer
  pagination_class = CursorPagination # 指定分页配置器

具体效果如下图所示。


配置生效，功能正常。

以上即为本文的全部内容，希望能为您的学习提供 helpful 参考，也欢迎大家继续支持本站。

相关文章

相关标签: Python Django DRF 后端开发

本站声明

本文内容仅供参考，不代表本站观点。转载或引用请注明出处。如发现内容问题，请通过联系我们页面反馈。

作者最新文章

全部内容

Python 相关产品和应用

全部下载
Python Selenium
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。
Python 机器学习
scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。
Python 代码质量
Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。
Python 代码质量
Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。
Python pytest
pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。
Python FastAPI API
FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架，支持类型提示和自动接口文档。
Python Flask Web开发
Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。
Python Django Web开发
Django

Django

6.1.2 · Windows

成熟的 Python Web 框架，适合构建内容站点和业务系统。
Python Spyder
Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。
Python SciPy
SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。
Python Pandas 数据分析
pandas

pandas

3.0.6 · Windows

Python 数据分析库，提供 DataFrame 与丰富的数据处理能力。
Python NumPy
NumPy

NumPy

2.5.4 · Windows

Python 科学计算基础库，提供高性能多维数组与数值运算。

文章分类

专题列表

ipython.cn 学习网
人工智能 Java AI行业服务