告别浏览器限制：用 GitHub CLI 的 gh api 命令直连 REST 与 GraphQL API 深度指南

告别浏览器限制：用 GitHub CLI 的 gh api 命令直连 REST 与 GraphQL API 深度指南

【免费下载链接】cliGitHub’s official command line tool项目地址: https://gitcode.com/GitHub_Trending/cli/cli

GitHub CLI 的gh api命令让开发者无需打开浏览器，就能直接在终端发起已认证的 GitHub REST API（v3）与 GraphQL API（v4）请求。它是官方命令行工具中最灵活的一把"万能钥匙"：一条命令即可完成查询、创建、嵌套参数、自动分页和 JSON 过滤，把浏览器里繁琐的点击操作变成可复用的脚本。本指南面向新手，带你从零掌握gh api的核心用法。

🎯 为什么需要 gh api 命令

GitHub 的大部分命令（如gh pr list、gh issue view）已经覆盖了日常操作，但总有场景需要"直达底层"：

• 调用官方尚未封装的高级接口（如项目 v2、自定义属性）
• 编写自动化脚本，批量处理仓库数据
• 探索 API 返回的完整 JSON 结构

gh api帮你绕开浏览器和 curl 手动拼 token 的麻烦，自动复用gh auth login的登录态，并输出美观的彩色 JSON。

💡 命令定义位于 pkg/cmd/api/api.go，并在主命令中注册：pkg/cmd/root/root.go

🚀 快速上手：第一条已认证请求

最简单的用法是给出一个 API 路径：

# 查看当前登录用户（等价于浏览器访问 /user） gh api /user # 列出当前仓库的 Releases gh api repos/{owner}/{repo}/releases

占位符魔法：{owner}、{repo}、{branch}会自动替换为当前目录所在仓库的信息，无需手敲仓库名。这个替换逻辑实现在 pkg/cmd/api/api.go 的fillPlaceholders函数中。

官方验收测试可直观看到两种请求的最小形态：

• REST 示例：acceptance/testdata/api/basic-rest.txtar
• GraphQL 示例：acceptance/testdata/api/basic-graphql.txtar

📡 REST API 实战：参数、方法与请求体

gh api默认使用 GET 请求；一旦添加参数，会自动切换为 POST（见 pkg/cmd/api/api.go）。常用参数组合：

-f与-F的区别（解析逻辑在 pkg/cmd/api/fields.go）：

• -f（raw-field）：值一律按字符串处理
• -F（field）：带"类型魔法"——true/false/null和整数自动转为对应 JSON 类型；@文件语法从文件读取值，@-从标准输入读取

嵌套参数支持key[subkey]=value与数组语法key[]=value1, key[]=value2，例如更新深层嵌套的自定义属性值：

gh api -X PATCH /orgs/{org}/properties/schema \ -F 'properties[][property_name]=environment' \ -F 'properties[][default_value]=production'

🔍 GraphQL API：一条命令直连 v4 接口

在路径参数中写graphql，即可访问 GraphQL 端点；除query外的所有字段会被自动归入 GraphQL 变量（见 pkg/cmd/api/http.go）：

gh api graphql -F owner='{owner}' -F name='{repo}' -f query=' query($name: String!, $owner: String!) { repository(owner: $owner, name: $name) { releases(last: 3) { nodes { tagName } } } } '

比 REST 更适合"一次性精确取数"——字段全由你自己指定，不多不少。

📄 分页详解：--paginate 与 --slurp

数据量超过一页时，手动翻页是最痛苦的部分，gh api内置了解决方案：

• REST：--paginate会解析响应的Link头自动请求下一页（实现见 pkg/cmd/api/pagination.go），并自动追加per_page=100提高效率；各页 JSON 数组会被无缝拼成一个连续数组输出
• GraphQL：查询需声明$endCursor: String变量并取回pageInfo { hasNextPage, endCursor }，--paginate会解析游标（findEndCursor，pkg/cmd/api/pagination.go）继续请求
• --slurp：把所有页包进一个外层 JSON 数组，方便交给jq做跨页统计

# 拉取用户全部仓库的 fork 占比 gh api graphql --paginate --slurp -f query='...' | jq '...'

✂️ 输出过滤：只留你需要的字段

原始 JSON 动辄上千行，两个内置参数让你"所见即所得"：

# 用 jq 语法只提取标题列表 gh api repos/{owner}/{repo}/issues --jq '.[].title' # 用 Go 模板渲染自定义表格 gh api repos/{owner}/{repo}/issues --template \ '{{range .}}{{.title}} ({{.labels | pluck "name" | join ", "}}){{"\n"}}{{end}}'

过滤结果适合直接管道给其他工具，实现完整的终端自动化工作流：

其他实用开关（定义见 pkg/cmd/api/api.go）：

🔗 相关源码与文档路径

想深入阅读实现，推荐从以下文件入手：

• 命令主逻辑与全部标志位：pkg/cmd/api/api.go
• 参数解析与类型转换：pkg/cmd/api/fields.go
• HTTP 请求构造：pkg/cmd/api/http.go
• 分页游标解析：pkg/cmd/api/pagination.go
• 项目整体文档目录：docs/

❓ 常见问题速答

Q1：提示 403 或权限不足怎么办？gh api复用gh auth登录态；若 token 权限不够，输出会附带授权建议（错误处理逻辑见 pkg/cmd/api/api.go）。重新gh auth refresh -s repo,read:org补充权限即可。

Q2：Windows 上报"invalid API endpoint"？PowerShell 可能把带前导斜杠的路径改写成磁盘路径，去掉开头的/即可（该检查位于 pkg/cmd/api/api.go）。

Q3：能访问非 github.com 的实例吗？可以，用--hostname或环境变量GH_HOST指定目标主机。

Q4：gh api 和 gh search / gh repo view 等高阶命令怎么选？日常操作优先用高阶命令，输出更友好、更易读（如 docs/primer/components/images/Detail-gh-issue-view.png 所示的 Issue 视图）；需要细粒度 JSON、批量处理或调用未封装接口时，交给gh api。

掌握gh api，你的终端就拥有了 GitHub 数据的全部入口——从一行查询到复杂自动化脚本，都只隔一条命令的距离。

【免费下载链接】cliGitHub’s official command line tool项目地址: https://gitcode.com/GitHub_Trending/cli/cli