GraphQL Formatter 使用指南：输入、模式与结果解读

先了解工具当前能返回什么

GraphQL Formatter 面向 GraphQL 查询或模式文本提供格式化入口。不过，按当前已核实的行为，空白输入可以成功返回空结果，非空字符串的美化和压缩请求都会在返回格式化文本前失败。因此，使用它时应先确认你要观察的是空白输入结果，还是验证非空输入请求的处理边界；不要把结果当作 GraphQL 语法校验、解析或执行结论。

操作步骤与观察方法

1. 在输入区域填写 GraphQL 查询或模式文本。输入应为字符串；如果主输入为空，工具也支持通过兼容的旧名称提交值，但提交后的值仍需是字符串。
2. 如需测试空白分支，保持输入为空，或只输入空格、换行等空白字符。此时可以提交请求，并记录返回的空格式化文本、输入大小和输出大小。
3. 如需测试非空分支，输入一段实际的 GraphQL 文本，再选择美化或压缩。美化是默认路径；只有模式值为 minify 时才选择压缩，其他模式值会进入美化路径。
4. 观察请求是否返回格式化文本。当前行为下，普通非空字符串在通过类型和大小检查后，美化与压缩都会在结果处理阶段失败，因此不要根据失败结果判断原文是否是有效 GraphQL。
5. 如调整缩进，非空输入的默认值是每层 2 个空格；可转换为整数且处于 0 到 8 之间的值会被采用，其他值回到 2。空白输入不会执行这项规范化。

如何解读结果及其边界

空输入或仅含空白的输入会得到空格式化文本，输入大小和输出大小均为 0；返回的模式与缩进值保持提交时的形式，不经过模式小写、缩进转换或范围规范化。非空输入则不能在当前实现中得到成功的格式化文本，所以不应把“没有返回格式化结果”解释为格式化后的内容，也不能据此判断查询可执行、语法正确或模式有效。压缩路径的设计目标包括移除井号开头的注释样文本、合并空白，并处理大括号、圆括号、冒号和逗号周围的空格；但普通非空输入仍会在返回结果前失败，方括号周围空格也不属于该路径的处理范围。

使用示例

用户想确认工具如何处理只含空白字符的 GraphQL 输入。

在输入区域只输入三个空格，保留默认模式和默认缩进，然后提交请求。

提交后得到空格式化文本，输入大小和输出大小均为 0；模式与缩进值保持提交时的形式。

使用限制

• UTF-8 编码超过 1,000,000 字节的非空输入会失败；普通非空输入当前也不会返回成功的格式化文本，且压缩路径对方括号周围空格没有对应处理。

常见错误

• 如果提交的值不是字符串，请改为提交文本；主输入为假值时，先确认兼容名称提供的替代值是否为字符串，因为别名选择发生在类型检查之前。

常见问题

非空 GraphQL 查询能成功格式化吗？

可以提交，但当前行为下空白或仅含空白的输入才会成功返回空结果；普通非空文本会在返回格式化文本前失败。

返回结果能证明 GraphQL 语法正确吗？

不能。当前结果不能用来证明 GraphQL 已通过校验、解析或执行；非空请求也不会返回成功的格式化文本。

输入内容有大小限制吗？

可以提交超过该大小的文本，但 UTF-8 编码超过 1,000,000 字节的非空输入会在格式化前失败；应缩短文本后再试。