知海

JavaScript：GraphQL Inspector（Schema 检查工具）

graphql-github-io-zh-Hans生态项目与库

JavaScript：GraphQL Inspector（Schema 检查工具）

简介

GraphQL Inspector 是一款用于 GraphQL Schema 与文档检查的开源命令行工具。它能够帮助开发者在持续集成（CI）流程中自动比对 Schema 变更、验证 GraphQL 文档、发现破坏性变更（Breaking Changes），以及评估 Schema 的覆盖率，从而有效维护 GraphQL API 的质量与一致性。

GraphQL Inspector

核心功能

  • Schema 比对：支持 diff 命令，比对两个 Schema 版本的差异，并输出变更摘要。
  • 验证文档：通过 validate 命令，检查 GraphQL 文档（Queries / Mutations / Subscriptions）是否符合当前 Schema 定义。
  • 破坏性变更检测：使用 breaking-change 检测规则，自动标记可能导致客户端运行失败的变更，辅助版本管理与升级评估。
  • 相似类型查找：通过 similar 命令，识别 Schema 中结构相近的类型，帮助精简与规范化设计。
  • Schema 覆盖率：通过 coverage 命令，统计文档中实际使用的 Schema 字段占比，直观反映测试或使用范围。
  • Git 集成：支持基于 Git 分支或提交记录的 Schema 变更检测，方便接入 Code Review 流程。

安装

GraphQL Inspector CLI 通过 npm 分发，包名为 @graphql-inspector/cli。

bash 复制代码 
npm install -g @graphql-inspector/cli

也可以在项目内作为开发依赖安装：

bash 复制代码 
npm install --save-dev @graphql-inspector/cli

基本用法

以下是几个常用命令示例：

比较两个 Schema

bash 复制代码 
graphql-inspector diff schema-old.graphql schema-new.graphql

检测破坏性变更

bash 复制代码 
graphql-inspector diff schema-old.graphql schema-new.graphql --rule breaking-change

验证文档合法性

bash 复制代码 
graphql-inspector validate schema.graphql 'src/**/*.graphql' --rule no-duplicate-fields

计算 Schema 覆盖率

bash 复制代码 
graphql-inspector coverage schema.graphql './src/**/*.ts' --silent

生态与集成

GraphQL Inspector 提供了多种集成方式：

  • GitHub App：自动在 Pull Request 中发表 Schema 变更评论。
  • GitLab CI / GitHub Actions：通过官方文档提供的配置模板，快速接入流水线。
  • Webhook / Slack 通知：结合 CI 脚本，将变更报告推送到团队通信工具。

相关资源

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。