本文将详细介绍如何利用 Octokit 结合 GitHub API 的搜索功能，高效地查询指定 GitHub 组织下所有仓库的开放 Pull Request。针对传统 API 端点需要逐个仓库查询的痛点，本教程提供了一种通过 `/search/issues` 接口实现单次请求聚合查询的解决方案，并附带示例代码，帮助开发者优化其自动化脚本。
挑战：跨组织仓库查询开放 PR
在自动化管理 GitHub 组织时，一个常见的需求是获取该组织下所有仓库的开放 Pull Request (PR)。然而，GitHub API 中用于列出 PR 的标准端点（例如 /repos/{owner}/{repo}/pulls）通常需要指定具体的仓库名称。这意味着，如果一个组织拥有数十甚至上百个仓库，开发者可能需要遍历所有仓库，并对每个仓库单独发起 API 请求，这不仅效率低下，而且会显著增加 API 请求次数，容易触及速率限制。
尽管 GitHub 网页界面提供了一个便捷的全局搜索功能，允许用户通过 is:open is:pr org:my-org-name 这样的查询字符串来查看整个组织的开放 PR，但如何在 Octokit 或 GitHub API 中复现这一功能，而不必逐个仓库查询，是许多开发者面临的挑战。直接尝试 octokit.request('GET /pulls?q=...') 往往会收到 404 错误，因为 /pulls 端点通常不直接支持全局搜索参数。
解决方案：利用 GitHub 搜索 API
解决这一问题的关键在于使用 GitHub 的 搜索 API，特别是 /search/issues 端点。这个端点设计用于执行广泛的搜索查询，并且支持多种查询限定符，包括按组织筛选。尽管其名称是 issues，但它同样能够搜索并返回 Pull Request，因为在 GitHub 的底层模型中，Pull Request 也是一种特殊类型的 Issue。
通过 /search/issues 端点，我们可以构建一个包含 is:pr（表示是 Pull Request）、is:open（表示是开放状态）和 org:ORGANIZATION（表示在指定组织内）的查询字符串，从而实现单次 API 请求获取所有相关信息。
使用 Octokit 实现查询
以下是使用 Octokit 库在 JavaScript 中实现这一功能的示例代码：
import { Octokit } from "@octokit/rest";
async function listAllOpenPrsInOrg(organizationName, githubToken) {
const octokit = new Octokit({
auth: githubToken, // 确保使用具有足够权限的 GitHub Token
});
try {
const response = await octokit.request("GET /search/issues", {
q: `is:pr is:open org:${organizationName}`,
per_page: 100, // 每页结果数量，最大100
});
console.log(`在组织 ${organizationName} 中找到 ${response.data.total_count} 个开放 PR。`);
// 遍历并处理查询结果
response.data.items.forEach(pr => {
console.log(`PR #${pr.number}: ${pr.title} (仓库: ${pr.repository_url.split('/').pop()})`);
// 更多 PR 详细信息可以在 pr 对象中获取
});
return response.data.items;
} catch (error) {
console.error("查询 GitHub PR 时发生错误:", error);
if (error.status === 403 && error.response.headers['x-ratelimit-remaining'] === '0') {
console.error("API 速率限制已达到。请稍后重试。");
}
throw error;
}
}
// 示例调用
const myOrg = "your-organization-name"; // 替换为你的组织名称
const token = "YOUR_GITHUB_TOKEN"; // 替换为你的 GitHub Personal Access Token
// 确保 Token 具有 'repo' 或 'read:org' 权限
listAllOpenPrsInOrg(myOrg, token)
.then(prs => {
// console.log("所有开放 PR:", prs);
})
.catch(err => {
console.error("获取 PR 失败:", err);
});代码解析：
- import { Octokit } from "@octokit/rest";: 导入 Octokit 库。
- auth: githubToken: 初始化 Octokit 实例时，需要提供一个 GitHub Personal Access Token。该 Token 必须拥有足够的权限来访问组织信息和搜索 Pull Request（通常 repo 或 read:org 权限足够）。
- octokit.request("GET /search/issues", { ... }): 这是核心部分。我们直接调用 request 方法，指定 HTTP 方法为 GET，端点为 /search/issues。
-
q: \is:pr is:open org:${organizationName}``: 这是搜索查询字符串。
- is:pr: 确保只返回 Pull Request。
- is:open: 确保只返回开放状态的 Pull Request。
- org:${organizationName}: 将搜索范围限定在指定的组织内。
- per_page: 100: 设置每页返回的结果数量，GitHub 搜索 API 的最大值为 100。
搜索查询参数详解
GitHub 搜索 API 支持丰富的查询限定符，除了上述示例中使用的，还有很多其他有用的参数：
- is:pr: 匹配 Pull Request。
- is:issue: 匹配 Issue。
- is:open / is:closed: 匹配开放或关闭状态。
- org:ORGANIZATION: 限制搜索到特定组织。
- user:USERNAME: 限制搜索到特定用户。
- repo:OWNER/REPO: 限制搜索到特定仓库。
- author:USERNAME: 匹配特定作者创建的项。
- assignee:USERNAME: 匹配分配给特定用户的项。
- label:LABEL_NAME: 匹配带有特定标签的项。
- created:YYYY-MM-DD / updated:YYYY-MM-DD: 按创建或更新日期筛选。
- head:BRANCH_NAME / base:BRANCH_NAME: 针对 Pull Request，按源分支或目标分支筛选。
通过组合这些限定符，可以构建出非常精确的搜索查询。
优势与注意事项
优势：
- 高效性： 通过一次 API 请求即可获取整个组织的所有开放 PR，避免了遍历大量仓库的开销。
- 简洁性： 代码实现更为简洁，易于维护。
- 可扩展性： 适用于拥有大量仓库的组织，且易于添加更多搜索条件。
注意事项：
速率限制： GitHub 搜索 API 的速率限制通常比常规 REST API 更严格（例如，认证用户每分钟 30 次请求）。对于需要频繁查询或处理大量数据的场景，务必注意并实现适当的速率限制处理机制。
-
分页处理： 如果组织中的开放 PR 数量超过 per_page 设置的最大值（100），API 响应将只包含第一页数据。你需要手动处理分页来获取所有结果。Octokit 提供了 octokit.paginate 方法来简化这一过程：
const allPrs = await octokit.paginate("GET /search/issues", { q: `is:pr is:open org:${organizationName}`, per_page: 100, }); // allPrs 将是一个包含所有页码结果的数组 数据结构： /search/issues 返回的结果在 response.data.items 中，每个 item 对象代表一个 Pull Request（或 Issue），其结构与 pulls.list 返回的 PR 对象略有不同，但包含了大部分常用信息，例如 number、title、user、html_url、repository_url 等。
权限： 确保用于认证的 GitHub Token 具有足够的权限来执行搜索操作并访问目标组织的信息。
总结
通过利用 Octokit 结合 GitHub API 的 /search/issues 端点，开发者可以高效且便捷地查询指定 GitHub 组织下所有仓库的开放 Pull Request。这种方法避免了传统上需要逐个仓库查询的低效率问题，并通过灵活的查询字符串提供了强大的筛选能力。在实际应用中，务必注意处理 API 速率限制和分页，以确保脚本的健壮性和完整性。
