GraphQL Client 查询调试与 Schema 探索工具手册

GraphQL Client 查询调试参考图以 GraphiQL、Altair、query、mutation、variables、headers、introspection 和查询成本形成 GraphQL 调试闭环。高清原图

HTTP 200 之后，故障才刚露出形状

订单页空白，浏览器却显示 GraphQL 请求返回 200 OK。把响应展开后才看到：

{
  "data": {
    "order": null
  },
  "errors": [
    {
      "message": "forbidden",
      "path": ["order", "payment"],
      "extensions": {
        "code": "FORBIDDEN",
        "requestId": "trace-demo"
      }
    }
  ]
}

这不是“接口成功但前端没渲染”，而是一次带部分数据的 GraphQL 响应。GraphQL 在一个 endpoint 上承载多个具名 operation；服务端先解析文档、按 schema 验证 operation 与 variables，再执行字段 resolver。请求错误可能在执行前终止，字段错误则可能让其他字段继续返回。因此客户端必须同时检查 HTTP 状态、data、errors、errors[].path 和实现自定义的 extensions，不能把 200 当成业务成功。

GraphiQL 与 Altair 都能把 query、mutation、variables、headers、schema 文档和结果放在同一调试现场。GraphiQL 适合由服务嵌入受控开发入口，能与应用认证和部署策略一起管理；Altair 适合跨多个 API 和环境的个人探索，提供桌面应用、浏览器扩展、Web 应用、collection 与环境变量。固定回归仍应落到脚本或测试框架，不能依赖某位开发者的 GUI 历史。

示例采用 GraphiQL 5.2.4 与 Altair 8.5.3 的能力口径。嵌入式 GraphiQL 应由锁文件固定版本；Altair 在 Help/About 或包管理器中确认实际安装版本，再从 GraphiQL Releases 与 Altair Releases 检查升级说明。客户端版本不会改变服务端 schema，但会影响 fetcher、存储、插件、订阅和导入导出行为。

选择一个不会扩大数据边界的入口

GraphiQL 跟随服务部署

GraphiQL 是可嵌入 React 应用的浏览器 IDE。项目安装需要 graphiql 及其 React、GraphQL peer dependencies：

npm install --save-exact \
  graphiql@5.2.4 @graphiql/toolkit@0.12.1 \
  react react-dom graphql

最小嵌入需要一个 fetcher：

import { createGraphiQLFetcher } from '@graphiql/toolkit';
import { GraphiQL } from 'graphiql';
import { createRoot } from 'react-dom/client';
import 'graphiql/style.css';

const fetcher = createGraphiQLFetcher({ url: '/graphql' });

createRoot(document.getElementById('root')!).render(
  <GraphiQL fetcher={fetcher} />,
);

真正的启用条件应放在服务路由或网关，不靠隐藏菜单：只有开发环境或经身份代理授权的运维角色能访问 IDE；endpoint 仍执行正常认证、授权、深度/复杂度限制与审计。GraphiQL 会持久化编辑状态，官方也提供自定义 storage 隔离同源多个实例的方式。共享浏览器、生产域名和高权限 token 组合在一起时，localStorage 与历史记录会成为敏感数据落点。

Altair 适合跨环境探索

Altair 官方提供 macOS、Windows、Linux 桌面应用，Chrome/Firefox 扩展和 Web 应用。macOS 可安装：

brew install --cask altair-graphql-client

Linux 可使用 Snap：

snap install altair

一次性公开 API 探索可以打开 Altair Web，但官方文档不建议把 Web 版作为完整开发入口；浏览器同源、CORS、Cookie 和响应头可见性会限制诊断。涉及内网 endpoint、客户端证书或敏感响应时，优先桌面应用，并确认组织的软件准入、自动更新和本地数据保留策略。

安装后的最低证据不是“窗口能打开”，而是能向授权测试 endpoint 发出 query Probe { __typename }，在结果区看到顶层 data，并在响应头或 extensions 中关联 request id。没有测试 endpoint 时，可先离线导入受控 schema 验证补全与文档，不要拿生产写权限账号做安装验收。

一次请求中真正变化的字段

GraphQL over HTTP 常见请求体包含三个关键字段：

{
  "query": "query OrderSummary($id: ID!) { order(id: $id) { id status } }",
  "operationName": "OrderSummary",
  "variables": {
    "id": "demo-order"
  }
}

query 保存完整 GraphQL 文档；operationName 在文档含多个 operation 时指定执行哪一个；variables 是独立 JSON 值，服务端按 schema 声明做类型强制转换。把真实 ID 拼进 query 会让历史、日志和缓存难以脱敏，也破坏请求模板复用。变量声明 $id: ID! 中的 ! 表示非空，传 null、漏传或传入不兼容结构都会在 resolver 执行前失败。

客户端界面通常分为四块：endpoint、operation 编辑器、variables 编辑器、headers/authorization 和响应区。先让这些字段保持显式，不要一开始依赖全局环境继承；否则错误可能来自看不见的 header 或旧 variables。

用正反实验区分验证失败与执行失败

正向实验先执行无副作用 query：

query OrderSummary($id: ID!) {
  order(id: $id) {
    id
    status
  }
}

variables：

{
  "id": "demo-order"
}

headers：

{
  "Authorization": "Bearer <access-token>",
  "X-Tenant-Id": "demo-tenant",
  "X-Request-Id": "trace-demo"
}

预期证据是响应含 data.order.id 与 data.order.status，errors 不存在或为空，并能用 trace-demo 关联服务日志。业务对象不存在时，schema 可能合法地返回 order: null；是否算失败取决于字段可空性与业务约定，不能凭空假定固定响应。

第一组反向实验把变量改为错误结构：

{
  "id": {
    "value": "demo-order"
  }
}

预期得到变量强制转换或验证错误，通常没有 data，对应 resolver 不应执行。第二组反向实验恢复变量、移除 Authorization，预期进入认证层并得到 HTTP 401/403 或 GraphQL errors，具体取决于服务传输约定。两组错误的阶段不同：前者证明文档已到达 GraphQL 验证器，后者证明 endpoint 可达但身份不足。

再做一个字段级反例：请求有权字段与无权字段并存。

query OrderEvidence($id: ID!) {
  order(id: $id) {
    id
    status
    payment {
      cardLastFour
    }
  }
}

若服务采用字段级授权，可能出现 data.order.id 成功、data.order.payment 为 null，同时 errors[0].path 指向 order.payment。这就是部分响应。问题单应保留 operation 名、脱敏 variables、错误 path、extensions.code、request id 和客户端版本，不能只写“接口 200”。GraphQL 响应规范说明可用于区分请求错误、字段错误和网络错误。

Schema 探索依赖 introspection，但安全不止一个开关

introspection 允许客户端查询 schema 自身。GraphiQL 和 Altair 用它生成文档、补全和本地验证。最小查询可以确认根类型：

query SchemaProbe {
  __schema {
    queryType { name }
    mutationType { name }
  }
}

更常见的是让 IDE 自动发送完整 introspection query。启用后，客户端得到类型、字段、参数、枚举、指令和弃用信息；它不会自动获得底层数据库结构或绕过字段授权，但会降低攻击者枚举 API 的成本。关闭 introspection 也不会修复缺失的认证、字段授权、查询限额或错误信息泄漏。

受控开发环境可以在认证后开放 introspection。生产策略可按威胁模型选择：认证后开放、对特定角色开放、完全关闭并向开发者发放版本化 schema artifact。若 IDE 报 Cannot query field "__schema" 或补全消失，先确认是服务策略还是 endpoint/header 配错；不要反复尝试绕过策略。

需要离线文档和 CI 校验时，把 schema 作为构建制品导出并绑定服务版本。schema artifact 可能包含内部类型、弃用说明和未来字段，同样需要访问控制。每次发布比较 breaking change，例如字段删除、参数从可空变非空、枚举值变化；客户端 UI 的绿色补全不能替代 schema diff 与契约测试。

离线 artifact 还应真正参与 operation 校验。下面的脚本使用项目已经安装的 graphql 包，把 SDL schema 与具名 operation 交给规范校验器，而不是只确认两个文件都存在：

// scripts/graphql-smoke/validate-operation.mjs
import { readFileSync } from 'node:fs';
import { buildSchema, parse, validate } from 'graphql';

const schema = buildSchema(
  readFileSync('docs/graphql/schema/service.graphql', 'utf8'),
);
const operation = parse(
  readFileSync('docs/graphql/operations/order-summary.graphql', 'utf8'),
);
const errors = validate(schema, operation);

if (errors.length > 0) {
  for (const error of errors) {
    console.error(error.message);
  }
  process.exitCode = 1;
}

node scripts/graphql-smoke/validate-operation.mjs

正向样例应退出 0。再把 operation 中的 status 临时改成 schema 不存在的 statusMissing，预期输出 Cannot query field 并以非零退出；恢复字段后重跑。该验证能发现字段、参数、变量类型和 selection set 与 schema 不一致，却不会执行 resolver，也不能证明认证、字段授权、复杂度或业务结果正确，这些仍要由请求级反例和服务端策略验证。

Header 继承是效率功能，也是事故放大器

Altair 支持请求级 header、collection header、选中环境和全局环境。官方文档给出的环境优先级是全局环境、选中环境、collection 环境，后者覆盖前者；全局环境中的 headers 会应用到所有窗口。这个模型很方便，也容易让测试 token 被无意发送给另一个 endpoint。

推荐把 endpoint 与非敏感环境标识放入环境变量：

{
  "apiUrl": "https://api.example.test/graphql",
  "tenant": "demo-tenant"
}

窗口中使用 {{apiUrl}} 和 {{tenant}}。真实 token 由短期身份流程获取，放在本地受控环境或操作系统密钥存储，不进入导出的 collection。发送前展开最终请求，确认实际 URL、Authorization、Cookie、租户和 CSRF header；切换环境后先执行只读 probe。

collection 可以保存和导入 query，collection header 会自动应用到其中所有窗口。导出前清理 request headers、collection headers、环境、pre-request/post-request scripts、variables、历史响应与内部 endpoint。脚本能读取 query、variables、headers 和 environment，也可能发起额外网络请求，因此导入 collection 相当于导入可执行配置，必须代码评审来源与脚本内容。

GraphiQL 的 fetcher 也会决定 Cookie 和 header 行为。使用浏览器会话认证时，要明确 credentials、CSRF 和同源策略；不要为了让 Web IDE 工作而把 CORS 改成任意来源。生产身份代理应在服务端验证用户，GraphiQL 页面隐藏与否不是授权边界。

Mutation 先证明目标，再允许写入

mutation 可能创建、更新、删除、发通知或触发下游工作流。名称看似温和并不代表可重放，例如 confirmOrder 可能扣库存并发送消息。调试前先确认环境、测试租户、目标对象和幂等语义，并使用最低写权限账号。

mutation RenameDemoOrder($input: RenameOrderInput!) {
  renameOrder(input: $input) {
    order {
      id
      name
    }
    userErrors {
      field
      message
    }
  }
}

{
  "input": {
    "id": "demo-order",
    "name": "verification-name"
  }
}

执行前先用 query 读取旧值并记录 request id；执行 mutation 后检查顶层 errors、payload 中的 userErrors 和新值；清理时用受支持的逆向 mutation 恢复旧值，再读一次确认。若操作不可逆，应创建一次性测试对象，完成后按服务提供的删除流程清理。客户端“重发”按钮、网络重试和多人重复点击都可能产生二次写入，服务没有幂等键时尤其危险。

生产环境可采取只读账号、禁用 IDE mutation、二次确认代理或独立变更入口。浏览器插件无法可靠理解每个自定义 mutation 的业务副作用，治理必须落在服务授权、审计和变更流程上。

查询形状决定容量与费用

GraphQL 让客户端选择字段，但并不保证“少一个 HTTP 请求就更便宜”。深层嵌套、宽字段、大分页、别名重复和 fragments 组合，可能触发大量 resolver、跨服务调用、N+1 查询和大响应。调试工具若反复执行高成本 query，本质上会变成无计划压测。

先从最小字段集和小分页开始：

query OrderPage($first: Int!, $after: String) {
  orders(first: $first, after: $after) {
    nodes { id status }
    pageInfo { hasNextPage endCursor }
  }
}

测试 variables 使用小 first，逐步增加字段并观察响应时间、响应字节数、extensions 中的 complexity/cost（若实现提供）、服务端 resolver 指标和下游调用数。正向证据是分页受控、成本随字段变化可解释；反向实验可在测试环境加入一个深层或重复字段，预期被 depth/complexity/timeout/rate-limit 策略拒绝，而不是拖垮后端。

客户端设置会改变风险：自动刷新 schema 增加 introspection 流量；历史与响应保留增加本地磁盘和敏感数据占用；并行窗口、自动重试与 subscription 增加连接数；collection 数量乘以环境数量会扩张维护成本。团队应观察按 operation name 聚合的调用量、错误率、P95/P99、响应大小、complexity、限流拒绝、resolver 扇出和无名 operation 比例。

从探索请求沉淀为项目资产

仓库保存具名 operation 与示例 variables：

docs/graphql/
  operations/
    order-summary.graphql
  variables/
    order-summary.example.json
  schema/
    service.graphql
scripts/graphql-smoke/
  check-order.sh

.graphql 文件应有稳定 operation name，example JSON 使用假数据，schema artifact 标注来源版本。Authorization、Cookie、真实订单号、手机号、邮箱、内部域名和响应快照不进入仓库。

CI smoke 可用 curl 发送固定 query，但必须解析 GraphQL body；curl --fail-with-body 只能处理 HTTP 失败，不能发现 200 + errors：

set -euo pipefail

: "${GRAPHQL_ENDPOINT:?missing GRAPHQL_ENDPOINT}"
: "${GRAPHQL_TOKEN:?missing GRAPHQL_TOKEN}"

curl_config="$(mktemp)"
chmod 600 "${curl_config}"
trap 'rm -f "${curl_config}"' EXIT
printf 'header = "Authorization: Bearer %s"\n' "${GRAPHQL_TOKEN}" >"${curl_config}"

response="$({
  jq -n \
    --rawfile query docs/graphql/operations/order-summary.graphql \
    --arg id "demo-order" \
    '{query: $query, operationName: "OrderSummary", variables: {id: $id}}'
} | curl --fail-with-body --silent --show-error \
  --config "${curl_config}" \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: ci-graphql-smoke' \
  --data-binary @- \
  "${GRAPHQL_ENDPOINT}")"

if jq -e '.errors != null and (.errors | length > 0)' <<<"${response}" >/dev/null; then
  jq '{errors: [.errors[] | {message, path, code: .extensions.code}]}' <<<"${response}" >&2
  exit 1
fi

jq -e '.data.order.id != null' <<<"${response}" >/dev/null

临时 curl 配置的权限为 0600，退出时由 trap 删除，token 不再出现在 curl 命令参数中；runner 仍须把环境变量限制在该任务并禁止调试日志回显。日志仅输出脱敏错误摘要，不打印完整 response 或 token。高风险 mutation 不进入通用 smoke；schema diff、operation 静态校验和业务契约测试分别承担兼容性与行为验证。

按错误阶段收集证据

现象	首先判断	有效证据与动作
DNS、TLS、CORS、超时	请求未完成	浏览器/桌面网络错误、证书链、代理日志；修复传输后再看 GraphQL
404/405	endpoint 或 HTTP method 错	最终 URL、网关路由、POST/GET 策略
401/403	身份或入口授权失败	header 键、账号角色、租户与 token 状态；不记录真实值
data 缺失且有 errors	解析、验证或变量强制转换失败	message、locations、operation、脱敏 variables
data 与 errors 并存	字段执行失败	errors[].path、null 冒泡位置、resolver/request id
补全和文档为空	introspection、schema 缓存或 endpoint 错	手动 SchemaProbe、刷新 schema、核对环境
GUI 成功而 CI 失败	隐式 header、Cookie 或环境变量	比较最终 HTTP 请求，不复制真实凭证
query 超时或限流	depth、complexity、分页或下游扇出	operation name、成本、响应大小、resolver 指标
mutation 重复生效	重试或幂等缺失	request id、幂等键、审计记录；停止重发并走恢复流程

错误排查要保持阶段顺序：传输层、HTTP 入口、解析/验证、认证授权、resolver 执行、下游依赖。先看到的 200、IDE 红线或 FORBIDDEN 都只是一个信号，必须用 response path 与服务端 request id 把它落到具体阶段。

清理、回滚与停用

一次调试结束后，先恢复 mutation 产生的测试数据，再撤销临时 token，清除客户端 request/collection/global headers，删除含真实值的 variables 与响应历史，关闭 subscription 窗口。GraphiQL 运行在共享或生产同源页面时，还要清理对应 storage namespace；Altair 导出文件若曾含凭证，应删除本地副本并按泄漏处理轮换凭证，不能只在导出文件里替换字符串。

工具升级出现 fetcher、插件、schema 刷新或存储回归时，恢复锁文件中的上一个版本，重新构建受控 IDE，并用固定 query、反向 query 和 schema artifact 验证。Altair 桌面升级可保留脱敏 collection 备份，但不要备份 token。停用某个客户端时，回收软件分发、浏览器扩展策略、相关 OAuth client/代理授权和团队文档入口。

团队长期维护的决策面

工具选型可以按责任分层。服务团队需要可嵌入、可认证、可随部署关闭的调试入口时选择 GraphiQL；开发者跨多个服务和环境探索、需要 collection、环境变量或桌面网络能力时选择 Altair；稳定 smoke 使用 curl 或专用 CLI；大型回归、schema 演进和客户端兼容性由契约测试与 schema registry/diff 工具承担。

权限上，默认给只读测试账号，mutation 权限单独申请并限时；凭证通过身份提供方或 secret manager 注入，不进入 collection、全局环境、截图和录屏。数据上，query 文本也可能暴露未发布字段与业务意图，variables 和 response 则可能直接含个人信息。审计至少能按用户、operation name、环境、request id、成本和结果状态追踪。

容量与成本治理不能停在“限制深度”。同时维护 max depth、complexity/cost、分页上限、超时、响应大小、并发、rate limit 和 persisted/allowlisted operation 策略，并用真实基线调整。关闭 introspection 可以减少枚举面，但不能代替这些保护。对 federation 或多个子图，还要区分公共组合 schema 与内部子图 schema 的访问权限和发布节奏。

团队推广前应演练四件事：无 introspection 时能用受控 schema artifact 调试；移除 Authorization 后能得到可解释的拒绝；高成本反例能被容量策略挡住；临时 mutation 能恢复且审计链完整。最终留下的是具名 operation、假数据 variables、schema 版本、脱敏错误证据与自动化检查，不是某个客户端里越来越难清理的个人状态。