API 设计：如何使用 Cursor API 实现高效分页 – wiki基地

作者： /

API 设计：如何使用 Cursor API 实现高效分页实现高效分页

在现代 Web 应用和移动应用中，列表展示数据是一项基本且频繁的需求。无论是社交媒体的动态流、电商平台的商品列表、新闻资讯的应用，还是管理系统的日志记录，都需要将大量数据分批次地呈现给用户。分页（Pagination）正是解决这一问题的核心技术。

传统上，实现分页最常见的方式是使用基于偏移量（Offset）和限制数量（Limit）的 API 设计。这种方法直观易懂，但在处理大数据集和高并发场景时，会暴露出一些严重的性能和稳定性问题。为了克服这些缺点，一种更先进、更高效的分页方法应运而生——基于游标（Cursor）的 API 分页。

本文将深入探讨基于游标的分页机制，详细阐述它与传统的偏移量分页的区别、工作原理、优势、劣势以及如何在后端和前端进行具体的实现，帮助开发者设计出更健壮、更高效的 API。

1. 传统分页：Offset/Limit 的困境

首先，我们回顾一下传统的 Offset/Limit 分页是如何工作的。其基本思想是通过两个参数来指定要获取的数据：

  • Offset (偏移量): 跳过前面多少条数据。
  • Limit (限制数量): 每页返回多少条数据。

例如，要获取第 N 页（每页大小为 P），通常会发送这样的请求：/api/items?limit=P&offset=(N-1)*P。

在数据库层面，对应的查询通常是这样的 SQL 语句：

sql
SELECT * FROM items ORDER BY id LIMIT P OFFSET (N-1)*P;

这种方法简单直接，对于数据量较小或数据不经常变动的场景，表现尚可。然而，当数据量变得庞大（数十万、数百万甚至更多）时，Offset/Limit 分页的弊端就显现出来了：

  1. 性能问题：

    • 当 offset 值较小时，数据库可以快速定位到起始位置。但随着 offset 值的增大，数据库需要扫描（或至少是遍历索引）前面 offset 条数据才能开始获取需要返回的 limit 条数据。这个扫描过程会消耗大量的 CPU 和内存资源，尤其是在没有合适索引或者索引不够有效的情况下。
    • 即使有索引，OFFSET 操作在许多数据库中依然需要先按照 ORDER BY 的字段排序（或利用排序索引），然后跳过指定的行数。对于巨大的 OFFSET，这并非一个 O(1) 或 O(log N) 的操作，其开销往往与 OFFSET 的大小成正比，导致性能呈线性甚至指数级下降。

  2. 数据漂移和不稳定性：

    • Offset/Limit 分页基于数据在某个特定时间点的“顺序”位置。如果在用户浏览列表时，有新的数据被插入到当前页之前，或者有数据被删除、更新导致排序位置变化，那么用户在加载下一页时，可能会看到重复的数据，或者跳过一些数据。
    • 例如，用户正在看第 2 页（Offset 10, Limit 10）。在他请求第 3 页（Offset 20, Limit 10）之前，有 5 条新数据被插入到列表的开头。此时，原来的数据索引发生了变化。他请求 Offset 20 时，实际上可能会拿到原来 Offset 15 开始的数据，导致数据错位。

  3. 无法处理无限滚动（Infinite Scrolling）：

    • 无限滚动是现代应用中常见的一种交互模式，用户向下滚动页面，新数据自动加载。Offset/Limit 方式需要客户端知道当前的页码或总偏移量。虽然可以模拟，但数据漂移问题在无限滚动场景下尤其突出，用户体验很差。

  4. 难以实现“跳转到任意页”：

    • 虽然 Offset/Limit 天生支持跳转到任意页（只需要计算对应的 Offset），但在大数据量下，跳转到靠后的页码会导致严重的性能问题，用户需要等待很长时间。这使得这项看似方便的功能在大规模应用中变得不太实用。

这些问题使得传统的 Offset/Limit 分页在大规模、高并发、数据频繁变动的应用中显得力不从心。我们需要一种不同的思路来实现分页。

2. 引入 Cursor 分页：基于位置的指针

Cursor 分页，或称基于游标的分页，提供了一种更鲁棒的解决方案。它不依赖于数据的绝对位置（偏移量），而是依赖于一个指向数据集某个特定位置的“指针”——游标（Cursor）。

核心思想： 下一页的数据从“当前页最后一条数据”的后面开始获取。

用户首次请求时，不带游标参数，API 返回第一页数据，同时在响应中包含一个指向“下一页起始位置”的游标。客户端在请求下一页时，将上一次收到的游标发送给服务器。服务器根据这个游标快速定位到数据集合中的特定位置，然后从该位置开始获取指定数量的数据。

3. Cursor 分页的工作原理

Cursor 分页通常依赖于一个或多个稳定、唯一的排序键（Sort Key）。这个键用于确定数据项的顺序，并且能够唯一标识一个数据项或一个位置。常见的排序键包括：

  • 唯一自增 ID： 如果数据按 ID 排序，游标可以是上一页最后一条数据的 ID。
  • 时间戳 + 唯一 ID： 如果数据按时间（例如创建时间 created_at）排序，可能会存在多条数据在同一时间创建。为了保证顺序稳定和唯一性，可以将游标设计为 (timestamp, id) 的组合。
  • 其他唯一且有序的字段： 例如，如果按用户名排序且用户名唯一，可以使用用户名作为游标。

API 请求通常包含以下参数：

  • limit: 每页返回的数据数量。
  • after (或 next_cursor): 获取位于指定游标 之后 的数据。
  • before (或 prev_cursor): 获取位于指定游标 之前 的数据（用于实现向前翻页）。

通常情况下，我们优先实现 after 功能，因为无限滚动等场景主要依赖向后翻页。

流程示例（向后翻页）：

  1. 首次请求: GET /api/items?limit=10

    • 服务器查询数据库：SELECT * FROM items ORDER BY created_at DESC, id DESC LIMIT 10; (假设按创建时间倒序，ID 倒序排序)
    • 服务器返回前 10 条数据。同时，生成一个 next_cursor。这个 next_cursor 通常包含最后一条数据（第 10 条）的排序键信息，例如 (created_at, id)。游标值通常会经过编码（如 Base64），以防止客户端篡改或暴露内部数据结构。
    • 响应格式可能类似：
      json
      {
      "data": [ {item1}, {item2}, ..., {item10} ],
      "next_cursor": "encoded_cursor_value_for_item10",
      "prev_cursor": null, // 首页没有上一页
      "has_more": true // 或者根据返回数量判断
      }

  2. 请求下一页: GET /api/items?limit=10&after=encoded_cursor_value_for_item10

    • 服务器解码 encoded_cursor_value_for_item10，获取到其排序键值，例如 (timestamp_10, id_10)。
    • 服务器查询数据库：SELECT * FROM items WHERE (created_at, id) < (timestamp_10, id_10) ORDER BY created_at DESC, id DESC LIMIT 10;
      • 注意这里的 < 操作符用于复合键的比较，它表示 (created_at < timestamp_10) OR (created_at = timestamp_10 AND id < id_10)。这确保了获取的数据确实是在第 10 条数据 之后（根据倒序排序）。
    • 服务器返回接下来的 10 条数据（item11 到 item20）。同时，生成 next_cursor (基于 item20) 和 prev_cursor (基于 item11)。
    • 响应格式可能类似：
      json
      {
      "data": [ {item11}, {item12}, ..., {item20} ],
      "next_cursor": "encoded_cursor_value_for_item20",
      "prev_cursor": "encoded_cursor_value_for_item11",
      "has_more": true
      }

  3. 请求再下一页: GET /api/items?limit=10&after=encoded_cursor_value_for_item20

    • 服务器解码游标，获取 (timestamp_20, id_20)。
    • 查询数据库：SELECT * FROM items WHERE (created_at, id) < (timestamp_20, id_20) ORDER BY created_at DESC, id DESC LIMIT 10;
    • 依此类推…

实现向前翻页 (before)：

实现 before 参数通常需要配合 ORDER BY 方向的反转以及对结果集的再次反转。

  1. 请求上一页: GET /api/items?limit=10&before=encoded_cursor_value_for_item11
    • 服务器解码 encoded_cursor_value_for_item11，获取到其排序键值，例如 (timestamp_11, id_11)。
    • 服务器查询数据库，但这次我们需要找在 item11 之前 的 10 条数据。为了高效利用索引，我们通常将排序方向反转：
      • SELECT * FROM items WHERE (created_at, id) > (timestamp_11, id_11) ORDER BY created_at ASC, id ASC LIMIT 10; (注意这里是 > 和 ASC)
    • 这个查询返回的是 item1 到 item10 (如果 item11 是第 11 条)。但是，它们是按正序排列的。为了得到我们想要的倒序结果（item10 到 item1），服务器需要将这 10 条数据在内存中反转顺序。
    • 服务器返回 item1 到 item10 (已反转为 item10 到 item1)。生成 next_cursor (基于 item1) 和 prev_cursor (首页通常没有 prev_cursor 或为 null)。
    • 响应格式可能类似：
      json
      {
      "data": [ {item10}, {item9}, ..., {item1} ], // 顺序已反转
      "next_cursor": "encoded_cursor_value_for_item1",
      "prev_cursor": null,
      "has_more": true // 或者根据返回数量判断
      }
    • 实现 before 逻辑的复杂性在于需要额外的查询排序方向判断、条件判断以及结果集反转，这使得它的实现比 after 稍微复杂一些。很多应用可能只实现 after 用于无限滚动，而放弃传统的页码跳转或向前翻页功能。

4. Cursor Pagination 的优势

与 Offset/Limit 分页相比，Cursor 分页具有以下显著优势：

  1. 高性能：

    • 数据库可以直接利用排序键上的索引，通过 WHERE 子句快速定位到游标指定的位置。不需要扫描或跳过大量前面的数据。
    • 查询的性能不再与页码深度（即偏移量大小）直接相关。无论是请求第一页还是第一百页，只要能够快速定位到游标位置，后续获取指定数量数据的开销是相对恒定的（通常是 O(limit)）。这使得它在大数据集下保持稳定的高性能。

  2. 稳定性：

    • Cursor 分页依赖于数据项之间的相对位置（“在某项之后”或“在某项之前”）。
    • 在用户翻页过程中，即使有新的数据被插入到当前页之前，或者有数据被删除，只要排序键不改变，游标依然能准确指向其原始位置，从而保证下一页的数据是紧跟着上一页末尾的，不会出现重复或跳过。这极大地提高了分页的稳定性。

  3. 适用于无限滚动：

    • Cursor 分页天然适合实现无限滚动。客户端只需要不断地使用上一次返回的 next_cursor 请求下一页数据即可，逻辑简单且用户体验流畅。

  4. 保护数据总量：

    • Cursor 分页通常不需要知道数据的总条数。这避免了执行昂贵的 SELECT COUNT(*) 查询，进一步提升了性能。

5. Cursor Pagination 的劣势与考虑

尽管 Cursor 分页优势明显，但也存在一些限制和需要权衡的地方：

  1. 难以实现“跳转到任意页码”：

    • Cursor 分页是基于“下一页”或“上一页”的导航，难以直接计算出第 N 页的游标。如果应用需要用户频繁地跳转到具体的页码（例如，一个传统的后台管理系统需要快速定位到某个记录所在的页面），Offset/Limit 可能仍然是更直观的选择（尽管性能问题依然存在）。
    • 当然，可以通过一些变通方法来模拟跳转，例如先获取第 M 页的游标，然后从该游标开始向后或向前分页，但这比直接计算偏移量复杂得多，且依然可能面临性能挑战。

  2. 需要稳定的排序键：

    • Cursor 分页高度依赖于所选的排序键的稳定性和唯一性。如果排序键本身不唯一（例如，只按创建时间排序，存在大量相同时间的数据），或者数据项的排序键会频繁变动，Cursor 分页可能会失效或出现问题。通常需要使用复合键（如 (created_at, id)）来确保唯一性。

  3. 实现“向前翻页”的复杂性：

    • 如前所述，实现基于 before 的向前翻页逻辑比 after 更复杂，需要处理排序方向的反转和结果集的反转。

  4. 游标的设计和安全性：

    • 游标值通常包含敏感的排序键信息。虽然通常会进行编码（如 Base64），但客户端仍然可以看到编码后的值。设计时需要考虑是否需要对游标进行加密或签名，以防止篡改，尤其是在游标包含的用户特定或权限相关信息时（虽然基本分页游标通常不包含这些）。

6. 后端实现 Cursor Pagination 的关键细节

实现 Cursor Pagination，后端需要处理以下核心任务：

  1. 确定排序规则和排序键： 选择一个或多个字段作为排序键。它们必须能够唯一标识数据项的顺序位置，并且通常需要建立联合索引。例如，如果按创建时间倒序，次要排序键可以是 ID 倒序，索引就是 (created_at DESC, id DESC)。

  2. 设计游标内容： 游标需要包含定位下一页（或上一页）所需的所有信息。最基本的就是排序键的值。对于复合排序键，游标需要包含所有键的值。例如，对于 (created_at DESC, id DESC) 排序，游标可以是一个结构 { "createdAt": "...", "id": "..." }。

  3. 编码和解码游标： 为了使游标对客户端更加友好、避免暴露内部数据结构，并防止客户端直接看到排序键的明文值，通常会对游标内容进行编码。Base64 是一种常见的选择。

    • 编码：将游标结构的 JSON 字符串进行 Base64 编码。
    • 解码：将客户端传来的 Base64 字符串解码为游标结构。

  4. 处理首次请求 (无游标)： 当 after 和 before 参数都为空时，这是一个首次请求，返回第一页数据。查询语句只需包含 ORDER BY 和 LIMIT。

  5. 处理 after 请求：

    • 解码客户端提供的 after 游标，获取到排序键值 (e.g., (cursor_created_at, cursor_id)).
    • 构建数据库查询。使用 WHERE 子句结合排序键和比较运算符来定位：
      • 如果排序是 ASC：WHERE (created_at, id) > (cursor_created_at, cursor_id)
      • 如果排序是 DESC：WHERE (created_at, id) < (cursor_created_at, cursor_id)
    • 添加 ORDER BY (与首次请求和后续 after 请求的排序方向一致) 和 LIMIT limit + 1。为什么要加 1？是为了判断是否有更多数据 (has_more)。如果返回了 limit + 1 条，说明后面还有数据；否则，说明已经是最后一页（或少于一页）。
    • 获取查询结果。如果返回了 limit + 1 条，取前 limit 条作为当前页数据，第 limit + 1 条用于判断 has_more。
    • 生成 next_cursor：基于当前页最后一条数据的排序键值进行编码。
    • 生成 prev_cursor：基于当前页第一条数据的排序键值进行编码。

  6. 处理 before 请求：

    • 解码客户端提供的 before 游标，获取到排序键值 (e.g., (cursor_created_at, cursor_id)).
    • 构建数据库查询。使用 WHERE 子句结合排序键和 反向 的比较运算符来定位：
      • 如果正常排序是 ASC：WHERE (created_at, id) < (cursor_created_at, cursor_id)
      • 如果正常排序是 DESC：WHERE (created_at, id) > (cursor_created_at, cursor_id)
    • 添加 反向 的 ORDER BY 和 LIMIT limit + 1。
    • 获取查询结果。这些结果是按反向排序排列的（例如，请求上一页但结果是正序）。
    • 在内存中将查询结果 反转 顺序，取前 limit 条作为当前页数据。
    • 生成 next_cursor：基于当前页最后一条数据（反转后的最后一条，即原始查询结果的第一条）的排序键值进行编码。
    • 生成 prev_cursor：基于当前页第一条数据（反转后的第一条，即原始查询结果的第 limit 条）的排序键值进行编码。

  7. 响应结构： 返回包含 data (数据列表), next_cursor (下一页游标), prev_cursor (上一页游标), has_more (是否有更多数据) 等字段的标准 JSON 结构。

示例：使用复合键 (created_at DESC, id DESC)

游标结构: {"createdAt": 1678886400, "id": 12345} (解码后)
编码后游标: eyJjcmVhdGVkQXQiOjE2Nzg4ODY0MDAsICJpZCI6IDEyMzQ1fQ== (Base64 示例)

  • 首次请求: /items?limit=10
    SELECT * FROM items ORDER BY created_at DESC, id DESC LIMIT 10;

  • after 请求: /items?limit=10&after=eyJjcmVhdGVkQXQiOjE2Nzg4ODY0MDAsICJpZCI6IDEyMzQ1fQ==
    解码游标得到 (1678886400, 12345)
    SELECT * FROM items WHERE (created_at, id) < (1678886400, 12345) ORDER BY created_at DESC, id DESC LIMIT 11; (取 11 条判断 has_more)

  • before 请求: /items?limit=10&before=encoded_cursor_for_item_X (假设 item_X 的游标是请求获取其前面数据的依据)
    解码游标得到 (cursor_created_at_X, cursor_id_X)
    SELECT * FROM items WHERE (created_at, id) > (cursor_created_at_X, cursor_id_X) ORDER BY created_at ASC, id ASC LIMIT 11;
    获取结果，反转前 10 条。

需要注意的是，复合键的比较 (a, b) < (c, d) 在 SQL 中通常等价于 (a < c) OR (a = c AND b < d)。这是实现正确排序的关键。

7. 前端/客户端使用 Cursor Pagination

客户端使用 Cursor Pagination 相对简单：

  1. 首次请求： 发送不带 after 或 before 参数的请求 (只带 limit)。
  2. 存储游标： 接收到响应后，解析出数据 (data) 和 next_cursor, prev_cursor。将 next_cursor 和 prev_cursor 存储起来（例如，存储在组件的状态或 Redux store 中）。
  3. 加载下一页： 当用户滚动到底部触发加载更多或点击“下一页”按钮时，取出存储的 next_cursor，发送带有 after=stored_next_cursor 和 limit 参数的请求。
  4. 加载上一页： 当用户点击“上一页”按钮时，取出存储的 prev_cursor，发送带有 before=stored_prev_cursor 和 limit 参数的请求。
  5. 处理 has_more： 根据响应中的 has_more 字段来判断是否还有更多数据可供加载，从而决定是否继续显示“加载更多”按钮或触发自动加载。
  6. 状态管理： 客户端需要妥善管理当前页的数据列表、当前的 next_cursor 和 prev_cursor。当执行新的搜索或刷新列表时，需要清空当前数据和游标，回到首次请求状态。

对于无限滚动，客户端逻辑可以简化为：
* 维护一个数据列表数组。
* 维护当前的 next_cursor 状态。
* 页面加载或下拉刷新时，清空列表和游标，发送首次请求。
* 滚动到底部时，如果 next_cursor 非空且有更多数据 (has_more 为 true)，发送带 after=current_next_cursor 的请求。
* 新数据返回后，追加到数据列表数组末尾，更新 next_cursor。

8. 何时选择 Cursor Pagination

Cursor Pagination 特别适合以下场景：

  • 数据集非常庞大： 数据量级达到数十万、百万甚至更高，Offset/Limit 的性能瓶颈会非常突出。
  • 数据变动频繁： 列表中的数据会频繁地添加、删除或更新，可能导致 Offset/Limit 的数据漂移问题。
  • 主要需求是无限滚动或顺序浏览： 用户习惯于一页一页或无限滚动地浏览数据，而不是频繁地跳转到特定页码。
  • 不关心数据的总条数： 或者获取总条数的开销非常大，且应用不需要精确显示总页数或总条数。

9. 何时不选择 Cursor Pagination

在某些场景下，Offset/Limit 可能仍然是更合适的选择：

  • 数据集较小或固定： 数据量不大，Offset/Limit 的性能问题不明显，且实现简单。
  • 数据不怎么变动： 数据相对静态，不需要担心数据漂移。
  • 核心需求是跳转到任意页码： 应用设计要求用户能够方便快捷地跳转到任意页（尽管在大数据下性能不佳）。
  • 需要显示精确的总页数或总条数： 如果获取总数是必须的功能，Offset/Limit 的“总数 + 分页”模式更自然（但依然要面对获取总数的性能问题）。

10. 总结

分页是处理大量数据的必备技术。传统的 Offset/Limit 分页因其简单直观而被广泛使用，但在大数据量、高并发和数据频繁变动的场景下，其性能和稳定性问题（尤其显著的性能下降和数据漂移）成为瓶颈。

Cursor Pagination 提供了一种更现代、更高效的解决方案。它通过使用一个指向数据集特定位置的游标，结合基于排序键的定位方式，实现了与页码深度无关的高性能数据获取，并且天然地解决了数据变动导致的数据漂移问题，尤其适合实现无限滚动。

虽然 Cursor Pagination 在实现向前翻页和跳转到任意页等方面存在一定的复杂性和限制，但在面对大规模、动态变化的列表数据时，其带来的性能和稳定性提升通常是决定性的。

在设计 API 时，根据应用场景、数据量、数据变动频率以及用户交互需求，权衡 Cursor Pagination 和 Offset/Limit 的优劣，选择最合适的分页策略，是构建高性能、稳定、用户体验良好的应用的关键一步。对于绝大多数需要处理大量动态数据的场景，优先考虑和实践 Cursor Pagination，将是迈向更高效 API 设计的重要决策。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部