企业官网建设流程全解析

GitHub 官方 API 是几乎所有 CI/CD、机器人、自动化和数据统计脚本的地基。我在不同团队做开发工具这么多年，见过不少把 GitHub API 当成万能接口用的项目，也修过一堆因为不了解边界而翻车的故障：有的被限流卡到怀疑人生，有的把私有仓库信息误当成公开数据拉，有的反复轮询把自己账户的请求频率送进了二级限流名单。说白了，GitHub API 远比想象中强大，但它的强大是有明确范围的。这篇文章，我会把 REST 与 GraphQL 两条 API 主线的能力边界、认证权限、速率限制、数据边界和稳定拉取全量数据的实操细节一次讲清楚，目标读者是所有想要正经用 GitHub API 做自动化的开发者。

1. 两条 API 主线：REST v3 与 GraphQL v4 为什么能共存

GitHub 官方 API 从一开始就没有只走一条技术路线。到今天，你打开官方文档，会看到两条并列的主线：稳定了很多年的 REST API（文档上叫 v3）和 2017 年推出的 GraphQL API（文档上叫 v4）。不少刚接触 GitHub API 的人会困惑：为什么不干脆只留一个？为什么新项目还要在两个之间做选择？

1.1 REST v3：简单工具的第一选择

REST 版 API 的思路非常直接：一个 URL 对应一种资源，比如/repos/{owner}/{repo}就是仓库信息，/repos/{owner}/{repo}/issues就是 issue 列表，你用 GET、POST、PATCH、DELETE 这些动词去操作它。它的优点是直观、调试成本低，浏览器里输入 URL 就能看到一个 JSON 响应，curl 一句就能验证一个接口是否存在。

REST 也是当前生态支持最全面的那一条线。绝大多数官方 SDK（Octokit 系列、PyGitHub、gh 命令行工具）默认走的都是 REST 接口，社区里能搜到的例子也大多基于 REST。官方新增能力时，往往也是在 REST 上先提供预览版本，等稳定后再转正。所以如果你的需求是写脚本、做一次性统计、接一个简单的自动化流程，REST 几乎总是最稳的选择。

REST 的短板也很明显：响应返回的对象是固定的，你拿不到"只取某几个字段"这种自由。比如你只想看仓库的 star 数和更新时间，GET /repos/{owner}/{repo}依然会把一整个几百行的 JSON 扔给你。当你需要聚合多个资源的数据时，REST 容易让你陷入"先查列表，再逐个查详情"的循环，请求数量蹭蹭往上走，速率限制很快就见底。

1.2 GraphQL v4：为复杂查询设计的那扇门

GraphQL 版 API 解决的核心问题就是 REST 的两个痛点：按需取字段、一个请求拿多个关联资源。它只有一个端点https://api.github.com/graphql，所有操作都是 POST 一个查询字符串过去，你要什么字段就写什么字段，服务端只会返回你要求的那部分。

举个例子，你想知道最近 10 个 issue 分别属于哪个 label、每个 label 下又有多少个 open 状态的 issue。用 REST 写至少要发好几轮请求：先翻 issue 列表，再逐个查 label 详情。用 GraphQL 写，一次查询就能把这三层关系全部取回，而且结构是树状的，和你要的数据形状完全一致：

{ repository(owner: "octocat", name: "Hello-World") { issues(last: 10, states: OPEN) { nodes { title labels(last: 5) { nodes { name issues(states: OPEN) { totalCount } } } } } } }

这种能力让 GraphQL 特别适合做聚合查询、仪表盘数据、以及那种"一次请求里要跨多个仓库、多个团队、多个维度"的业务逻辑。

1.3 到底怎么选：一张表和一个判断原则

我个人的选型经验很简单：脚本和自动化默认 REST，需要聚合查询或前端需要细粒度数据时用 GraphQL。两者不是替代关系，而是互补关系。下面这张表是我常年放在笔记里的对照，基本能覆盖绝大多数决策场景：

还有一个很容易被忽略的判断维度：如果你要用的是某个还没被 GraphQL schema 覆盖的管理类端点，那么别犹豫，直接切 REST。GraphQL 虽然覆盖面广，但并不是把 REST 的每一个能力都平移过去了，有些运维和管理类操作至今只在 REST 里存在。两套文档我都习惯同时开着，遇到 GraphQL 查不到的类型，就去 REST 那边翻一下，往往能找到对应接口。

2. 认证与权限边界：令牌决定了你能看到什么

GitHub API 的第二个大边界是身份与权限。同一个接口，你用不同身份去调用，能拿到的数据可能差出天和地。很多自动化项目翻车，不是接口用错了，而是令牌的权限模型没搞明白。

2.1 匿名、个人令牌、OAuth 与 GitHub App

GitHub API 允许匿名访问，但是代价很大：匿名请求的速率限制只有每小时 60 次，而且只能读公开数据。这个额度连开发调试都不太够用，所以实际项目里你一定会有某种形式的认证。

目前主流的认证身份有四类，我按使用频率排个序：

• 个人访问令牌（Personal Access Token，PAT）：最常用的自动化身份。它代表的是某个用户账号，所以它的权限天然不能超过该用户自己的权限。
• OAuth App 令牌：用户通过 OAuth 授权流程换取代表自己的令牌，适合做"第三方网站让你用 GitHub 登录并读取数据"这类场景。
• GitHub App 安装令牌：以应用的身份代表"安装到某个仓库或组织"的权限，令牌有效期通常只有 1 小时，适合后台服务长期运行。
• SSH Key：严格说它不是 API 认证，而是 Git 协议认证，作用域是 Git 推送和拉取，不进 API 的速率限制体系。

这四类身份在 API 层面的权限表现完全不同。PAT 的权限是你这个账号的权限子集；OAuth 令牌还要叠加用户授权时的 scope；GitHub App 的权限不是继承某个用户的，而是应用自己声明注册的那套权限集。所以写自动化之前，先问清楚一个问题：这个令牌代表的是"我"还是"一个独立的应用"？这直接决定了后续所有接口调用的边界。

2.2 细粒度令牌改变了权限管理方式

个人访问令牌本身也在进化。早期只有经典 PAT（Classic PAT），它的权限是粗粒度的 scope 模式：勾一个repo，就等于拿到了该用户所有仓库的读写权限；勾一个admin:org，就能动所有组织设置。这种模式在真实团队里非常危险，一个泄露的经典令牌理论上可以把你名下所有仓库打包带走。

这两年官方主推的是细粒度 PAT（Fine-grained PAT），权限模型发生了本质变化：

• 可以只授权某几个仓库，而不是全部仓库；
• 每一项权限都拆得很细，比如"Contents: Read-only""Issues: Write""Actions: Read-only"；
• 强制设置有效期，到期自动失效；
• 可以限定 IP 范围。

我现在的建议是：新项目一律用细粒度 PAT，老项目里还能控制的经典 PAT 尽快迁移。尤其那种跑在 CI 里的令牌，以前图省事勾了repo全家桶，现在完全可以拆成"只对指定仓库有 Contents 和 Actions 权限"的细粒度令牌，即使泄露了，伤害半径也被缩小到了单个仓库。

2.3 404 与 403 的小心机：不要用错误码猜资源是否存在

有一个细节特别值得提，因为它会让排查问题的人怀疑人生：当你访问一个无权访问的私有仓库时，GitHub 返回的是 404 Not Found，而不是 403 Forbidden。

官方这么做的理由很明确：避免泄露资源的存在性。如果对"有权限但不存在"返回 404、对"存在但无权限"返回 403，那么攻击者只要反复试探，就能确认某个私有仓库是否真实存在。统一返回 404，相当于把所有"你不该知道"的情况一律伪装成"不存在"。

这也带来一个实际影响：排查权限问题时，只看到 404 不要立刻断定是路径写错了。先去检查令牌的权限设置，确认它是否有权访问该仓库。我踩过的坑是：用了一个只授权了仓库 A 的细粒度令牌去访问仓库 B，curl 一直报 404，我盯着 URL 看了半天，最后才发现是令牌权限根本没包含仓库 B。

2.4 最小权限和密钥轮换的实战建议

权限边界这条线，落实到工程实践上就三件事：

1. 令牌只授最小权限。写进 CI 的令牌，先想清楚它到底需要什么：能读代码就够了，别给写权限；能触发工作流就够了，别给管理员权限。
2. 轮换是制度，不是操作。每次成员离职、每次令牌可能泄露，都要立即轮换。细粒度 PAT 现在支持在后台创建多个互不影响的令牌，轮换成本很低。
3. 区分人和机器。凡是由后台服务长期使用、需要自动刷新的场景，优先考虑 GitHub App 安装令牌，而不是拿某个人的 PAT 顶着。GitHub App 的 1 小时短令牌机制，本身就是在帮你做"自动轮换"，即使泄露，能造成的影响窗口也非常小。

3. 速率限制的三种形态：5000次、30次和积分制

速率限制是 GitHub API 能力边界最硬的一条线。很多人第一次被限流时都会懵：明明请求量不算大，怎么突然 403 了？原因往往是你踩了某一类特殊的限制，而不是通用的 5000 次限额。

3.1 REST 的 5000 次/小时与 Search 的 30 次/分钟

在 REST API 下，认证请求的通用额度是每小时 5000 次。这个额度按令牌计算，不是按 IP 计算。也就是说，只要你有合法的认证令牌，5000 次配额就是归这个令牌所有的。

但有几个端点用的是另一套限制，最典型的是 Search API：

• 普通 REST 端点：认证后 5000 次/小时；
• 搜索端点：认证后 30 次/分钟；
• 匿名请求：所有端点合计 60 次/小时，搜索 10 次/分钟。

Search 为什么限制这么紧？因为搜索是跨全平台索引的高成本操作，它要在大规模的索引数据里做关键词匹配和排序，每次搜索消耗的服务器资源比普通获取单个资源的请求高得多。官方把搜索单独拎出来限速，本质是在保护整个搜索基础设施。

如果你的业务需要大量搜索请求，我的经验是：先用 GraphQL 的搜索查询尽量一次拿全，再把 30 次/分钟当成硬约束去做任务编排，不要在一个循环里连续发几十个搜索请求。曾经我写过一个批量关键词巡检脚本，前 30 个请求都好好的，第 31 个直接 403，整个任务中断，后面才知道是撞上了 Search 的独立配额。

3.2 GraphQL 的积分制与节点数限制

GraphQL API 用的不是"次数"而是"积分"（points）。默认额度同样是每小时 5000 积分，但每次查询消耗的积分不是固定的，而是根据你查询的复杂程度动态计算。大概的规则是：一个普通字段约等于 1 积分，复杂字段和嵌套查询会消耗更多积分。

除了积分制，GraphQL 还多了一层硬性限制：单次请求的节点数不能超过 500。所谓节点，是指你的查询在结果树上展开的连接点和对象数量。如果你一次查询 600 个 issue，每个 issue 又带上 author、labels、comments，很容易突破 500 节点上限，请求直接失败，报错会明确告诉你 node limit exceeded。

因此在使用 GraphQL 时，不要因为它能聚合就无限往一个查询里塞内容。一个常见的做法是把大查询拆成"先拿列表 id，再分页或分批取详情"的两阶段模式。虽然这看起来又回到了 REST 的老路，但在 GraphQL 的护栏下，这是保证请求稳定性的必要妥协。

3.3 响应头、304 条件请求和 Retry-After

速率限制不是只靠报错的 403 才知道。几乎所有 API 响应都会带一组X-RateLimit-*头，我每次写脚本都会先打印这个头，确认自己的消耗情况：

curl -I https://api.github.com/repos/octocat/Hello-World

响应头里可以看到X-RateLimit-Limit（总配额）、X-RateLimit-Remaining（剩余配额）、X-RateLimit-Reset（配额重置的 Unix 时间戳）。GraphQL 的请求里，你还可以直接查rateLimit字段拿到剩余点数。

还有一个非常实用的减负手段：条件请求。请求时带上If-None-Match: {ETag}或If-Modified-Since: {时间戳}，如果资源没有变化，GitHub 会返回304 Not Modified，而304 响应不计入速率限制配额。这对于"定时刷新某个仓库元数据"的场景极其有用。我维护的仓库状态监控脚本，就是靠 ETag 缓存把配额消耗降到了原来的十分之一。

当真的被限流时，响应头里会有Retry-After字段，告诉你等多少秒再试。此外还有一种更容易被忽略的"二级速率限制"（secondary rate limit）：即使你没超过 5000 次/小时，如果短时间并发太高、或者创建资源的频率太快，官方一样会返回 403，并在Retry-After头里告诉你冷却时间。这种限制没有公开的精确阈值，本质是反滥用机制。解决手段也很朴素：控制并发数，一次别开几十个线程去打 API；轮询间隔放宽；遇到 403 就退避重试，不要立刻重打。

4. 数据边界：能取到的数据与拿不到的数据

讨论能力边界，最终要回到一个实际问题：官方 API 到底能给我哪些数据，哪些数据是我无论如何也拿不到的？把这张"数据地图"画清楚，很多架构取舍就自然有了答案。

4.1 官方 API 完整覆盖的资源域

REST and GraphQL 的覆盖面已经相当广，我列一下我最常用到的几块：

• 仓库与内容：仓库元数据、文件内容（Contents API）、提交历史、分支、标签、releases、release 附件、Git 对象（blob/tree/commit/ref）。
• 协作数据：issues、pull requests、评论、review、label、milestone、assignee。
• 自动化设施：Actions 工作流、workflow run、job 日志、workflow dispatch、webhook 配置、部署密钥。
• 组织与用户：用户档案、组织信息、团队成员、团队成员权限、组织级别的 runner、projects 看板。
• 包与发布：GitHub Packages 元数据、releases、gists。
• 安全与治理（部分）：代码扫描告警、依赖告警，前提是仓库和令牌权限都允许。

这些能力足够支撑绝大多数自动化需求：机器人管理 issue、CI 触发 release、定时统计仓库活跃度、生成周报数据、同步团队权限等等。

4.2 API 替代不了 Git 协议和 Webhook

但官方 API 有一个非常明确的边界：它不提供完整的 Git 协议能力。你不能用 API 把一个本地仓库git push上去，也不能用 API 做完整的git pull。虽然 API 里有 Git Data 这一组端点，可以手动创建 blob、tree、commit、再更新 ref，理论上能"拼"一次推送出来，但这是极其底层的操作，生产环境里没人会这么干。

同样，API 也替代不了 Webhook。API 是"你去问，它才答"的拉模式，如果 GitHub 上发生了一个事件（比如有人 push 了代码），而你只想被动接收通知，API 并不合适。事件流的正确姿势是让 GitHub 的 Webhook 把事件 POST 到你的服务器，由你的服务主动处理。这个边界我从一开始就会提醒团队成员：凡是"实时响应"的需求，先想 Webhook；凡是"批量拉取、周期性统计"的需求，再想 API。

4.3 大文件、LFS 与 release asset 的体积边界

文件大小是另一个容易撞上的边界。GitHub 本身对仓库里的单个文件有限制：超过 50MB 会给出警告，超过 100MB 会被 Git 层直接拒绝。API 没法绕过这个限制，因为限制发生在 Git 协议那一层。

如果你想管理大型二进制文件，正确的路径是 Git LFS。但这里有个容易被忽略的坑：LFS 对象实际上不存放在仓库的 Git 对象里，API 的 Contents 接口如果读取一个 LFS 跟踪的文件，拿到的只是 LFS 指针文本，而不是真实的大文件内容。需要下载真实文件时，还得走 LFS 自己的传输协议。

release asset 也有体积上限，单个附件大约限制在 2GB 以内。超过这个量级，老老实实放到外部对象存储，release asset 只放下载链接。我见过有人试图把 5GB 的模型包传成 release asset，上传失败后才发现是撞上了 2GB 的硬边界。

4.4 搜索和 Events 不是强一致的实时数据

还有一类边界很隐蔽，就是数据一致性。很多人默认"官方 API 返回的就是最新的"，但在两个地方这个假设不成立：

• Search API 基于索引。新 push 的 commit、新创建的 issue，不会立刻出现在搜索结果里，索引更新有延迟，可能几秒也可能几十秒。如果你拿搜索结果的 total_count 当实时统计数据，数字几乎一定不准。
• Events API 是浅层事件流。它只暴露最近一段时间内的公开事件，不是完整历史，也不承担消息队列的功能。想基于事件做精准处理，还是要靠 Webhook，Webhook 才能保证事件的实时投递。

明白了这些，就能理解为什么很多成熟项目宁可自己维护一份数据快照，也不直接拿 API 的聚合接口当唯一数据源。API 是很好的"读取窗口"，但它不等于仓库内部的分布式数据库。

5. 稳定拉取全量数据：分页、增量与缓存的实际姿势

当你需要把一个仓库的 issues 全部拉下来、或者把某组织所有仓库的 star 数全部统计一遍时，你就进入了"批量拉数据"模式。这时候最考验对 API 边界的掌握程度。很多脚本跑到一半被限流、或者数据前后对不上，都是因为分页和增量策略设计得不对。

5.1 分页与 Link Header

REST API 的分页参数非常常规：per_page控制每页数量，默认 30，最大 100；page控制页码。写脚本时我一般直接把per_page设成 100，尽量用最少的请求拿最多的数据。

但不要自己去拼page=101这种 URL。官方推荐的方式是读响应头里的Link头，它会告诉你下一页、上一页、最后一页的相对地址。比如：

Link: <https://api.github.com/repositories?page=2>; rel="next", <https://api.github.com/repositories?page=34>; rel="last"

所有主流 SDK 都封装了 Link 头的解析。自己写脚本时，只要判断rel="next"是否存在即可，存在就继续循环，不存在就说明到末尾了。这个方法比硬编码页码要稳得多，因为服务端如果调整了游标策略，你的代码逻辑完全不用动。

5.2 用 since 和 updated 做增量拉取

拉全量数据只是第一步，真正有挑战的是"持续增量同步"。GitHub 的很多列表端点支持since参数，只返回在某个时间戳之后更新过的资源。比如拉取某个仓库的全部 issue，我可以先全量拉一次，记录下最后一条的updated_at，之后每次同步都用since=上次记录的时间，请求量直接从几千次降到了几十次。

这里有个经验：增量同步的时间字段要用 updated_at 而不是 created_at。因为一个旧 issue 可能被重新打开、新评论、改标签，这些操作都会改updated_at，只有跟踪这个字段，才不会漏掉状态变化的 issue。配合state=all一起用，能把已关闭的历史 issue 也纳入增量范围，避免数据脱节。

拉取活跃度很高的仓库时，还要注意排序的稳定性。比如按created排序的接口，如果同步期间有人新建了资源，下一页的边界会往后漂，可能出现重复数据。我的对策是：记录下上一条数据的唯一 id，并在合并时做一次去重，同时把同步批次的门槛设置为"只取 updated_at 大于上次同步时间"的数据，让重复范围尽量小。

5.3 条件请求缓存、重试策略与幂等

批量脚本的稳定性，很大程度上取决于你怎么处理错误。我把常见的状态码和处理方式整理成了下面这张表，贴在我们团队的 API 调用规范里：

重试策略上，我的原则是：只对 403 二级限流、429、5xx 做指数退避重试，其他错误一律先排查代码逻辑。指数退避的间隔可以用 1 秒起步，每次翻倍，最大到 60 秒左右，并且加一点随机抖动，避免所有任务在同一瞬间集中重试。

写入类操作还要考虑幂等性。比如创建一个 issue，如果请求超时了但服务端其实已经创建成功，你重试就会得到两个 issue。我的习惯是：创建前先查询是否存在某个唯一标识（比如标题里带的任务编号、或者一个自定义 label），创建后用返回的 id 做记录，下次重试前先查 id 是否已存在。

6. 以 Webhook 和 Git 协议补齐 API 的拼图

讲到这里，边界基本清晰了：API 负责按需读取和写入资源，但有三种事情它做不好——实时事件推送给不了、大文件传输不合适、Git 原生操作替代不了。要搭一套完整的工作流，还得把这些能力拼起来用。

6.1 Webhook：让 GitHub 主动把事件推给你

API 是拉模型，Webhook 是推模型。你在仓库设置里配置一个 Webhook，指定某些事件发生后把 JSON payload POST 到一个 URL，GitHub 就会把手伸过来找你，你完全不需要轮询。

我在生产环境最常用的 Webhook 事件是这几个：

• push：代码推送到分支时触发；
• issues：issue 创建、编辑、关闭时触发；
• pull_request：PR 打开、合并、review 时触发；
• release：发布新版本时触发；
• workflow_run：Actions 工作流完成时触发。

Webhook 的边界在于安全：任何人只要拿到你的回调 URL，就能伪造 GitHub 的 POST 请求。所以配置 Webhook 时一定要设置一个 secret，服务端收到请求后用 HMAC 校验签名。GitHub 会在请求头的X-Hub-Signature-256里带上签名，你只需要用配置的 secret 对请求体算一遍 HMAC-SHA256 并做比对即可。

6.2 GitHub Actions 与 API 的分工

另一个经常和 API 配合使用的是 GitHub Actions。很多人以为有了 Actions 就不再需要 API 了，其实是反过来的：Actions 提供的是"在 GitHub 的沙箱里执行代码"的能力，而 API 提供的是"程序化操作 GitHub 资源"的能力，两者经常协同工作。

比如发布流程可以这样设计：Webhook 收到release事件，触发一个 Actions 工作流跑测试和打包；工作流里再通过 API 调用上传 release asset、在 issue 里留下发布说明。反过来，你也可以通过 API 的workflow_dispatch端点，从一个外部系统（比如你公司的内部平台）主动触发某个 Actions 工作流，这相当于给 CI/CD 加了一个外部控制入口。

这个组合模式的好处是：外部系统不需要拿到仓库的完整 Git 权限，只需要一个能触发工作流的细粒度令牌；所有真正对代码库的写操作，都发生在 Actions 的受控环境里。

6.3 自动化工作流的组合模式

最后分享一个我在实际项目中反复使用的组合范式，它对中小团队特别适用：

1. 事件入口用 Webhook：把 GitHub 上的关键动作（push、PR、issue）推给自建服务；
2. 业务逻辑用自建服务调用 API：收到事件后，通过细粒度令牌调用 API 读取关联数据、打标签、加评论、写统计；
3. 重活交给 Actions：需要跑构建、跑测试、生成产物时，用 API 触发workflow_dispatch，让 Actions 去执行，产物通过 artifact 或 release asset 回传。

这样设计的核心价值，是把 GitHub API 的每一次调用都放在"最小必要权限、最小必要频率"的框架里，不会出现一个全局令牌到处飞、或者一个脚本无脑轮询的局面。

个人体会是，API 能力边界与其说是官方给你的限制，不如说是在引导你选择更合理的架构。我第一次做自动化机器人时，恨不得用 API 模拟出一切功能，后来撞了几次限流、查了几次 404 之后才明白：分清实时事件与批量查询、分清 API 与 Git 协议、分清只读令牌与写令牌，这些边界意识比会写几百行请求代码重要得多。只要把认证拆细、把轮询换成事件、把大查询切成增量，GitHub 官方 API 会是非常可靠且耐用的工具。