Django REST framework API 指南（17）：分页

官方原文连接
本系列文章 github 地址
转载请注明出处

分页

REST framework 包含对可定制分页样式的支持。这使你能够将较大的结果集分红单独的数据页面。

分页 API 支持：

• 以分页连接的形式做为响应内容的一部分。
• 以分页连接的形式包含在响应的 header 中，如 Content-Range 或 Link.

内置的样式目前是以分页连接的形式做为响应内容的一部分。使用可浏览的 API 时，此样式更易于访问。

分页仅在你使用通用视图或视图集时自动执行。若是你使用的是常规 APIView，则须要本身调用分页 API 以确保返回分页响应。示例请参阅 mixins.ListModelMixin 和 generics.GenericAPIView 类的源代码。

能够经过将分页类设置为 None，关闭分页。

设置分页样式

分页样式可使用 DEFAULT_PAGINATION_CLASS 和 PAGE_SIZE setting key 全局设置。例如，要使用内置的 limit/offset 分页，你能够这样作：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
    'PAGE_SIZE': 100
}
复制代码

请注意，你须要设置分页类和应使用的页面大小。默认状况下，DEFAULT_PAGINATION_CLASS 和 PAGE_SIZE 都是 None。

你还可使用 pagination_class 属性在单个视图上设置分页类。一般，你但愿在整个 API 中使用相同的分页样式，但你可能但愿在每一个视图的基础上更改分页的各个方面，例如默认或最大页面大小。

修改分页样式

若是要修改分页样式的特定方面，则须要继承其中一个分页类，并设置要更改的属性。

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
复制代码

而后，你可使用 .pagination_class 属性将新样式应用于视图：

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

或者使用 DEFAULT_PAGINATION_CLASS setting key 全局应用样式。例如：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'apps.core.pagination.StandardResultsSetPagination'
}
复制代码

---

API 参考

PageNumberPagination

此分页样式在请求查询参数中接受一个页码值。

Request:

GET https://api.example.org/accounts/?page=4
复制代码

Response:

HTTP 200 OK
{
    "count": 1023
    "next": "https://api.example.org/accounts/?page=5",
    "previous": "https://api.example.org/accounts/?page=3",
    "results": [
       …
    ]
}
复制代码

Setup

要全局启用 PageNumberPagination 样式，请使用如下配置，并根据须要设置 PAGE_SIZE：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 100
}
复制代码

若是使用的是 GenericAPIView 的子类，还能够设置 pagination_class 属性以在每一个视图的基础上选择 PageNumberPagination。

Configuration

PageNumberPagination 类包含一些能够被覆盖以修改分页样式的属性。

要设置这些属性，你应该继承 PageNumberPagination 类，而后像上面那样启用你的自定义分页类。

• django_paginator_class - 要使用的 Django Paginator 类。默认是 django.core.paginator.Paginator，对于大多数用例来讲应该没问题。
• page_size - 指定页面大小的数字值。若是设置，则会覆盖 PAGE_SIZE setting。默认值与 PAGE_SIZE setting key 相同。
• page_query_param - 一个字符串值，指定用于分页控件的查询参数的名称。
• page_size_query_param - 一个字符串值，指定查询参数的名称，容许客户端根据每一个请求设置页面大小。默认为 None，表示客户端可能没法控制所请求的页面大小。
• max_page_size - 一个数字值，表示容许的最大页面大小。该属性仅在 page_size_query_param 也被设置时有效。
• last_page_strings - 字符串列表或元组，用于指定可能与 page_query_param 一块儿使用的值，用以请求集合中的最终页面。默认为 ('last',)
• template - 在可浏览 API 中渲染分页控件时使用的模板的名称。可能会被覆盖以修改渲染样式，或设置为 None 以彻底禁用 HTML 分页控件。默认为 "rest_framework/pagination/numbers.html"。

---

LimitOffsetPagination

这种分页样式反映了查找多个数据库记录时使用的语法。客户端包含 “limit” 和 “offset” 查询参数。limit 表示要返回的 item 的最大数量，而且等同于其余样式中的 page_size。offset 指定查询的起始位置与完整的未分类 item 集的关系。

Request:

GET https://api.example.org/accounts/?limit=100&offset=400
复制代码

Response:

HTTP 200 OK
{
    "count": 1023
    "next": "https://api.example.org/accounts/?limit=100&offset=500",
    "previous": "https://api.example.org/accounts/?limit=100&offset=300",
    "results": [
       …
    ]
}
复制代码

Setup

要全局启用 LimitOffsetPagination 样式，请使用如下配置：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination'
}
复制代码

或者，你也能够设置一个 PAGE_SIZE 键。若是使用了 PAGE_SIZE 参数，则 limit 查询参数将是可选的，而且可能会被客户端忽略。

若是使用的是 GenericAPIView 子类，还能够设置 pagination_class 属性以基于每一个视图选择 LimitOffsetPagination。

Configuration

LimitOffsetPagination 类包含一些能够被覆盖以修改分页样式的属性。

要设置这些属性，应该继承 LimitOffsetPagination 类，而后像上面那样启用你的自定义分页类。

• default_limit - 一个数字值，指定客户端在查询参数中未提供的 limit 。默认值与 PAGE_SIZE setting key 相同。
• limit_query_param - 一个字符串值，指示 “limit” 查询参数的名称。默认为 'limit'。
• offset_query_param - 一个字符串值，指示 “offset” 查询参数的名称。默认为 'offset'。
• max_limit - 一个数字值，表示客户端能够要求的最大容许 limit。默认为 None。
• template - 在可浏览 API 中渲染分页控件时使用的模板的名称。可能会被覆盖以修改渲染样式，或设置为 None 以彻底禁用 HTML 分页控件。默认为 "rest_framework/pagination/numbers.html"。

---

CursorPagination

基于游标的分页提供了一个不透明的 “游标” 指示器，客户端可使用该指示器来翻阅结果集。此分页样式仅提供前向和反向控件，而且不容许客户端导航到任意位置。

基于游标的分页须要在结果集中存在惟一的，不变的 item 顺序。这种排序一般能够是记录上的建立时间戳，由于这确保了排序的一致性。

基于游标的分页比其余方案更复杂。它还要求结果集渲染固定顺序，而且不容许客户端任意索引结果集。但它确实提供了如下好处：

• 提供一致的分页视图。正确使用时 CursorPagination 确保客户端在分页时不会看到同一个 item，即便在分页过程当中其余客户端正在插入新 item。
• 支持使用很是大的数据集。使用极大数据集分页时，使用基于偏移量的分页样式可能会变得效率低下或没法使用。基于游标的分页方案具备固定时间属性，而且不会随着数据集大小的增长而减慢。

细节和限制

正确使用基于游标的分页须要稍微注意细节。你须要考虑但愿将该方案应用于何种顺序。默认是按 "-created" 排序。这假设在模型实例上必须有一个 “created” 时间戳字段，而且会渲染一个 “时间轴” 样式分页视图，其中最近添加的 item 是第一个。

你能够经过重写分页类上的 'ordering' 属性或者将 OrderingFilter 过滤器类与 CursorPagination 一块儿使用来修改排序。与 OrderingFilter 一块儿使用时，你应该考虑限制用户能够排序的字段。

正确使用游标分页应该有一个知足如下条件的排序字段：

• 在建立时应该是一个不变的值，例如时间戳，slug，或其余只设置一次的字段。
• 应该是独特的，或几乎独一无二的。毫秒精度时间戳就是一个很好的例子。这种游标分页的实现使用了一种智能的 “位置 + 偏移” 风格，容许它正确地支持非严格惟一的值做为排序。
• 应该是能够强制为字符串的非空值。
• 不该该是一个 float。精度错误很容易致使错误的结果。提示：改用小数。（若是你已经有一个 float 字段而且必须对其进行分页，则能够在此处找到使用小数来限定精度的示例。）
• 该字段应该有一个数据库索引。

使用不知足这些约束条件的排序字段一般仍然有效，可是你将失去游标分页的一些好处。

Setup

要全局启用 CursorPagination 样式，请使用如下配置，根据须要修改 PAGE_SIZE：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.CursorPagination',
    'PAGE_SIZE': 100
}
复制代码

若是使用的是 GenericAPIView 子类，还能够设置 pagination_class 属性以基于每一个视图选择 CursorPagination。

Configuration

CursorPagination 类包含一些能够被覆盖以修改分页样式的属性。

要设置这些属性，你应该继承 CursorPagination 类，而后像上面那样启用你的自定义分页类。

• page_size = 指定页面大小的数字值。若是设置，则会覆盖 PAGE_SIZE 设置。默认值与 PAGE_SIZE setting key 相同。
• cursor_query_param = 一个字符串值，指定 “游标” 查询参数的名称。默认为 'cursor'.
• ordering = 这应该是一个字符串或字符串列表，指定将应用基于游标的分页的字段。例如： ordering = 'slug'。默认为 -created。该值也能够经过在视图上使用 OrderingFilter 来覆盖。
• template = 在可浏览 API 中渲染分页控件时使用的模板的名称。可能会被覆盖以修改渲染样式，或设置为 None 以彻底禁用 HTML 分页控件。默认为 "rest_framework/pagination/previous_and_next.html"。

---

自定义分页样式

要建立自定义分页序列化类，你应该继承 pagination.BasePagination 并覆盖 paginate_queryset(self, queryset, request, view=None) 和 get_paginated_response(self, data) 方法：

• paginate_queryset 方法被传递给初始查询集，而且应该返回一个只包含请求页面中的数据的可迭代对象。
• get_paginated_response 方法传递序列化的页面数据，并返回一个 Response 实例。

请注意，paginate_queryset 方法能够在分页实例上设置状态，然后 get_paginated_response 方法可使用它。

举个栗子

假设咱们想用一个修改后的格式替换默认的分页输出样式，该样式包含嵌套的 “links” key（包含上一页，下一页连接）。咱们能够像这样指定一个自定义分页类：

class CustomPagination(pagination.PageNumberPagination):
    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
        })
复制代码

而后咱们须要在配置中设置自定义类：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'my_project.apps.core.pagination.CustomPagination',
    'PAGE_SIZE': 100
}
复制代码

请注意，若是你关心如何在可浏览的 API 中显示键的顺序，则能够在构建分页响应的主体时选择使用 OrderedDict，这是可选的。

使用你的自定义分页类

要默认使用你的自定义分页类，请使用 DEFAULT_PAGINATION_CLASS setting：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'my_project.apps.core.pagination.LinkHeaderPagination',
    'PAGE_SIZE': 100
}
复制代码

列表端点的 API 响应如今将包含一个 Link header，而不是将分页连接包含为响应主体的一部分。

分页和模式

经过实现 get_schema_fields() 方法，你还可使分页控件可用于 REST framework 提供的模式自动生成。此方法应具备如下签名：

get_schema_fields(self, view)

该方法应该返回一个 coreapi.Field 实例列表。

---

自定义分页样式，使用 'Link' header

---

HTML 分页控件

默认状况下，使用分页类将致使 HTML 分页控件显示在可浏览的 API 中。有两种内置显示样式。 PageNumberPagination 和 LimitOffsetPagination 类显示包含上一页和下一页控件的页码列表。 CursorPagination 类显示更简单的样式，只显示上一页和下一页控件。

自定义控件

你能够覆盖渲染 HTML 分页控件的模板。这两种内置式样是：

• rest_framework/pagination/numbers.html
• rest_framework/pagination/previous_and_next.html

在全局模板目录中提供具备这些路径的模板将覆盖相关分页类的默认渲染。

或者，你能够经过在现有类的子类上彻底禁用 HTML 分页控件，将 template=None 设置为该类的属性。而后，你须要配置你的 DEFAULT_PAGINATION_CLASS setting key，以将你的自定义类用做默认分页样式。

低级 API

用于肯定分页类是否应显示控件的低级 API 做为分页实例上的 display_page_controls 属性公开。若是须要显示HTML 分页控件，自定义分页类应该在 paginate_queryset 方法中设置为 True 。

.to_html() 和 .get_html_context() 方法也能够在自定义分页类中重写，以便进一步自定义控件的渲染方式。