Loading…

关于 在线 GraphQL 格式化工具

保持您的 GraphQL SDL 和操作可读且一致。此在线 GraphQL 格式化工具使用 Prettier 的 GraphQL 解析器重新缩进、换行和规范化您的文档。它尽可能在浏览器中运行，必要时回退到服务器格式化器，因此您无需考虑工具即可获得可靠输出。

此 GraphQL 格式化工具的功能

  • 使用 Prettier 的 GraphQL 解析器应用一致、社区标准的格式化
  • 支持查询、变更、订阅、片段和完整架构 SDL（类型、接口、联合、枚举、输入、指令）
  • 可调缩进：选择空格或制表符并配置缩进大小（1–8）
  • 通过可配置列宽进行可选的行长度/换行控制
  • 在规范化布局的同时保持描述（`"""…"""`）和内联注释不变
  • 在格式化过程中验证您的 GraphQL 文档结构；无效语法将显示错误，而非静默破坏代码
  • 混合执行：可用时在浏览器中运行 Prettier，必要时回退到服务器格式化器
  • 粘贴或上传 `.graphql` / `.gql` 文件，然后预览、复制或下载格式化结果

📝 如何在线格式化 GraphQL for graphql-formatter

1

粘贴或上传您的 GraphQL

将您的 GraphQL 模式或查询粘贴到编辑器中，或拖放 `.graphql` / `.gql` 文件。格式化器适用于 SDL 和操作文档。

2

调整格式化选项

选择空格或制表符，设置缩进大小，并配置您偏好的行长度。这些选项将传递给 Prettier 的 GraphQL 格式化器。

3

格式化、审查与导出

点击“格式化”应用更改。在预览窗格中审查结果，然后将其复制回您的编辑器或下载格式化后的文件。

技术规格

支持的输入

专为标准 GraphQL 模式和操作文档设计。

类型示例备注
模式 SDLschema.graphql, schema.gql类型、接口、联合、枚举、输入、指令、模式定义
操作queries.graphql, app.gql查询、变更、订阅和片段
扩展单独文件中的模式扩展例如：`extend type Query { … }` 块

格式化引擎

格式化使用 Prettier 的 GraphQL 支持执行。在大多数情况下，Prettier 通过轻量级运行时在浏览器中运行。如果当前环境中无法解析 GraphQL 插件，格式化器将透明地回退到服务器端 Prettier 工作器。

可用选项（映射到 Prettier）

选项行为典型值
缩进样式在空格和制表符之间选择空格（默认）或制表符
缩进大小每个缩进级别的空格数（使用空格时）1–8，默认：2
行长度用于换行/截断长选择的目标列0–120（0 ≈ 实际上不换行）

限制与性能

该工具针对典型的GraphQL模式和操作文件进行了优化。几百KB到约2MB的请求通常是安全的；极大的文档可能会遇到超时或大小限制。

隐私与安全

GraphQL文档在您的浏览器中或在encode64的格式化后端进行格式化。它们不会被执行或发送给第三方服务。对于敏感模式，您可以在本地使用Prettier镜像相同的配置。

命令行等效工具（Prettier）

如果您已安装Node.js和Prettier，可以在本地重现此行为。

Node.js（所有平台）

原地格式化GraphQL模式文件

npx prettier --write schema.graphql

Prettier会根据文件扩展名自动检测GraphQL。

使用自定义缩进和行长度格式化

npx prettier --write schema.graphql --tab-width 2 --use-tabs false --print-width 80

反映了在线工具中公开的缩进和换行选项。

从标准输入格式化（例如从另一个工具管道输入）

cat input.graphql | npx prettier --stdin-filepath input.graphql

在shell脚本、CI流水线或Git钩子中很有用。

常见GraphQL格式化器使用场景

API模式开发

  • 保持大型模式文件格式一致，便于导航
  • 减少模式PR中的无关空白差异
  • 为代码生成工具准备干净的SDL
# 之前
type User{ id:ID! name:String!}

# 之后
type User {
  id: ID!
  name: String!
}

前端操作与片段

  • 跨多个应用或包标准化共享查询
  • 在调试时使嵌套选择更易于浏览
  • 保持文档片段和playground示例格式美观

测试、夹具与工具

  • 标准化快照测试中使用的GraphQL夹具
  • 将格式化集成到预提交钩子或CI作业中
  • 将干净文档输入到模式验证或差异工具中

❓ Frequently Asked Questions

GraphQL格式化器实际改变了什么？

它根据Prettier的GraphQL规则重构您的GraphQL文档：缩进、换行、标点周围的间距以及选择和字段的布局。它不会重命名字段、添加参数或更改模式语义。

它是否同时支持操作和模式SDL？

是的。格式化器适用于标准GraphQL操作（查询、变更、订阅、片段）和模式定义语言（类型、接口、枚举、联合、输入、指令、模式定义和扩展）。

注释和描述字符串是否保留？

是的。三引号描述字符串（`"""…"""`）和内联`#`注释会被保留。格式化器可能会重新排列它们或调整周围的空白，但不会有意删除它们。

我的 GraphQL 代码会被执行吗？

不会。该工具将您的 GraphQL 作为文本来解析以重新格式化，但不会执行查询或连接到任何 GraphQL 服务器。

格式化在哪里运行：客户端还是服务器？

格式化器优先在您的浏览器中直接运行 Prettier 以确保响应性。如果所需的 GraphQL 插件无法在此加载，则会回退到服务器上具有相同选项的 Prettier 工作线程。

这是免费使用的吗？

是的。该工具免费，并设有合理使用保护以保持性能稳定。对于繁重或私密的工作负载，请在您自己的环境中使用 Prettier 镜像相同的配置。

Pro Tips

Best Practice

在添加代码检查或破坏性更改之前，使用此格式化器标准化遗留模式；这使后续的差异审查更加容易。

Best Practice

将您的在线工具设置（缩进大小和行长度）与项目的 Prettier 配置对齐，以保持本地和网页格式化一致。

Best Practice

将代码中嵌入的长 GraphQL 字符串提取到 `.graphql` 文件中，以便统一格式化和重用。

Best Practice

将格式化与代码检查（例如 GraphQL ESLint）结合使用，以捕获超出空白和换行的问题。

Additional Resources

GraphQL 规范
Documentation
Prettier – GraphQL 格式化
Documentation
GraphQL 官方文档 – 学习
Documentation
GraphQL ESLint（代码检查规则）
Documentation

Other Tools