GitHub API分页机制概述
在使用github rest api获取资源列表时，例如获取用户列表（get /users），api通常会设置一个默认的返回数量上限，常见的是每页100条记录。这意味着如果需要获取超过100个用户，就必须采用分页机制。
对于GET /users端点，GitHub API提供了一个名为since的参数。这个参数接受一个用户ID，API会返回ID大于该用户ID的所有用户，从而实现“从某个点开始”获取后续数据的目的。通过不断更新since参数为上一页结果中最后一个用户的ID，我们就可以逐步遍历整个用户列表。
需要特别注意的是，GET /users端点是按照用户ID的升序来返回用户的，它不提供直接通过用户名字符串进行模糊匹配或过滤的功能。如果您的目标是根据用户名包含特定字符串来搜索用户，您应该使用GET /search/users端点，该端点支持通过q参数进行更复杂的查询，例如q=username_substring+in:login。本教程将专注于解决GET /users端点的分页问题。
使用 octokit.paginate 进行高效分页（推荐）
对于使用octokit库进行GitHub API交互的JavaScript/TypeScript项目，最推荐且最便捷的分页方式是使用其内置的paginate方法。octokit.paginate方法能够自动处理后续请求的逻辑，包括更新since参数、循环请求直到所有数据被获取，并将所有结果聚合成一个数组返回。这大大简化了分页代码的编写。
以下是使用octokit.paginate方法的示例代码：
import { Octokit } from "octokit";
// 初始化Octokit实例，如果需要认证，可以在这里传入auth token
const octokit = new Octokit({
// auth: 'YOUR_GITHUB_TOKEN' // 如果需要访问私有数据或提高速率限制，请提供认证token
});
async function getAllGitHubUsers() {
try {
console.log("正在通过octokit.paginate获取所有GitHub用户...");
// 使用paginate方法获取所有用户
// per_page 参数指定每页返回的数量，最大为100
const allUsers = await octokit.paginate("GET /users", {
per_page: 100, // 每页请求100个用户
headers: {
"X-GitHub-Api-Version": "2022-11-28", // 指定API版本
},
});
console.log(`成功获取到 ${allUsers.length} 个GitHub用户。`);
// console.log(allUsers); // 打印所有用户数据
return allUsers;
} catch (error) {
console.error("获取GitHub用户时发生错误:", error);
throw error;
}
}
// 调用函数
getAllGitHubUsers();代码解析：
- new Octokit({}): 创建一个Octokit实例。根据您的需求，可以传入认证令牌 (auth) 以提高API速率限制或访问受保护资源。
- octokit.paginate("GET /users", { ... }): 这是核心调用。第一个参数是API端点路径。第二个参数是一个对象，用于指定请求参数，例如per_page（每页获取数量，最大100）和headers（设置API版本等）。
- paginate方法会自动处理所有页面的请求，并将所有结果累积到一个数组中返回。当API返回的列表长度小于per_page时，paginate会认为已经到达列表末尾并停止请求。
手动实现分页逻辑
如果您不使用octokit库，或者希望对分页过程有更细粒度的控制，可以手动实现循环分页逻辑。这种方法涉及在一个循环中反复调用API，每次请求时更新since参数，直到获取到所有数据。
以下是手动实现分页逻辑的模拟代码：
// 这是一个模拟实现，用于说明手动分页的逻辑
// 实际生产环境应替换为真实的API请求库（如axios, fetch等）
async function getAllGitHubUsersManually() {
let allUsers = [];
let lastUserId = 0; // 初始时从第一个用户开始（ID为0或更小）
const perPage = 100; // 每页请求数量
let hasMoreUsers = true;
console.log("正在手动获取所有GitHub用户...");
while (hasMoreUsers) {
try {
// 模拟API请求
// 在实际应用中，这里会是 `await octokit.request('GET /users', { since: lastUserId, per_page: perPage, ... })`
// 或者 `await fetch(`https://api.github.com/users?since=${lastUserId}&per_page=${perPage}`, { ... })`
const response = await mockApiRequest(lastUserId, perPage); // 模拟函数
const currentUsers = response.data.users; // 假设API返回的数据结构
if (currentUsers && currentUsers.length > 0) {
allUsers = allUsers.concat(currentUsers);
// 更新lastUserId为当前批次中最后一个用户的ID
lastUserId = currentUsers[currentUsers.length - 1].id;
// 如果返回的用户数量小于perPage，说明已经到达列表末尾
if (currentUsers.length < perPage) {
hasMoreUsers = false;
}
} else {
// 如果没有返回用户，也说明已经到达列表末尾
hasMoreUsers = false;
}
console.log(`已获取 ${allUsers.length} 个用户，当前批次 ${currentUsers.length} 个。`);
} catch (error) {
console.error("手动获取GitHub用户时发生错误:", error);
hasMoreUsers = false; // 发生错误时停止循环
throw error;
}
}
console.log(`手动获取完毕，共 ${allUsers.length} 个GitHub用户。`);
return allUsers;
}
// 模拟API请求函数 (仅用于演示逻辑)
// 实际应用中需要替换为真实的API调用
async function mockApiRequest(sinceId, perPage) {
// 假设这是一个模拟的GitHub API响应
const mockUsers = [];
for (let i = 1; i <= 500; i++) { // 模拟总共有500个用户
mockUsers.push({ id: i, login: `user${i}` });
}
const startIndex = mockUsers.findIndex(user => user.id > sinceId);
if (startIndex === -1) {
return { data: { users: [] } }; // 没有更多用户
}
const usersSlice = mockUsers.slice(startIndex, startIndex + perPage);
return { data: { users: usersSlice } };
}
// 调用函数
getAllGitHubUsersManually();代码解析：
- allUsers: 用于存储所有获取到的用户数据。
- lastUserId: 记录上一次请求中最后一个用户的ID，用于下一次请求的since参数。初始值为0，表示从ID最小的用户开始。
- while (hasMoreUsers): 循环条件，只要可能还有更多用户就继续请求。
- 在每次循环中，构造带有since和per_page参数的API请求。
- 将当前请求返回的用户数据添加到allUsers数组中。
- 更新lastUserId为当前批次中最后一个用户的ID。
- if (currentUsers.length
注意事项
- API速率限制 (Rate Limiting): GitHub API对请求频率有严格限制。频繁的请求可能会导致您的IP被暂时封禁。在使用手动分页时尤其要注意，确保在请求之间有适当的延迟，或者使用认证令牌来提高速率限制。octokit.paginate通常会更好地管理这些限制。
- 错误处理: 在实际应用中，务必对API请求进行完善的错误处理，例如网络错误、API返回的错误状态码等。
- GET /users与GET /search/users的区别: 如前所述，GET /users用于按ID顺序获取用户列表，不
