优化 GitHub API 用户列表获取：高效分页策略

在通过 github rest api 获取用户列表时，开发者常会遇到一个限制：默认的 /users 端点单次请求最多只能返回100个用户。这对于需要获取大量甚至全部 github 用户信息的场景来说，显然是不够的。本文将深入探讨如何利用 github api 的分页机制，高效、完整地检索用户数据。

理解 GitHub API 的分页机制

GitHub API 的 /users 端点通过 since 参数实现分页。since 参数接受一个用户ID，API 会返回ID大于该指定ID的所有用户，并按ID升序排列。通过不断更新 since 参数为上一次请求返回的最后一个用户的ID，我们可以逐步遍历所有用户。

例如，首次请求可以不带 since 参数（或设为0），获取前100个用户。然后，将这100个用户中最后一个用户的ID作为下一次请求的 since 值，即可获取接下来的100个用户，依此类推，直到请求返回的用户数量不足100（或为空），表明已到达列表末尾。

方法一：使用 Octokit 的 paginate 方法 (推荐)

对于使用 Octokit 库的 JavaScript/TypeScript 项目，最推荐且最便捷的方式是利用其内置的 paginate 方法。paginate 方法能够自动处理 since 参数的更新和多次请求的循环，将所有分页结果聚合到一个数组中返回，极大地简化了代码。

import { Octokit } from "octokit";

// 初始化 Octokit 实例
// 如果需要更高的速率限制或访问私有数据，请在此处配置认证令牌
const octokit = new Octokit({
  // auth: 'YOUR_GITHUB_TOKEN'
});

async function getAllGitHubUsersPaginated() {
  try {
    // 使用 paginate 方法自动处理分页
    // "GET /users" 是要请求的端点
    // per_page: 100 是每页最大用户数，也是 GitHub API 的默认最大值
    const allUsers = await octokit.paginate("GET /users", {
      per_page: 100,
      headers: {
        "X-GitHub-Api-Version": "2022-11-28", // 指定 API 版本
      },
    });

    console.log(`成功获取到 ${allUsers.length} 个用户。`);
    // allUsers 将是一个包含所有分页结果的数组
    return allUsers;
  } catch (error) {
    console.error("获取 GitHub 用户时发生错误:", error);
    throw error;
  }
}

// 调用示例
// getAllGitHubUsersPaginated().then(users => {
//   // 在这里处理获取到的所有用户数据
//   // console.log(users[0]); // 例如，查看第一个用户
// });

代码解析：

• octokit.paginate("GET /users", { ... })：这是核心调用。它指示 Octokit 库对 /users 端点执行分页请求。
• per_page: 100：指定每页返回的用户数量。GitHub API 允许的最大值为100。
• headers: { "X-GitHub-Api-Version": "2022-11-28" }：指定请求的 API 版本，这是一个良好的实践。

paginate 方法的优势在于其抽象性，开发者无需关心底层的循环逻辑和 since 参数的管理，代码更加简洁和健壮。

GitHub Copilot

GitHub AI编程工具，实时编程建议

48

查看详情

方法二：手动实现分页逻辑

在某些情况下，例如不使用 Octokit 库、需要更细粒度的控制，或者集成到现有自定义网络请求逻辑中时，可能需要手动实现分页。这种方法涉及一个循环，在每次迭代中更新 since 参数。

// 模拟手动分页逻辑
async function getAllGitHubUsersManually() {
  let users = [];
  let lastUserId = 0; // 从ID为0之后开始列出用户
  const perPage = 100; // 每页用户数

  while (true) {
    try {
      // 构造 API 请求 URL
      const apiUrl = `https://api.github.com/users?since=${lastUserId}&per_page=${perPage}`;

      // 发送 HTTP 请求
      const response = await fetch(apiUrl, {
        headers: {
          'X-GitHub-Api-Version': '2022-11-28',
          // 如果需要认证，请在此处添加 Authorization 头
          // 'Authorization': 'token YOUR_GITHUB_TOKEN'
        }
      });

      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }

      const currentUsers = await response.json();

      if (currentUsers.length === 0) {
        // 如果当前页没有返回任何用户，说明已经没有更多用户了
        break;
      }

      // 将当前页的用户添加到总列表中
      users = users.concat(currentUsers);

      if (currentUsers.length < perPage) {
        // 如果当前页返回的用户数量少于每页限制，说明已到达最后一页
        break;
      }

      // 更新 lastUserId 为当前页最后一个用户的ID，用于下一次请求
      lastUserId = currentUsers[currentUsers.length - 1].id;

      // 实际应用中，为了避免速率限制，可能需要在这里添加延迟
      // await new Promise(resolve => setTimeout(resolve, 1000)); 

    } catch (error) {
      console.error("手动获取 GitHub 用户时发生错误:", error);
      break; // 发生错误时退出循环
    }
  }
  console.log(`手动获取到 ${users.length} 个用户。`);
  return users;
}

// 调用示例
// getAllGitHubUsersManually().then(users => {
//   // 在这里处理获取到的所有用户数据
//   // console.log(users[0]);
// });

代码解析：

• lastUserId：跟踪上次请求的最后一个用户ID，用于下一次请求的 since 参数。
• while (true)：一个无限循环，直到满足退出条件。
• fetch(apiUrl, { ... })：使用 Web API 的 fetch 函数发送 HTTP 请求。
• response.json()：解析响应体为 JSON 格式。
• users = users.concat(currentUsers)：将当前页的用户数据合并到总列表中。
• 退出条件：
  • currentUsers.length === 0：没有返回任何用户，表示列表已遍历完。
  • currentUsers.length < perPage：返回的用户数量少于每页限制，表示已是最后一页。
• lastUserId = currentUsers[currentUsers.length - 1].id;：更新 lastUserId 为当前页最后一个用户的ID，这是实现分页的关键。

注意事项与最佳实践

1. API 速率限制： GitHub API 对未认证和已认证的请求都有速率限制。频繁或快速的请求可能会导致暂时封禁。在手动实现分页时，建议在每次请求之间添加适当的延迟（例如，使用 setTimeout），以避免触及速率限制。对于生产环境，务必使用认证令牌（如 Personal Access Token）来提高速率限制。
2. 关于“包含指定字符串”的搜索： 原始问题提及按用户名包含指定字符串进行搜索。需要明确的是，/users 端点主要用于按ID顺序列表用户，不直接支持按用户名子串进行高级搜索。如果您的核心需求是搜索包含特定字符串的用户，您应该使用 GitHub 的 /search/users 端点。例如：

   // 搜索用户名中包含 "string" 的用户
   await octokit.request('GET /search/users', {
     q: 'string in:login', // 'in:login' 表示在用户名中搜索
     per_page: 100,
     headers: {
       'X-GitHub-Api-Version': '2022-11-28'
     }
   });

   登录后复制

   /search/users 端点也有其自己的分页机制，通常使用 page 参数和 per_page 参数。

3. 错误处理： 在实际应用中，务必加入健壮的错误处理机制，例如 try...catch 块，以应对网络问题、API 错误响应或数据解析失败等情况。
4. 认证： 强烈建议使用 GitHub Personal Access Token (PAT) 进行认证。认证后的请求不仅拥有更高的速率限制，还能访问公共和私有仓库的更多数据。
5. per_page 参数： per_page 参数的最大值通常为100。将其设置为大于100的值可能不会生效，API 仍会返回最多100个结果。

通过本文介绍的两种分页策略，您可以有效地克服 GitHub API 的100用户限制，无论是通过 Octokit 库的便捷方法，还是手动构建更精细的控制逻辑，都能实现完整、高效的用户列表检索。在选择方法时，请根据项目需求和对控制粒度的要求进行权衡。

以上就是优化 GitHub API 用户列表获取：高效分页策略的详细内容，更多请关注php中文网其它相关文章！