要点
- 01使用官方 graphql.js 解析器格式化查询、mutations、subscriptions 和 SDL 架构。
- 02验证语法并报告错误的精确行和列 — 无需架构。
- 03GraphQL 注释 (#) 在格式化时被删除；为想要保留的文档使用描述字符串。
- 04完全在浏览器中运行 — 内部 API 查询和专有架构保持私密。
为什么格式化 GraphQL 文档?
GraphQL 查询可以快速变得复杂 — 嵌套片段、内联变量、多个操作定义和具有接口和指令的 SDL 类型定义。一致的格式化使同行审查更快，更容易一眼看出缺少的结束大括号或参数不匹配。
格式化工具使用引用 graphql.js 解析器 — GraphQL 规范所附带的解析器。这意味着你在此处获得的规范格式化与 Prettier 的 GraphQL 插件和大多数 GraphQL 工具生成的匹配。在此处干净解析的任何内容将在 Apollo、Relay 和 graphql-request 中干净解析。
如何格式化 GraphQL 文档
- 01
粘贴你的 GraphQL
将查询、mutation、subscription、fragment 或 SDL 架构定义粘贴到输入面板中。
- 02
单击格式化
解析器使用规范缩进发出文档 — 两空格缩进、每行一个字段、一致的参数对齐。结果出现在输出面板中。
- 03
可选验证
单击验证以确认文档解析而不生成格式化的输出。结果是确认或带有行和列号的语法错误列表。
- 04
复制结果
单击复制获取格式化的文档。粘贴到你的代码库、PR 描述或文档文件。
对内部架构和 API 查询安全
graphql.js 解析器完全在浏览器中运行。没有操作文本或架构定义发送到任何服务器。这使其可以安全地格式化引用私有字段名称或不想暴露给第三方工具的内部类型系统的查询。
此处的验证仅是语法 — 该工具检查文档是有效的 GraphQL 文档，但不检查字段名称是否在真实架构中存在、变量是否与参数类型匹配或指令是否正确应用。架构感知验证需要目标架构与文档一起加载。
GraphQL 格式化工具常见问题
GraphQL 格式化是否根据架构验证?
不会 — 仅语法验证。检查字段和参数是否存在需要目标架构。此工具确认文档是有效的 GraphQL 文档，仅此而已。
我的 GraphQL 中的注释会被保留吗?
不会。以 # 开头的行被解析器删除。为应该在格式化中存活的文档使用三引号描述字符串。
支持哪个 GraphQL 规范版本?
2021 年 10 月规范，包括 OneOf 输入对象和 @specifiedBy 指令。
我可以格式化 SDL 架构定义，而不仅仅是操作文档吗?
是的。类型定义、接口声明、联合类型、enums、指令和描述都通过格式化工具正确往返。
查询或架构上传到任何地方吗?
不会。graphql.js 解析器完全在浏览器中运行 — 没有东西离开你的设备。