---

name: use-graphql-api description: > 通过命令行与 GraphQL API 交互——通过内省发现 Schema、构造查询和变更操作、 使用 gh api graphql 或 curl 执行、用 jq 解析响应，并通过 ID 管道链接操作。 适用于通过 GraphQL 自动化 GitHub Discussions、Issues 或 Projects、从脚本 集成任意 GraphQL 端点，或构建需要结构化 API 数据的 CLI 工作流。 license: MIT allowed-tools: Read Write Edit Bash Grep Glob WebFetch metadata: author: Philipp Thoss version: "1.0" domain: web-dev complexity: intermediate language: multi tags: graphql, api, github, query, mutation, introspection locale: zh-CN source_locale: en source_commit: 6f65f316 fence_basis_commit: 6f65f316 translator: claude-opus-4-6 translation_date: 2026-03-16

使用 GraphQL API

从命令行发现、构造、执行并链接 GraphQL 操作。

适用场景

• 通过 GraphQL 端点（GitHub、Hasura、Apollo 等）查询或修改数据
• 自动化需要 GraphQL 的 GitHub 操作（Discussions、Projects v2）
• 构建从 GraphQL API 获取结构化数据的 Shell 脚本
• 链接多个 GraphQL 调用，将前一个调用的输出传入下一个

输入

• 必需：GraphQL 端点 URL 或服务名称（如 github）
• 必需：操作意图（读取或写入的数据内容）
• 可选：认证令牌或方式（默认：GitHub 使用 gh CLI 认证）
• 可选：输出格式偏好（原始 JSON、jq 过滤、变量赋值）

步骤

第 1 步：发现 Schema

确定可用的类型、字段、查询和变更。

针对 GitHub：

# List available query fields
gh api graphql -f query='{ __schema { queryType { fields { name description } } } }' \
  | jq '.data.__schema.queryType.fields[] | {name, description}'

# List available mutation fields
gh api graphql -f query='{ __schema { mutationType { fields { name description } } } }' \
  | jq '.data.__schema.mutationType.fields[] | {name, description}'

# Inspect a specific type
gh api graphql -f query='{
  __type(name: "Repository") {
    fields { name type { name kind ofType { name } } }
  }
}' | jq '.data.__type.fields[] | {name, type: .type.name // .type.ofType.name}'

针对通用端点：

# Full introspection query via curl
curl -s -X POST https://api.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query":"{ __schema { types { name kind fields { name } } } }"}' \
  | jq '.data.__schema.types[] | select(.kind == "OBJECT") | {name, fields: [.fields[].name]}'

预期结果： JSON 输出列出可用类型、字段或变更。Schema 响应确认端点可达且认证令牌有效。

失败处理：

• 401 Unauthorized — 验证令牌；GitHub 请运行 gh auth status
• Cannot query field — 端点可能禁用内省；改查其文档
• 连接被拒绝 — 验证端点 URL 和网络访问

第 2 步：确定操作类型

确定任务需要查询（读取）、变更（写入）还是订阅（流）。

意图	操作	示例
获取数据	query	获取仓库详情、列出 discussions
创建/更新/删除	mutation	创建 discussion、添加评论
实时更新	subscription	监听新 issue（CLI 中少见）

针对 GitHub 特定操作，查阅 GitHub GraphQL API 文档。

# Quick check: does the mutation exist?
gh api graphql -f query='{ __schema { mutationType { fields { name } } } }' \
  | jq '.data.__schema.mutationType.fields[].name' | grep -i "discussion"

预期结果： 明确识别需要查询还是变更，以及确切的操作名称（如 createDiscussion、repository）。

失败处理：

• 找不到操作 — 用更广泛的词语搜索或检查 API 版本
• 不确定是查询还是变更 — 如果操作改变状态，则为变更

第 3 步：构造操作

用字段、参数和变量构建 GraphQL 查询或变更。

查询示例——获取仓库的 discussion 分类：

gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      discussionCategories(first: 10) {
        nodes { id name }
      }
    }
  }
' -f owner="OWNER" -f repo="REPO" | jq '.data.repository.discussionCategories.nodes'

变更示例——创建 GitHub Discussion：

gh api graphql -f query='
  mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
    createDiscussion(input: {
      repositoryId: $repoId,
      categoryId: $categoryId,
      title: $title,
      body: $body
    }) {
      discussion { url number }
    }
  }
' -f repoId="$REPO_ID" -f categoryId="$CAT_ID" \
  -f title="My Discussion" -f body="Discussion body here"

关键构造规则：

1. 始终使用变量（$var: Type!）而非内联值，以提高复用性
2. 只请求所需字段以最小化响应体积
3. 对分页连接使用带 nodes 的 first: N
4. 在每个对象选择中添加 id——链接时需要用到

预期结果： 语法正确的 GraphQL 操作，包含适当的变量、字段选择和分页参数。

失败处理：

• 语法错误 — 检查括号匹配和尾随逗号（GraphQL 不允许尾随逗号）
• 类型不匹配 — 根据 Schema 验证变量类型（如 ID! vs String!）
• 缺少必填字段 — 根据 Schema 添加必需的输入字段

第 4 步：通过 CLI 执行

运行操作并捕获响应。

GitHub——使用 gh api graphql：

# Simple query
gh api graphql -f query='{ viewer { login } }'

# With variables
gh api graphql \
  -f query='query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) { id name }
  }' \
  -f owner="octocat" -f repo="Hello-World"

# With jq post-processing
REPO_ID=$(gh api graphql \
  -f query='query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) { id }
  }' \
  -f owner="OWNER" -f repo="REPO" \
  --jq '.data.repository.id')

通用端点——使用 curl：

curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "$(jq -n \
    --arg query 'query { users { id name } }' \
    '{query: $query}'
  )"

预期结果： JSON 响应包含带请求字段的 data 键，或操作失败时包含 errors 数组。

失败处理：

• 响应中有 errors 数组 — 阅读消息；常见原因是权限不足、ID 无效或触发速率限制
• data 为空 — 查询未匹配任何记录；验证输入值
• HTTP 403 — 令牌缺少所需权限范围；GitHub 请检查 gh auth status 并用 gh auth refresh -s scope 添加权限

第 5 步：解析响应

从 JSON 响应中提取所需数据。

# Extract a single value
gh api graphql -f query='{ viewer { login } }' --jq '.data.viewer.login'

# Extract from a list
gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      issues(first: 5, states: OPEN) {
        nodes { number title }
      }
    }
  }
' -f owner="OWNER" -f repo="REPO" \
  --jq '.data.repository.issues.nodes[] | "\(.number): \(.title)"'

# Assign to a variable for later use
CATEGORY_ID=$(gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      discussionCategories(first: 20) {
        nodes { id name }
      }
    }
  }
' -f owner="OWNER" -f repo="REPO" \
  --jq '.data.repository.discussionCategories.nodes[] | select(.name == "Show and Tell") | .id')

预期结果： 提取出干净的值，可直接显示或赋值给 Shell 变量。

失败处理：

• jq 返回 null — 字段路径错误；先将原始 JSON 传给 jq . 检查结构
• 期望单个值但返回多个 — 添加 select() 过滤器或 | first
• Unicode 问题 — 为 jq 添加 -r 以获取原始字符串输出

第 6 步：链接操作

将一个操作的输出用作下一个操作的输入。

# Step A: Get the repository ID
REPO_ID=$(gh api graphql \
  -f query='query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) { id }
  }' \
  -f owner="$OWNER" -f repo="$REPO" \
  --jq '.data.repository.id')

# Step B: Get the discussion category ID
CAT_ID=$(gh api graphql \
  -f query='query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      discussionCategories(first: 20) {
        nodes { id name }
      }
    }
  }' \
  -f owner="$OWNER" -f repo="$REPO" \
  --jq '.data.repository.discussionCategories.nodes[]
    | select(.name == "Show and Tell") | .id')

# Step C: Create the discussion using both IDs
RESULT=$(gh api graphql \
  -f query='mutation($repoId: ID!, $catId: ID!, $title: String!, $body: String!) {
    createDiscussion(input: {
      repositoryId: $repoId,
      categoryId: $catId,
      title: $title,
      body: $body
    }) {
      discussion { url number }
    }
  }' \
  -f repoId="$REPO_ID" -f catId="$CAT_ID" \
  -f title="$TITLE" -f body="$BODY" \
  --jq '.data.createDiscussion.discussion')

echo "Created: $(echo "$RESULT" | jq -r '.url')"

模式： 始终在早期查询中提取 id 字段，以便将其作为 ID! 变量传递给后续变更。

预期结果： 多步骤工作流中每个调用都成功，ID 在操作之间正确传递。

失败处理：

• 变量为空 — 前一步静默失败；添加 set -e 并检查每个中间值
• ID 格式错误 — GitHub 节点 ID 是不透明字符串（如 R_kgDO...）；永远不要手动构造它们
• 触发速率限制 — 在调用之间添加 sleep 1，或使用别名批量查询

验证清单

1. 内省查询返回 Schema 数据（第 1 步成功）
2. 构造的查询语法正确（无 GraphQL 解析器错误）
3. 响应包含 data 键且无 errors
4. 提取的值类型正确（ID 为非空字符串，计数为数字）
5. 链接操作端到端完成（变更使用前序查询中的 ID）

常见问题

问题	预防措施
忘记在必需变量类型上加 !	始终检查 Schema 中的可为空性；大多数输入字段是非空的（!）
在 GraphQL 中使用 REST ID	GraphQL 使用不透明节点 ID；通过 GraphQL 获取，而非 REST
不分页大结果集	使用带 pageInfo { hasNextPage endCursor } 的 first/after
硬编码 ID 而不查询	ID 在不同环境中不同；始终动态查询
忽略 errors 数组	即使 data 存在也要检查错误——部分错误是可能的
Shell 中嵌套 JSON 的引号问题	使用 gh 的 --jq 标志或单独通过 jq 管道处理

相关技能

• scaffold-nextjs-app — 构建消费 GraphQL API 的 Web 应用
• create-pull-request — GitHub 工作流自动化（REST 对应方案）
• manage-git-branches — 通常与 API 自动化配合使用的 Git 操作
• serialize-data-formats — 响应处理中使用的 JSON 解析模式