GraphQL 格式化是指将 GraphQL 查询、变更和订阅等代码进行清晰、规范地排版，使其符合一致的风格和最佳实践。格式化 GraphQL 代码的目的是提高可读性、保持一致性并减少潜在的错误。
GraphQL 是一种用于 API 的查询语言，能够使客户端精确地请求所需要的数据，而不需要依赖传统的 REST API 中的冗长响应。良好的格式化不仅帮助开发人员更快地理解查询，还能在协作中保持代码的一致性。
为什么需要 GraphQL 格式化？
提高可读性：格式化后，GraphQL 查询结构更加清晰，开发者可以轻松理解查询请求的内容。
增强一致性：统一的格式能够避免代码风格的差异，提高团队协作的效率。
减少错误：格式化可以帮助开发人员识别潜在的语法错误或结构不合理的问题。
更好的维护性：格式化的代码更加规范，方便后期的维护和扩展。
GraphQL 格式化的关键规则
缩进和对齐：
使用一致的缩进（推荐使用 2 个空格或 4 个空格）。避免混用制表符和空格。
确保每个字段、参数等都对齐，特别是在多行时。
字段和参数的排版：
字段：如果一个查询包含多个字段，每个字段应位于单独的一行。
参数：当字段有多个参数时，建议将每个参数放在单独一行，并对齐它们。
嵌套结构：
在嵌套的查询中，每一层嵌套应该有适当的缩进，以显示层级结构。
大括号的使用：
查询和变更中，选择的字段应放在大括号内，且大括号应该与字段排成一行。
注释：
使用注释来解释复杂的查询，帮助团队成员理解某些字段的用途。
示例：GraphQL 查询格式化
非格式化的 GraphQL 查询示例：
graphql
query {users{id,name,email,posts{id,title}}}
格式化后的 GraphQL 查询示例：
graphql
query {
users {
id
name
email
posts {
id
title
}
}
}
格式化工具和方法
1. Prettier：
Prettier 是一个流行的代码格式化工具，它支持多种语言，包括 GraphQL。使用 Prettier 可以自动格式化 GraphQL 查询、变更和订阅。
安装 Prettier 和 GraphQL 插件：
bash
npm install --save-dev prettier prettier-plugin-graphql
配置 Prettier：在项目根目录创建 .prettierrc 文件，并添加 GraphQL 格式化规则：
json
{
"singleQuote": true,
"semi": true,
"trailingComma": "es5",
"tabWidth": 2
}
运行 Prettier 格式化 GraphQL 文件：
bash
npx prettier --write "**/*.graphql"
2. GraphQL Playground：
GraphQL Playground 是一个交互式的 GraphQL IDE，它提供了格式化 GraphQL 查询的功能。在编写查询时，可以直接使用 Playground 的 "Format" 按钮来格式化查询。
3. Apollo Server：
Apollo Server 提供了一个 GraphQL 查询解析工具，能够自动格式化查询和变更。通过 Apollo 的工具链，可以轻松格式化请求和响应。
4. VSCode 插件：
Prettier - Code Formatter：VSCode 的 Prettier 插件支持 GraphQL 格式化，能够自动格式化 GraphQL 查询文件。
GraphQL for VSCode：专门为 GraphQL 提供的插件，支持语法高亮、自动完成和格式化功能。
5. GraphQL Formatter：
GraphQL Formatter 是一个用于格式化 GraphQL 查询的命令行工具。你可以使用它来格式化 GraphQL 查询文件。
安装 GraphQL Formatter：
bash
npm install -g graphql-formatter
使用 GraphQL Formatter 格式化查询文件：
bash
graphql-formatter path/to/query.graphql
格式化的常见技巧
使用一致的缩进：
推荐使用 2 个空格进行缩进，但确保在整个项目中保持一致。
字段与嵌套结构：
每个查询字段或嵌套字段应该独占一行，嵌套字段应该根据其层级适当缩进。
参数的处理：
当字段有多个参数时，应该将每个参数放在单独的一行，且在多行参数的情况下，参数的冒号后应该有一个空格。
注释的使用：
使用注释来解释复杂的查询或变更。例如，描述某个字段的作用，或者解释某些参数的用途。
避免过长的查询：
尽量避免将所有字段放在同一行，尤其是字段很多时。过长的查询会使得代码变得难以阅读。
格式化小示例
非格式化的 GraphQL 查询：
graphql
query {search(query:"GraphQL",type:REPOSITORY,first:10){edges{node{id ... on Repository{name}}}}}
格式化后的 GraphQL 查询：
graphql
query {
search(query: "GraphQL", type: REPOSITORY, first: 10) {
edges {
node {
id
... on Repository {
name
}
}
}
}
}
小结
GraphQL 格式化不仅仅是为了美观，它在提高代码可读性、增强一致性、减少潜在错误以及提升代码维护性方面都有显著作用。通过使用 Prettier、VSCode 插件、Apollo Server 等工具，可以轻松格式化 GraphQL 查询、变更和订阅。