Neatbo.

静态 GraphQL 校验需要对应的 schema 快照

理解本地 schema 校验能够证明什么、为什么多操作文档必须完整检查，以及如何用源证据审查 API 变更。

Neatbo 编辑部更新于 约 4 分钟阅读

快照也是结果的一部分

下载的 introspection 响应描述某个时点的 schema。文档即使通过昨天快照的校验，今天也可能面对不同的 schema。交付时一起保留快照，不要只转发通过状态。

SDL 与 introspection JSON 用不同的源格式描述本地契约。Introspection 还可能被包在包含 errors 或不完整类型引用的响应中；只有 schema 检查完成后，操作结果才有意义。

检查实际交付的完整文档

一份文档可能包含多个命名操作和共享 fragment。执行时选择某个操作，并不会让其他定义自动适合完整静态审查。重复名称、匿名操作规则和循环引用可能影响文档本身。

Neatbo 一起检查全部 operation 与 fragment，在固定完整报告上限内保留所有诊断，不提供能够隐藏错误定义的 operationName 筛选。

  • 确认 schema 快照来自哪个 API 环境，并把这份实际源文件与操作文档一同保留。
  • 一起检查全部 operation 与共享 fragment；先解决完整文档的诊断，再选择要执行的操作。
  • 下载完整报告和两份原件，交付时核对各自的字节长度与 SHA256。
  • 静态审查完成后，在目标 API 环境继续验证运行时变量和自定义 scalar 行为。

字面量语法无法代替运行时行为

自定义 scalar 的含义超出内建标量规则。没有应用自身的强制转换实现，静态校验只能确定何处需要它，无法验证业务语义。为填补这个缺口运行用户 resolver，会变成代码执行任务。

数字字面量能说明这种边界：固定的成熟校验器会静态接受 Float 位置的 1e400，而在 Int 位置提供过大数值会得到标准诊断。两种结果都不证明运行时输入可用或响应能够序列化。

静态证据与仍需完成的 API 验证
输入或检查项本地校验能够确定的内容目标 API 环境仍需验证的内容
完整操作文档针对所提供的有效 schema 检查语法和标准文档规则，包含全部 operation 与 fragment。携带实际变量及凭据执行目标操作。
本地 SDL 或 introspection schema检查报告所标明的这份实际快照的结构与 schema 规则。确认快照仍对应目标 API 及当前权限。
自定义 scalar确定 schema 在何处要求该 scalar；不运行应用自身的 scalar 强制转换。验证应用的 scalar 强制转换和业务规则。
运行时变量值检查文档中的变量声明及静态使用；工具不接收变量值载荷。在实际执行操作时验证并提供变量值。

完整拒绝能留下清楚的边界

一千条诊断可能是完整结果；出现第一千零一条时必须拒绝。如果把前一千条作为成功的完整报告，会隐藏检查已经停止。报告字节上限和自动 Worker 期限同样如此。

两份原件、字节长度及 SHA256 让结果可核对。哈希标明实际输入，不能证明快照仍是最新版本或授权操作。把这些明确的原件和完整报告带到目标 API 环境，完成其余执行检查。

参考资料

本分类工具使用说明

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

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

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

操作步骤

  1. 把完整 GraphQL 操作文档粘贴到第一个文本框。
  2. 选择 schema 格式，粘贴本地 SDL、introspection JSON，或选择一个 schema 文件。
  3. 运行静态校验，查看 schemaValid、documentValid 及每条诊断的位置。
  4. 下载两份完整原件和 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 文档校验 →