在 GraphQL API 中使用分页

关于分页

GitHub 的 GraphQL API 限制了可以在单个请求中提取的项数，以防止对 GitHub 服务器发出过多请求或滥用请求。 使用 GraphQL API 时，必须在任何连接上提供 first 或 last 参数。 这些参数的值必须介于 1 到 100 之间。 GraphQL API 将返回由 first 或 last 参数指定的连接数。

如果要访问的数据拥有的连接数大于 first 或 last 参数指定的项数，则响应将按指定大小分为较小的“页面”。 可以一次提取这些页面，直到检索到整个数据集为止。 每个页面都包含由 first 或 last 参数指定的项数，最后一页除外，最后一页包含的项数可能低于该值。

本指南演示如何在分页响应中请求其他结果页，如何更改每页返回的结果数，以及如何编写脚本来获取多页结果。

请求查询中的 cursor

使用 GraphQL API 时，可以使用游标来遍历分页后的数据集。 游标表示数据集中的特定位置。 可以通过查询 pageInfo 对象来获取页面上的第一个和最后一个光标。 例如：

query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    pullRequests(first: 100, after: null) {
      nodes {
        createdAt
        number
        title
      }
      pageInfo {
        endCursor
        startCursor
        hasNextPage
        hasPreviousPage
      }
    }
  }
}

在此示例中，pageInfo.startCursor 提供了页面上第一项的游标。 pageInfo.endCursor 提供了页面上最后一项的游标。 pageInfo.hasNextPage 和 pageInfo.hasPreviousPage 指示在返回的页面之前和之后是否还存在页面。

更改每页显示的项数

first 和 last 参数用于控制返回的项数。 可以使用 first 或 last 参数提取的最大项数为 100。 如果查询涉及大量数据，则建议将请求的项数限制在 100 以下，以避免达到速率限制或节点限制。 有关详细信息，请参阅“GraphQL API 的速率限制和节点限制”。

使用分页遍历数据集

返回查询的游标后，可以使用游标请求下一页的结果。 为此，需要使用 after 或 before 参数和游标。

例如，假设上例中 pageInfo.endCursor 的值为 Y3Vyc29yOnYyOpHOUH8B7g==，则可以使用以下查询请求下一页结果：

query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    pullRequests(first: 1, after: "Y3Vyc29yOnYyOpHOUH8B7g==") {
      nodes {
        createdAt
        number
        title
      }
      pageInfo {
        endCursor
        hasNextPage
        hasPreviousPage
      }
    }
  }
}

可以继续发送响应中返回新 pageInfo.endCursor 值的查询，直到不再有要遍历的页面（通过 pageInfo.hasNextPage 返回 false 来指示）为止。

如果指定了 last 参数而不是 first 参数，则将首先返回结果的最后一页。 在这种情况下，你将使用 pageInfo.startCursor 值和 before 参数来获取上一页结果。 pageInfo.hasPreviousPage 返回 false 时，则说明到达了最后一页。 例如：

query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    pullRequests(last: 1, before: "R3Vyc29yOnYyOpHOHcfoOg==") {
      nodes {
        createdAt
        number
        title
      }
      pageInfo {
        startCursor
        hasPreviousPage
      }
    }
  }
}

后续步骤

可以使用 GitHub 的 Octokit SDK 和 octokit/plugin-paginate-graphql 插件来支持在脚本中分页。 有关详细信息，请参阅“plugin-paginate-graphql.js”。