在 Go 程序里调用 GitHub REST 接口的客户端库（go-github）

自己写 HTTP 请求调用 GitHub 接口，麻烦的地方不在发请求，而在认证、分页、限流响应、时间字段格式这些边角。GitHub 的 REST API v3 有几百个端点，每个端点的参数形态和返回结构都不一样，手写一遍再维护一遍成本很高。go-github 做的就是把这一层包起来，让你用 Go 结构体和方法去调接口。

go-github 是 Google 维护的 Go 客户端库，把 GitHub REST API v3 封装成按服务划分的方法，传入访问令牌与请求参数，返回 Go 结构体与错误，供 Go 程序读写仓库、Issue、Pull Request。客户端对象按资源拆成 Organizations、Repositories、PullRequests 这类服务，调用方式与 GitHub 官方 API 文档的章节结构一一对应。

典型的使用者是用 Go 写自动化的人：CI 里跑的发版机器人、批量给几百个仓库改配置的运维脚本、把 GitHub 数据同步进内部平台的后端服务、按标签整理 Issue 的小工具。这些场景的共同点是需要在程序里长期调用 GitHub 接口，而且希望调用代码能被编译器检查。

主要功能

• 按服务划分的客户端：先构造 github.NewClient()，再从客户端上取不同的服务对象访问 GitHub API 的不同部分。例如列出一个用户的全部组织：orgs, _, err := client.Organizations.List(context.Background(), "willnorris", nil)。服务的划分方式与 GitHub API 文档的章节结构一致，找方法时可以直接对照官方文档。
• 可选的请求参数对象：接口带可选参数时，用一个后缀为 Options 的结构体传进去。例如列出 github 组织的公开仓库：opt := &github.RepositoryListByOrgOptions{Type: "public"}，再调 client.Repositories.ListByOrg(context.Background(), "github", opt)。
• 访问令牌认证：用 github.WithAuthToken("... your access token ...") 这个选项方法配置 OAuth 令牌，个人访问令牌就属于这一类，除 GitHub App 之外的大多数场景用它。README 明确提醒，认证过的客户端所有调用都会带上该令牌，因此几乎不应该在不同用户之间共用一个认证客户端。
• 自定义传输层与 HTTP 客户端：github.WithTransport 可以传入自己实现的 http.RoundTripper 来处理认证，github.WithHTTPClient 可以直接传一个 http.Client。需要 OAuth 令牌自动刷新时，可以配合 golang.org/x/oauth2 里的 oauth2.Transport。需要 HTTP Basic 认证的接口，用仓库提供的 BasicAuthTransport。
• GitHub App 认证：由外部包承担，README 点名了 bradleyfalzon/ghinstallation 与 jferrl/go-githubauth 两个。前者提供实现 http.RoundTripper 的 Transport，后者提供 NewApplicationTokenSource 与 NewInstallationTokenSource 两个令牌源，配 oauth2.NewClient 后再交给 github.WithHTTPClient。README 提示大多数端点要访问令牌认证，少数端点（例如 GET /app/hook/deliveries）要 JWT 认证，用哪一种取决于你要调哪个接口。
• context 支持：每个调用都接收 context.Context，取消信号与超时可以直接传到请求上。手上没有现成的 context 时，用 context.Background() 起步。
• 限流说明：README 有一节专讲 Rate Limiting，说明 GitHub 对所有 API 客户端都设了限制，primary rate limit 指客户端在一段时间内能发出的 REST 请求数量上限，目的是防滥用和拒绝服务。这一节给的是概念解释，仓库里没有说明库本身是否自动重试或自动等待。
• 样例代码与发版说明工具：example/ 目录放示例片段。想查两次发布之间发生了什么变化，先 clone 仓库，再跑 go run tools/gen-release-notes/main.go --tag v92.0.0。仓库顶层还有 otel/、scrape/、script/、test/、tools/ 等目录，事实表只给出目录名，没有给出它们各自的职责说明。

安装与依赖

项目以 Go module 形式发布，模块模式下直接用 go get 拉取：

go get github.com/google/go-github/v92

也可以在代码里 import 之后再跑不带参数的 go get：

import "github.com/google/go-github/v92/github"

要用主干上最新的代码（不是发布版），命令是 go get github.com/google/go-github/v92@master。

Go 版本方面，go-github 遵循 Go 官方的版本支持策略，支持最近两个大版本的所有 minor 版本，go.mod 里的 go 指令反映的就是这一点。README 提到从 Go 1.26 起，go.mod 中的 go 指令声明的是硬性最低版本，并且这个值必须不小于所有依赖的 go 行，结果是本库默认会要求 N-1 这个 Go 大版本。旧版本 Go 会不会坏，作者说会尽量不弄坏，但没有对更老的版本做显式测试。

用 GraphQL API v4 的话，README 推荐的是另一个库 shurcooL/githubv4，go-github 本身针对的是 REST API v3。

最短能跑通的用法

构造客户端后直接调用服务方法即可。下面这段来自 README，列出用户 willnorris 的所有组织：

client, err := github.NewClient()
if err != nil {
    // Handle error.
}

orgs, _, err := client.Organizations.List(context.Background(), "willnorris", nil)

调用带令牌的客户端，只多一个选项：

client, err := github.NewClient(github.WithAuthToken("... your access token ..."))
if err != nil {
    // Handle error.
}

换成 GitHub App 认证时，用 ghinstallation 建好传输层再注入客户端：

itr, err := ghinstallation.NewKeyFromFile(http.DefaultTransport, 1, 99, "2016-10-19.private-key.pem")
if err != nil {
    // Handle error.
}

client, err := github.NewClient(github.WithTransport(itr))

README 还提示，要与某些接口交互，比如往仓库写文件，得先用 GitHub App 的 installation ID 生成安装令牌，再按上面的 OAuth 方式认证。

关键参数

• github.NewClient(opts ...ClientOptions)：客户端入口，不传选项就是匿名客户端，受更严格的限流约束。
• github.WithAuthToken(token)：用访问令牌认证，适合个人访问令牌场景。
• github.WithTransport(rt)：传入自定义 http.RoundTripper，GitHub App 认证走这条路。
• github.WithHTTPClient(c)：传入自定义 http.Client，配合 oauth2.NewClient 做令牌自动刷新。
• github.BasicAuthTransport：用于需要 HTTP Basic 认证的接口。
• github.RepositoryListByOrgOptions{Type: "public"}：可选参数结构体，字段名对应 GitHub 接口的查询参数。
• context.Background()：没有现成 context 时的起点，实际服务里建议换成带超时的 context。

结果在哪里看

这个库本身不写输出文件，也不打印报告。调用返回三个值：请求到的数据（通常是结构体或结构体切片）、响应相关信息、以及 error。README 的示例里，第二个返回值一般用 _ 忽略，只在需要看限流或分页细节时才接住。数据在哪，取决于你自己的程序把它写到哪里——数据库、标准输出还是模板渲染，仓库里没有规定。

接口对不对、字段叫什么，看 pkg.go.dev 上的文档页：https://pkg.go.dev/github.com/google/go-github/v89/github（项目主页给的是 v89 的地址，当前发布版已到 v92）。更细的调用例子在仓库的 example/ 目录。

实际使用中的坑

• 迭代器遇上不正确的分页选项会死循环：有用户反馈跑 client.Users.ListAllIter 时陷入无限循环，追查到 client.Users.ListAll 对分页参数的处理上。该 Issue 已解决。
• 部分接口的返回结构与该库的类型对不上：Repositories.ListCommitActivity 抛过 json: cannot unmarshal object into Go value of type []*github.WeeklyCommitActivity，即接口返回的是对象，代码期待的是切片。该 Issue 已解决。
• 未受保护的分支会拿 404 当错误抛出：查询分支保护的状态检查时，未受保护的分支返回 404，库直接抛错，而用户期望的是返回空的必需检查列表。该 Issue 已解决。
• 时间字段解析：有用户遇到 GitHub Actions 返回的时间格式无法按 RFC3339 解析而报错，报错信息形如 parsing time "8/18/2019 7:44:51 PM" as "2006-01-02T15:04:05Z07:00"。该 Issue 已解决。
• 大版本升级经常带破坏性改动：从发布说明看，v88.0.0 把 App installation 的 Find* 方法改名为 Get*；v89.0.0 把部署相关请求体改为按值传递；v91.0.0 把 PullRequestsService 上的 EditComment 改名为 UpdateComment，并拆分了评审评论的请求体；v92.0.0 又把 Codespaces 相关请求体改为按值传递，并重命名成以 Request 结尾的类型。仓库里有一条待解决 Issue 正是讨论把指针参数全量重构为值参数，这类改动的来源就在那里。
• 低质量 PR 的涌入：仓库里有一条待解决的 Issue，标题是提醒不要提交 AI 生成的劣质 PR，作者说最近收到大量连自己都没在界面上看过一遍的 PR。这条与使用者关系不大，但如果你打算提 PR，值得先读一遍。

和同类放在一起看

下面两个对比项与 go-github 属于同一类东西，都是官方或社区维护的 GitHub API 客户端，只是语言不同。

反过来说，如果你的服务不是 Go 写的，go-github 对你完全没有用，该去用 octokit.rb 或 php-github-api 这类对应语言的入口，硬凑一层跨语言的调用只会更麻烦。就算技术栈是 Go，如果你要调的是 GraphQL API v4，也得换成 README 推荐的 shurcooL/githubv4。真正该用 go-github 的情况只有一种：Go 项目里要长期、结构化地调 GitHub REST v3，并且愿意跟着大版本做升级。

适合谁

适合用 Go 写自动化的人：CI 机器人、批量仓库管理脚本、把 GitHub 数据同步进内部系统的后端、需要按标签或状态整理 Issue 的小工具。也适合想给团队做一个 GitHub 集成面板、又不希望自己处理认证和分页细节的开发者。

不适合只想临时跑一次接口的人，那种场景 curl 更快。不适合用非 Go 语言写服务的人。也不适合只想调 GraphQL API v4 的人，README 明确把这类需求指向了别的库。项目采用 BSD-3-Clause 许可证，主要语言是 Go（占比 99.8%），仓库在 https://github.com/google/go-github，当前 Star 11311、Fork 2554、开放 Issue 48。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 10.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。