GraphQL Formatter

GraphQL Input

Formatted GraphQL

query GetUser($id: ID!) {
  user(id:$id) {
    name email posts {
      title content comments {
        body author {
          name
        }
      }
    }
  }
}

技术详情

GraphQL 格式化器的工作原理

工具功能

GraphQL 格式化器可美化或压缩 GraphQL 查询（Query）、变更（Mutation）和订阅（Subscription）语句。工具解析 GraphQL 语法树，按标准的缩进规则重新排版输出——花括号内的字段缩进 2 或 4 空格、逗号和括号的间距统一化、嵌套查询层级分明。压缩模式则将 GraphQL 语句压缩为单行，去除所有不必要的空格和注释，适合在 HTTP 请求体中传输。工具也支持 Schema 定义语言（SDL）的格式化。

常见开发者使用场景

GraphQL 格式化器在前端和后端开发中都有用途。前端开发者从浏览器 DevTools 的网络面板复制 GraphQL 请求时，Payload 往往是压缩的单行格式——格式化后可以读懂查询结构。后端开发者在日志中查看 GraphQL 查询时，格式化后更容易定位性能问题（如 N+1 查询的嵌套字段）。在编写 API 文档或分享 GraphQL 查询示例时，格式化的代码更专业可读。学习 GraphQL 的新手用它理解复杂的嵌套查询语法。

与 SQL 格式化器配合可以同时格式化前后端查询语句，或使用 JSON 格式化器处理 GraphQL 的响应数据。

GraphQL 查询语法结构

格式化器处理的核心语法元素：

操作类型：query（查询）、mutation（变更）、subscription（订阅），可含操作名称
字段选择集：用花括号包裹的嵌套字段列表，支持多层嵌套
参数：字段后括号中的键值对参数（如 id: "123"），需处理各种类型值（字符串、整数、枚举、变量）
指令：@include、@skip、@deprecated 等指令的正确缩进
片段：fragment ... on Type 的片段定义和 ...FragmentName 的展开语法

常见陷阱与注意事项

变量定义：查询开头的变量定义（$variable: Type!）需要特殊处理，不要被误认为参数。
注释保留：压缩模式会删除注释，# 号后的注释在格式化时默认保留，但需确认工具行为。
内联片段：... on SomeType 的格式特殊处理，确保缩进正确反映其层级关系。
字符串内容：格式化器不应修改字符串字面量的内容，包括字符串内的空格、换行和特殊字符。

何时使用此工具而非代码

在调试 GraphQL 查询、编写 API 文档示例、或快速格式化从网络日志中提取的查询时使用此工具。对于编辑器中的持续格式化需求，推荐使用 Prettier 的 GraphQL 插件或 GraphQL VSCode 扩展，它们提供保存时自动格式化和语法高亮功能。