在通过 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 参数的管理，代码更加简洁和健壮。
方法二：手动实现分页逻辑
在某些情况下，例如不使用 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
- lastUserId = currentUsers[currentUsers.length - 1].id;：更新 lastUserId 为当前页最后一个用户的ID，这是实现分页的关键。
注意事项与最佳实践
- API 速率限制： GitHub API 对未认证和已认证的请求都有速率限制。频繁或快速的请求可能会导致暂时封禁。在手动实现分页时，建议在每次请求之间添加适当的延迟（例如，使用 setTimeout），以避免触及速率限制。对于生产环境，务必使用认证令牌（如 Personal Access Token）来提高速率限制。
-
关于“包含指定字符串”的搜索： 原始问题提及按用户名包含指定字符串进行搜索。需要明确的是，/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 参数。
- 错误处理： 在实际应用中，务必加入健壮的错误处理机制，例如 try...catch 块，以应对网络问题、API 错误响应或数据解析失败等情况。
- 认证： 强烈建议使用 GitHub Personal Access Token (PAT) 进行认证。认证后的请求不仅拥有更高的速率限制，还能访问公共和私有仓库的更多数据。
- per_page 参数： per_page 参数的最大值通常为100。将其设置为大于100的值可能不会生效，API 仍会返回最多100个结果。
通过本文介绍的两种分页策略，您可以有效地克服 GitHub API 的100用户限制，无论是通过 Octokit 库的便捷方法，还是手动构建更精细的控制逻辑，都能实现完整、高效的用户列表检索。在选择方法时，请根据项目需求和对控制粒度的要求进行权衡。
