01
把当前版本放在旧版
风险是从旧版走向新版计算的。若不小心贴反，使用交换按钮会重新分析；删除一个字段与添加一个字段的结果完全不同，不能只看两份文件是否相似。
GraphQL 文档
GraphQL Schema 对比发布前看清接口变化
旧版放当前已发布的完整 SDL，新版放拟发布的完整 SDL；左右方向决定移除与新增的风险解释。
GraphQL Schema 对比
旧版 Schema SDL
新版 Schema SDL
差异结果
请输入两份完整的 Schema SDL，或加载示例。
两份 SDL 只在当前浏览器内解析；不请求 API、不上传、不保存历史，也不把输入写入网址。
选项
破坏性与潜在危险由 GraphQL.js 判定；其他结构变化和弃用另列，不等于已经证明安全。
每份 SDL 最多 100,000 字符、20,000 个词法单元、100 层嵌套；对比最多运行 8 秒。
请输入两份完整的 Schema SDL，或加载示例。
做接口评审时，GraphQL Schema 对比比逐行看文本更接近真正的问题：这次改动会不会让已有查询失效？定义顺序和缩进可能变化很多，客户端真正依赖的却是字段、类型和参数的契约。
这份报告把 Schema 差异对比和风险判定分开。GraphQL.js 有明确的破坏性变更检测规则，但规则未报出的新增字段、参数放宽和弃用标记仍会列出，供审查人判断运行时与迁移影响。
为什么用 GraphQL Schema 对比
忽略排版噪声，同时保留规则没有覆盖的变化。
沿路径找到真实差异
GraphQL Schema 对比先解析两份 SDL，再按类型、字段、参数、输入对象和枚举路径列出变化。调换定义顺序不会造成假阳性；旧版字段被删除时，报告会直接指出该字段，而不是只给一段行号。
风险与弃用分别审查
新增枚举值可能影响穷举分支，会落在潜在风险；给旧字段加 @deprecated 只是弃用标记，不等于字段已消失。GraphQL Schema 对比将两者分栏展示，也把普通新增留在其他结构变化里。
先认清方向，再导出最新报告
02
按输入规模选运行方式
默认在停止输入约 350 毫秒后自动对比。粘贴大段 SDL 时可关闭自动模式，待两侧都准备好后按“对比”或 Ctrl/Cmd+Enter，避免每次小改动都触发计算。
03
修复错误并确认报告未过期
旧版或新版出现语法、Schema 语义问题时，错误会指出侧别和可用的行列。任何输入修改都会禁用复制与下载；重新对比成功后，即使屏幕只展示前 100 项，导出仍包含全部变化。
从字段变化读到兼容风险
按 GraphQL 结构找路径
类型、字段、参数、输入对象、枚举、联合与指令参与结构对比；空白、缩进和定义顺序不会被误算为接口变化。 GraphQL 字段变更会精确落到所属类型与字段，不因文件行号变化而漂移。
保留官方规则分类
破坏性和潜在危险由 GraphQL.js 的规则返回，旁边展示规则代码。其他结构变化不自动贴“安全”标签，评审时仍要考虑具体客户端。
独立记录弃用与完整导出
@deprecated 的新增、移除或原因变更单独列出；即使旧字段已经弃用，真正删除时仍是破坏性变化。复制与下载拿到完整报告。
输入范围与风险结论的边界
- 必须是两份完整 SDL
- 这里只接收能建立有效 GraphQL Schema 的 SDL。缺少 Query 根类型、引用不存在的类型或写错语法时，不会产生“零差异”的误导报告；应先修正报错一侧。
- 静态风险不等于真实使用量
- GraphQL Schema 对比能指出可能使旧查询失效的结构，但不知道线上有哪些客户端、它们是否真的调用了该字段。潜在危险与其他结构变化也需要结合实际调用判断。
- 不抓远程端点或收 JSON 内省结果
- 本页不发送网络请求，不执行 Query 或 Mutation，也不把文件上传到服务端。输入是 SDL 文本；若手上只有 introspection JSON，请先转换为完整 SDL。
- 改名按删除加新增处理
- 两份快照无法证明某个旧字段就是某个新字段的改名。报告会保留删除的破坏性提示；给字段写过 @deprecated 也不会自动豁免真正的删除。
GraphQL Schema 对比常见问题
把 Mutation 参数改成可接受 null 会破坏兼容性吗？
把必填 Mutation 参数改成可空，通常扩大了可接受的输入，GraphQL.js 不把这个方向归为破坏性。反过来从可空改必填会拒绝旧请求；务必先确认旧版和新版的放置方向。
给 GraphQL 枚举增加一个值算破坏性变更吗？
新增枚举值通常不会让旧查询在校验阶段失败，但客户端若用穷举分支处理每个值，运行时可能出问题。因此 GraphQL.js 把它列为潜在危险，报告也保留这一类。
怎样重命名 GraphQL 类型而不破坏现有客户端？
两份 SDL 不含“这是改名”的迁移意图。GraphQL Schema 对比会把旧类型删除和新类型新增分别列出；如需平滑迁移，应在 API 中保留过渡字段或另做客户端迁移计划。
GraphQL Mutation 可以标记为弃用吗？
Mutation 根类型上的字段可以加 @deprecated。标记之后旧操作仍可调用，真正删除该字段才是另一回事；默认风险规则仍会把删除已弃用字段列为破坏性。
将 GraphQL 字段由非空改成可空会破坏兼容性吗？
输出字段从非空改为可空，可能改变客户端生成类型及其取值假设，GraphQL.js 会判为破坏性。相反方向会显示为结构变化，但解析器是否真的永不返回 null 仍需服务端测试。
遇到未覆盖的文档情况？