REST 或 GraphQL 中的分页

2025-07-23

有效负载分页允许数据 API 指向非常大的数据集，而不需要客户端或 API 本身。数据 API 生成器无需同时返回所有行，而是自动将响应分解为页面，从而提高性能和保护系统资源。

此分页系统适用于 REST 和 GraphQL 终结点，并包括对基于游标的导航的内置支持。即使查询繁忙或快速更改的表，基于游标的分页也有助于跨页面加载提供稳定、一致的结果。

索引导航按位置返回行，例如“行 51 到 100”。这适用于静态数据，但如果在请求之间添加或删除行，则会中断。结果通常跳过或重复行。

游标导航通过使用稳定的引用（如唯一 ID 或内部令牌）来避免此问题，以记住上一页结束的位置。即使基础数据在调用之间发生更改，这也会保持分页可靠。

例如，如果用户加载了 50 行，并在下一页请求之前插入新数据，则游标导航仍会准确选取上一个调用中断的位置。此行为内置于使用 REST firstafter 或 $after GraphQL 的数据 API 生成器$first中和 GraphQL 中。

使用（REST）或 `after` （GraphQL）请求页面`$after`

检索第一页后，响应将包含延续标记。在 REST 中，这是一个 nextLink URL。在 GraphQL 中，它显示为 endCursor 对象中的 pageInfo 值。可以将该令牌用于 $after 或 after 请求下一页的结果，而无需跳过或重复数据。

REST 示例 `$after`

GET /api/products?$first=3&$after=eyJpZCI6MywidHMiOjE3MDA4MDg1NTU1fQ==

此调用返回在令牌表示的项之后开始的接下来 3 个项目。下面是 REST 有效负载的外观：

{
  "value": [
    { "id": 1, "name": "Item A" },
    { "id": 2, "name": "Item B" },
    { "id": 3, "name": "Item C" }
  ],
  "nextLink": "/api/products?$first=3&$after=eyJpZCI6MywidHMiOjE3MDA4MDg1NTU1fQ=="
}

该 nextLink 字段包含随时可用的延续 URL。客户端可以调用它以获取下一页。

GraphQL 示例 `after`

在 GraphQL 中，没有 nextLink。相反，必须显式请求 pageInfo 接收游标并检查是否有更多页面可用。

query {
  products(first: 3) {
    items {
      id
      name
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

示例 GraphQL 响应：

{
  "data": {
    "products": {
      "items": [
        { "id": 1, "name": "Item A" },
        { "id": 2, "name": "Item B" },
        { "id": 3, "name": "Item C" }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJpZCI6MywidHMiOjE3MDA4MDg1NTU1fQ=="
      }
    }
  }
}

若要获取下一页，请使用after参数提供endCursor值：

query {
  products(first: 3, after: "eyJpZCI6MywidHMiOjE3MDA4MDg1NTU1fQ==") {
    items {
      id
      name
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

控制有效负载

数据 API 生成器为开发人员提供了灵活的方法来控制单个请求中返回的数据量。这适用于 REST 和 GraphQL 终结点，有助于避免客户端或 API 过载。

Understanding runtime.pagination.default-page-size

此设置 runtime.pagination.default-page-size 定义未指定显式限制时默认返回的行数。此设置适用于 REST 和 GraphQL 查询。

使用 REST 示例 `$first`

GET /api/products?$first=10 HTTP/1.1
Host: myapi.com

使用 GraphQL 示例 `first`

query {
  products(first: 10) {
    items {
      id
      name
    }
  }
}

在这两种情况下，即使存在更多项，响应也会仅返回 10 个项。这使 UI 能够保持响应状态，并帮助管理带宽和处理。

Understanding runtime.pagination.max-page-size

该 runtime.pagination.max-page-size 设置定义任何请求的上限，即使使用 $first 或 first请求了更高的值也是如此。这可以防止用户请求可能降低性能的过大有效负载。

Note

设置 $first=-1 （或在 first: -1 GraphQL 中）告知 API 返回允许 max-page-size的最大行数。这为使用者提供了一种简单的方法来请求完整限制，而无需知道其确切值。

Understanding runtime.host.max-response-size-md

无论行计数如何，此设置 runtime.host.max-response-size-md 都会控制总响应大小（以兆字节为单位）。当行包含大型字段（例如 NVARCHAR(MAX)， JSON或二进制数据）时，这非常有用。

即使少量行也可以根据列类型创建大型有效负载。此设置可保护 API 和客户端免受可能超出内存或网络限制的严重响应。

这些设置协同工作，在 REST 和 GraphQL 之间平衡性能、安全性和灵活性。

通过

REST 或 GraphQL 中的分页

什么是游标导航？

使用 （REST） 或 after （GraphQL） 请求页面$after

REST 示例 $after

GraphQL 示例 after