在 REST API 中使用分页

关于分页

当 REST API 的响应包含许多结果时，GitHub 会对结果进行分页并返回结果的一个子集。例如，GET /repos/octocat/Spoon-Knife/issues 仅返回 octocat/Spoon-Knife 代码仓库中的 30 个问题，即使该代码仓库包含超过 1600 个开放问题。这使得服务器和用户更容易处理响应。

您可以使用响应中的 link 头请求其他页面的数据。如果某个端点支持 per_page 查询参数，则可以控制每页返回的结果数。

本文演示了如何为分页响应请求其他页面的结果，如何更改每页返回的结果数，以及如何编写脚本以获取多页的结果。

使用 link 头

当响应被分页时，响应头将包含一个 link 头。如果端点不支持分页，或者所有结果都适合一页，则会省略 link 头。

link 头包含可用于获取其他页面的结果的 URL。例如，结果的前一页、下一页、第一页和最后一页。

要查看特定端点的响应头，您可以使用 curl、GitHub CLI 或您用于发出请求的库。要查看使用库发出请求时的响应头，请遵循该库的文档。要查看使用 curl 或 GitHub CLI 时响应头，请在请求中传递 --include 标志。例如

curl --include --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json"

如果响应被分页，则 link 头将如下所示

link: <https://api.github.com/repositories/1300192/issues?page=2>; rel="prev", <https://api.github.com/repositories/1300192/issues?page=4>; rel="next", <https://api.github.com/repositories/1300192/issues?page=515>; rel="last", <https://api.github.com/repositories/1300192/issues?page=1>; rel="first"

link 头提供了结果的前一页、下一页、第一页和最后一页的 URL

• 前一页的 URL 后跟 rel="prev"。
• 下一页的 URL 后跟 rel="next"。
• 最后一页的 URL 后跟 rel="last"。
• 第一页的 URL 后跟 rel="first"。

在某些情况下，仅提供这些链接的一部分。例如，如果您位于结果的第一页，则不会包含前一页的链接，如果无法计算最后一页，则不会包含最后一页的链接。

您可以使用 link 头中的 URL 请求另一页的结果。例如，要根据前面的示例请求最后一页的结果

curl --include --request GET \
--url "https://api.github.com/repositories/1300192/issues?page=515" \
--header "Accept: application/vnd.github+json"

link 头中的 URL 使用查询参数来指示要返回结果的哪一页。link URL 中的查询参数可能因端点而异，但是每个分页端点都将使用 page、before/after 或 since 查询参数。（某些端点将 since 参数用于分页以外的其他用途。）在所有情况下，您都可以使用 link 头中的 URL 获取其他页面的结果。有关查询参数的更多信息，请参阅“REST API 入门”。

更改每页项目数

如果某个端点支持 per_page 查询参数，则可以控制每页返回的结果数。有关查询参数的更多信息，请参阅“REST API 入门”。

例如，此请求使用 per_page 查询参数每页返回两个项目

curl --include --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json"

per_page 参数将自动包含在 link 头中。例如

link: <https://api.github.com/repositories/1300192/issues?per_page=2&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=2&page=7715>; rel="last"

使用脚本进行分页

无需手动复制 link 头中的 URL，您可以编写脚本以获取多页的结果。

以下示例使用 JavaScript 和 GitHub 的 Octokit.js 库。有关 Octokit.js 的更多信息，请参阅“REST API 入门”和Octokit.js 自述文件。

使用 Octokit.js 分页方法的示例

要使用 Octokit.js 获取分页结果，您可以使用 octokit.paginate()。octokit.paginate() 将获取下一页的结果，直到到达最后一页，然后将所有结果作为单个数组返回。一些端点将分页结果作为对象中的数组返回，而不是将分页结果作为数组返回。即使原始结果是对象，octokit.paginate() 始终返回一个项目数组。

例如，此脚本获取 octocat/Spoon-Knife 代码仓库中的所有问题。尽管它一次请求 100 个问题，但该函数在到达数据的最后一页之前不会返回。

import { Octokit } from "octokit";

const octokit = new Octokit({ });

const data = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 100,
  headers: {
    "X-GitHub-Api-Version": "2022-11-28",
  },
});

console.log(data)

import { Octokit } from "octokit";

const octokit = new Octokit({ });

const data = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 100,
  headers: {
    "X-GitHub-Api-Version": "2022-11-28",
  },
});

console.log(data)

您可以向 octokit.paginate() 传递一个可选的映射函数，以便在到达最后一页之前结束分页或通过仅保留响应的一个子集来减少内存使用量。您还可以使用 octokit.paginate.iterator() 一次迭代一页，而不是请求每一页。有关更多信息，请参阅Octokit.js 文档。

创建分页方法的示例

如果您使用的是另一种没有分页方法的语言或库，则可以构建自己的分页方法。此示例仍使用 Octokit.js 库发出请求，但不依赖于 octokit.paginate()。

getPaginatedData 函数使用 octokit.request() 向端点发出请求。响应中的数据由 parseData 处理，parseData 处理没有返回数据或返回的数据是对象而不是数组的情况。然后将处理后的数据追加到一个列表中，该列表包含迄今为止收集的所有分页数据。如果响应包含 link 头，并且 link 头包含下一页的链接，则该函数使用 RegEx 模式（nextPattern）获取下一页的 URL。然后，该函数重复前面的步骤，现在使用此新 URL。一旦 link 头不再包含指向下一页的链接，就会返回所有结果。

import { Octokit } from "octokit";

const octokit = new Octokit({ });

async function getPaginatedData(url) {
  const nextPattern = /(?<=<)([\S]*)(?=>; rel="Next")/i;
  let pagesRemaining = true;
  let data = [];

  while (pagesRemaining) {
    const response = await octokit.request(`GET ${url}`, {
      per_page: 100,
      headers: {
        "X-GitHub-Api-Version":
          "2022-11-28",
      },
    });

    const parsedData = parseData(response.data)
    data = [...data, ...parsedData];

    const linkHeader = response.headers.link;

    pagesRemaining = linkHeader && linkHeader.includes(`rel=\"next\"`);

    if (pagesRemaining) {
      url = linkHeader.match(nextPattern)[0];
    }
  }

  return data;
}

function parseData(data) {
  // If the data is an array, return that
    if (Array.isArray(data)) {
      return data
    }

  // Some endpoints respond with 204 No Content instead of empty array
  //   when there is no data. In that case, return an empty array.
  if (!data) {
    return []
  }

  // Otherwise, the array of items that we want is in an object
  // Delete keys that don't include the array of items
  delete data.incomplete_results;
  delete data.repository_selection;
  delete data.total_count;
  // Pull out the array of items
  const namespaceKey = Object.keys(data)[0];
  data = data[namespaceKey];

  return data;
}

const data = await getPaginatedData("/repos/octocat/Spoon-Knife/issues");

console.log(data);

import { Octokit } from "octokit";

const octokit = new Octokit({ });

async function getPaginatedData(url) {
  const nextPattern = /(?<=<)([\S]*)(?=>; rel="Next")/i;
  let pagesRemaining = true;
  let data = [];

  while (pagesRemaining) {
    const response = await octokit.request(`GET ${url}`, {
      per_page: 100,
      headers: {
        "X-GitHub-Api-Version":
          "2022-11-28",
      },
    });

    const parsedData = parseData(response.data)
    data = [...data, ...parsedData];

    const linkHeader = response.headers.link;

    pagesRemaining = linkHeader && linkHeader.includes(`rel=\"next\"`);

    if (pagesRemaining) {
      url = linkHeader.match(nextPattern)[0];
    }
  }

  return data;
}

function parseData(data) {
  // If the data is an array, return that
    if (Array.isArray(data)) {
      return data
    }

  // Some endpoints respond with 204 No Content instead of empty array
  //   when there is no data. In that case, return an empty array.
  if (!data) {
    return []
  }

  // Otherwise, the array of items that we want is in an object
  // Delete keys that don't include the array of items
  delete data.incomplete_results;
  delete data.repository_selection;
  delete data.total_count;
  // Pull out the array of items
  const namespaceKey = Object.keys(data)[0];
  data = data[namespaceKey];

  return data;
}

const data = await getPaginatedData("/repos/octocat/Spoon-Knife/issues");

console.log(data);