GraphQL 查询构建器

粘贴 GraphQL Schema(SDL)或内省查询的 JSON 结果,按 Query、Mutation 展开字段树,勾选需要的字段、填写参数,自动生成格式规范的查询语句和变量,以及 fetch、curl、Python 调用代码。支持嵌套对象、联合类型和输入类型参数。要直接向接口发送请求,请用 GraphQL 调试器。

编辑 Schema(当前为示例博客接口)

可以粘贴 schema.graphql 的内容,或者内省查询(introspection)返回的 JSON。

勾选对象类型的字段时会自动选上它的第一个普通字段;带 * 的参数为必填。

变量

怎么拿到接口的 Schema

  • 项目里的文件:很多项目会把 Schema 保存为 schema.graphql 或 schema.gql,直接复制内容粘贴即可。
  • 内省查询:接口开启了内省(introspection)时,在 GraphQL 调试器 中点“获取 Schema”,把返回的 JSON 粘贴到这里。生产环境出于安全考虑常常关闭内省。
  • 命令行导出:npx get-graphql-schema https://接口地址 > schema.graphql,或者使用 Apollo Rover:rover graph introspect https://接口地址。

写查询的几个好习惯

  • 参数用变量传:不要把值直接拼进查询字符串。用 $变量 的写法,查询文本保持不变,服务端可以缓存解析结果,也避免了注入和转义问题,本工具默认这样生成。
  • 只取需要的字段:GraphQL 的优势就是按需取数据,选太多嵌套字段会让一次请求查询大量数据,很多服务端会限制查询深度和复杂度。
  • 给操作起名字:有名字的操作(如 query GetUser)在服务端日志、监控和浏览器开发者工具中更容易定位。

GraphQL 查询构建器常见问题

GraphQL 查询构建器怎么使用?

展开“编辑 Schema”粘贴自己的 SDL 或内省 JSON(默认是示例博客接口),选择查询或变更,在字段树中勾选字段,勾选带参数的字段后填写参数值;右侧生成查询语句和变量,切换 fetch、curl、Python 代码,填写接口地址后复制。

GraphQL 查询为什么要用变量?

查询文本保持不变,便于服务端缓存,也避免了手动拼接字符串带来的转义和注入问题。

对象类型的字段为什么必须选子字段?

GraphQL 要求返回对象时明确列出需要的字段,本工具会自动选上第一个普通字段。

联合类型怎么查询?

使用 ... on 类型名 的片段分别选择各类型的字段,本工具在联合类型下会列出这些片段。

怎么获取接口的 Schema?

接口开启内省时可以在 GraphQL 调试器中获取,或者向接口提供方索取 schema.graphql 文件。

GraphQL 查询构建器的结果应怎样理解?

SDL 解析覆盖 type、interface、input、enum、union、scalar 和 schema 定义,不处理自定义指令的含义;接口类型的具体实现类型片段需要手动补充。

输入内容会保存或发给外部服务吗?

Schema 和生成的查询只在浏览器本地处理,不会发送任何请求。

没有结果或操作失败时先检查什么?

提示没有找到 Query 类型,检查 Schema 中是否定义了 type Query,或者 schema { query: ... } 指定的类型名是否存在。

相关工具

GraphQL 调试器 · cURL 命令生成器 · JSON Schema 生成器 · JSON Schema 生成表单 · 全部开发工具