用本地 schema 检查 GraphQL 文档

准备实际 SDL 或 introspection 快照，校验所有操作，并交付完整原件与全部诊断。

更新于 2026-10-09约 4 分钟阅读

准备两个不同的输入

把完整 query、mutation 或 subscription 文档放入第一个文本框。来自 React gql 标签时，只复制其中的 GraphQL 文本；JavaScript 源码和 HTTP query 请求包不属于此输入格式。

Schema 文档选择 SDL；下载的 __schema 对象或 data.__schema 响应选择 introspection JSON。快照应对应打算使用的 API 版本；本工具不会请求 endpoint 获取它。

选择 schema 文件时保留操作文档：文件只替代第二个输入。
.json 后缀不会替代明确选择的解析格式。
如果 endpoint 返回 errors，先获得实际完整 schema，再检查文档语义。

按顺序理解结果

先看 schemaValid。为 false 时，documentValid 是 null，表示所给 schema 无法支持文档语义检查。语法、schema 类型或 introspection 结构问题仍会交付完整诊断报告。

SchemaValid 为 true 后，documentValid 表示整份文档是否通过标准规则。多个命名 operation 一起检查；选择 operationName 不会隐藏看起来未使用的错误定义。逐条查看 fragment 问题及其他诊断。

列按 UTF-16 单元计数，emoji 占两个列单位，CRLF 只推进一行。Introspection 的默认值是另一个解码后的 GraphQL 字面量，其错误可能没有原 JSON 坐标；报告不会编造位置。

完整文档示例

Schema：type Query{x:Int}
文档：query A{x} query B{missing}
结果：schemaValid=true，documentValid=false；B 中字段不存在

交付完整且有界的证据

下载 schema-original.graphql（或 schema-original.json）、document-original.graphql 及 validation-report.json。核对两份源 SHA256、实际计数与明确的 schema 格式。屏幕只预览前 4,000 个码点，报告复制仍然完整。

容量、编码、超时或取消拒绝都没有报告。修正或缩小输入后重跑，每次使用新的 Worker；10 秒期限包含启动，不会被同步校验循环延长。

最后在目标 API 环境，用真实变量值和授权运行操作。静态检查不会调用自定义标量转换、resolver 或服务器扩展，也不验证最终响应。

交付文件
原件或报告	用途
Schema 原件	实际生效的本地 schema 完整字节及身份
文档原件	完整操作文档，所有定义一起检查
校验报告	全部诊断、源哈希、阶段及实际工作量计数

参考资料

下载 schema 后校验 mutation 的原始问题
作者已经持有 introspection JSON 并希望静态检查；浏览器偏好与需求规模未知。
GraphQL.js 官方参考实现
固定 GraphQL.js 17.0.2 的语法与标准规则，不执行 operation。

本分类工具使用说明

展开工具，查看操作步骤、可调选项和支持范围，再直接进入工作区。

GraphQL 文档校验用本地 SDL 或 introspection JSON 校验完整 GraphQL 文档，下载全部静态诊断和字节不变的原件。

使用已有 schema 检查所有 operation 和 fragment，查看源位置，并把两份原件与完整校验报告一起保存。

操作步骤

把完整 GraphQL 操作文档粘贴到第一个文本框。
选择 schema 格式，粘贴本地 SDL、introspection JSON，或选择一个 schema 文件。
运行静态校验，查看 schemaValid、documentValid 及每条诊断的位置。
下载两份完整原件和 validation-report.json，再到目标 API 环境验证实际执行。

可调选项

本地 schema 格式: GraphQL SDL · Introspection JSON
明确选择解析格式；选中文件只替代 schema 文本。

能力与限制

粘贴完整操作文档，UTF-8 最多 1 MiB；粘贴 schema 最多 2 MiB。也可选择一个最多 2 MiB 的 schema 文件：只替代第二个 schema 文本框，保留第一个操作文档。明确选择 SDL 或 introspection 格式。原始文件名标签最多 512 个 UTF-8 字节。
使用 GraphQL.js 17.0.2 的标准静态规则，一起检查全部 operation 和 fragment；不按 operationName 筛选，不提取 React/JavaScript，不请求 endpoint，不运行自定义规则、resolver 或 scalar 强制转换。通过静态校验不代表查询能够执行或响应数据有效。
Schema 语法、结构或类型错误以及文档语法、语义错误都交付完整诊断报告。Schema 出错时 documentValid 为 null。行和列从 1 开始，列按 UTF-16 单元计数，CRLF 算一个换行；缺少原件坐标的 introspection 结构错误不编造位置。
文件必须可严格解码为 UTF-8，Unicode 必须成对。接受一个开头 BOM，原始字节与 SHA256 保留它。Introspection 必须是严格 JSON；解码后的重复键、同时出现 __schema 和 data.__schema、或包含 errors 成员会产生 schema 诊断。转义后出现孤立代理字符则原子拒绝。
Introspection 元数据数字必须是有限 IEEE 754 值，整数值必须在 ±9,007,199,254,740,991 以内。类型、字段、参数、枚举值及 directive 数组中的同名条目不会被覆盖。额外 envelope 元数据不参与语义校验，报告列出其键名，原件保持不变。
SDL 最多 100,000 个语法 token 和 100,000 个 AST 节点；操作文档各最多 50,000 个。花括号、中括号和圆括号嵌套最多 64 层，无环 fragment 引用链最多 64 个定义。Token 不包括注释、逗号和空白；AST 包括 Document 与 Name 节点，不计算位置链接。
Introspection JSON 最多 128 层容器和 100,000 个树节点，包括属性节点和键节点。可达非 __ 命名类型最多 2,000 个，包括构建器加入的标量。嵌入的 defaultValue 按 GraphQL const 语法解析，累计共用 schema token/AST 上限与 64 层嵌套上限。
最多交付 1,000 条完整诊断，完整报告 UTF-8 最多 1 MiB。多出一条诊断或一个字节都会拒绝，不发布截断报告；两份独立原件合计最多 3 MiB。独立 Worker 自动期限为 10 秒；取消、超时、容量或编码拒绝都没有部分产物。
屏幕最多预览报告的 4,000 个 Unicode 码点，复制和下载保留完整报告。GraphQL Float 字面量 1e400 和任意自定义 scalar 字面量可能通过标准静态规则；本工具不做运行时数字或自定义标量强制转换。输入只在本浏览器处理。

打开GraphQL 文档校验 →