在 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”。