GraphQL架构差异检测与分析Skill：在架构上线前，把"破坏性变更"拦在 CI 里
- 它是什么：一个围绕
graphql-inspector-diff的专家知识型 AI 技能，专注 GraphQL 架构（Schema）版本之间的差异检测，能把变化精确归类为「重大 / 危险 / 非重大」。 - 它解决什么：字段被删、类型被改、非空约束被加上……这些改动一旦上线，客户端就会集体报错。这个技能帮你在部署前把这些变化找出来。
- 它能做什么：比较本地文件、Git 分支/提交/标签、远程端点之间的架构差异，支持
--onlyBreaking、--failOnDangerous、--json、自定义规则、基于实际操作的用法检查、Apollo 联合架构比较。 - 怎么用：最典型的方式是把它接入 CI/CD，在 Pull Request 上自动跑一次
graphql-inspector diff 'git:origin/main:schema.graphql' schema.graphql，破坏性变更不再靠人工肉眼比对。 - 适合谁： GraphQL 后端开发者、平台/SDK 团队、负责 API 治理与前端契约稳定的技术负责人。
该技能叫什么？如何下载安装 AI 技能提升开发效率？
技能中文名：GraphQL架构差异检测与分析Skill 技能英文名：graphql-inspector-diff 技能ID：13953
这个技能要解决的问题非常具体：GraphQL 的 Schema 就是前后端的"合同"，而合同修改往往发生得悄无声息。一个字段从 email: String 改成 email: String!，在后端看来只是"顺手加了个非空"，对客户端来说却可能是大面积 null 崩溃；一个枚举值被移除，线上某些老版本 App 的查询会直接失败。人工逐行 diff schema 文件既慢又容易漏，而普通文本 diff 工具又分不清"新增字段"和"删除字段"哪个是破坏性的。
这个技能本质上是 GraphQL Inspector 的 diff 命令的专家知识封装。它把比较语法、变化分类标准、配置规则、CI 集成模板、常见故障排查路径都整理成可直接复用的知识，注入到 AI 助手中。当你在会话里描述"我想比较主分支和当前分支的 schema 改动"时，助手能直接给出可执行的命令、参数组合和结果解读思路，而不是让你去翻文档。
需要说明的是，该技能的元信息标注为「用户可调用: false」，也就是说它不对外暴露一个独立的命令入口，而是作为专家知识在 AI 助手处理相关任务时被调用。因此"安装"的实际含义是：把这个技能加载到你的 AI 助手环境里，让助手在 GraphQL 架构差异相关话题上具备专家级回答能力。
一键安装的思路与步骤：
- 确认前提条件：你需要一个支持加载技能的 AI 助手运行环境；如果希望通过技能执行实际操作，还需要 Node.js 环境（因为核心命令基于
npx）以及一个待比较的 GraphQL Schema 文件（.graphql或通过 URL 提供）。 - 加载技能：在技能市场、技能库或团队内部的技能配置入口中，按技能名
graphql-inspector-diff或技能ID 13953 检索并启用。具体入口名称、按钮位置与安装命令以官方说明为准（不同平台差异较大，此处不虚构具体命令）。 - 验证是否生效：加载完成后，在会话中提一个"试探性问题"，例如「我要把
User.email从String改成String!，这算重大变更吗？怎么在 CI 里拦住它？」如果回答能准确归类为重大变更，并给出--onlyBreaking或--failOnDangerous这类参数建议，就说明技能已生效。 - 配套安装可比对工具：技能提供的是知识与流程指导，真正执行 diff 的动作仍由
@graphql-inspector/cli完成，典型方式是npx @graphql-inspector/cli diff a.graphql b.graphql；如需长期在 CI 中使用，可全局安装，安装方式与版本号以官方说明为准。 - 沉淀为团队规范：把技能建议的比较方式固化进仓库的 CI 配置和
.graphql-inspector.yaml规则文件，让"每次改 Schema 都跑一次 diff"变成流水线的默认动作。
该技能的主要功能和特点
- 三类变化分级：把差异严格划分为「重大变化」（会破坏现有客户端）、「危险变化」（可能破坏部分客户端）、「非重大变化」（不破坏客户端），而不是简单罗列增删行。
- 多源比较：支持本地文件互比、与 Git 分支 / 特定提交 / 标签比较（如
git:origin/main:schema.graphql、git:v1.0.0:schema.graphql）、与远程端点比较，甚至两个远程端点之间互比（如 staging 与 prod）。 - 精准过滤：
--onlyBreaking只看重大变化，--failOnDangerous在出现危险变化时直接让命令失败，--json输出机器可读结果便于二次处理。 - 规则可配置：支持
suppressRemovalOfDeprecatedField（允许移除已弃用字段）、suppressCommonPrefixChanges（忽略前缀重命名）等抑制规则，减少噪音。 - 基于使用的差异检测：
--rule considerUsage配合--documents "src/**/*.graphql"，只标记真正影响实际操作的重大变化，让"安全移除未使用字段"成为可能。 - 联合架构支持：通过
--federation比较 Apollo 联合架构的 subgraph，适配微服务拆分的团队。 - CI/CD 模板化知识：内置 GitHub Actions、GitLab CI 的完整配置样式，可直接套用。
- 故障排查经验：覆盖"架构未找到"“内省查询失败”"CI 检测到重大变化"等高频问题与对应处理路径。
和普通工具比强在哪：普通文本 diff 只能告诉你"这两行不一样"，而这个技能背后的 GraphQL Inspector 理解 Schema 语义——它知道"新增可选参数"是非重大的、"新增必需参数"是重大的、"可空字段变为非空"在输出位置属于危险变化。这种语义级判断，是文本工具完全无法提供的。
如何使用该技能？
步骤一：明确你要比较的两端
先想清楚基线是什么。推荐的做法是永远和主分支比，而不是随便找两个文件比。
步骤二：选择比较方式并执行
# 最基础：两个本地文件比较
npx @graphql-inspector/cli diff old-schema.graphql new-schema.graphql
# 推荐：与主分支比较（CI 中最常用）
npx @graphql-inspector/cli diff 'git:origin/main:schema.graphql' schema.graphql
# 与某个发布标签比较
npx @graphql-inspector/cli diff 'git:v1.0.0:schema.graphql' schema.graphql
# 本地架构 vs 远程端点
npx @graphql-inspector/cli diff 'https://api.example.com/graphql' schema.graphql
# 两个远程端点比较（如预发 vs 生产）
npx @graphql-inspector/cli diff 'https://staging.api.com/graphql' 'https://prod.api.com/graphql'
步骤三：加上合适的过滤与输出参数
# 只看会破坏客户端的变化
npx @graphql-inspector/cli diff old.graphql new.graphql --onlyBreaking
# 出现危险变化就让流程失败
npx @graphql-inspector/cli diff old.graphql new.graphql --failOnDangerous
# 输出 JSON，便于接入自定义报表
npx @graphql-inspector/cli diff old.graphql new.graphql --json
# 开启使用检查，减少误报
npx @graphql-inspector/cli diff old.graphql new.graphql \
--rule considerUsage \
--documents "src/**/*.graphql"
步骤四：读懂输出
输出会按类别列出变化条目。例如看到 User.email 被移除、Query 上新增 id: ID! 这类描述，就属于重大变化，说明这次发布大概率会打断现有客户端；看到「字段添加」「类型添加」「弃用添加」，则属于非重大变化，可以放心发布。
步骤五：把规则固化到配置里
在项目根目录创建 .graphql-inspector.yaml：
diff:
rules:
- suppressRemovalOfDeprecatedField
- considerUsage
failOnBreaking: true
failOnDangerous: false
上面的配置含义是：允许移除已被标记 @deprecated 的字段，启用使用情况检查，遇到重大变化时失败、遇到危险变化时仅提示。
步骤六：接入 CI，让检查自动化
以 GitHub Actions 为例，在 PR 变更涉及 schema.graphql 时自动执行：
- name: 安装检查器
run: npm install -g @graphql-inspector/cli
- name: 检查重大变化
run: |
graphql-inspector diff \
'git:origin/main:schema.graphql' \
schema.graphql \
--onlyBreaking
步骤七：按最佳实践收尾
推荐在真正删除字段前先加 @deprecated 并保留迁移窗口，先"添加新字段 + 弃用旧字段"，等客户端迁移完成后再移除旧字段。遇到危险变化不要直接放行，要人工复核，因为它们可能仍会破坏边缘情况。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 本技能（graphql-inspector-diff 专家知识） | 围绕 GraphQL Inspector diff 的知识型 AI 技能 | 三类变化分级、Git 引用比较、规则配置、联合架构、CI 模板、故障排查 | 需在 AI 助手中加载技能；实际操作依赖 Node.js 与 CLI | 希望快速获得"该怎么比较、结果怎么解读、CI 怎么写"的完整方案 | 优势：知识成体系、上手快、能直接产出可执行命令与配置；不足：本身不执行比较，需配合 CLI；元信息标注为不对外直接调用 |
| Apollo Studio Schema Checks | 托管式 Schema 治理平台 | 架构检查、操作流量感知、变更审批、发布门禁 | 需接入 Apollo 平台与账号体系 | 已使用 Apollo 生态、需要基于真实流量判断影响面的团队 | 优势：能结合生产流量判断实际影响；不足：与平台强绑定，成本与迁移门槛较高 |
| GraphQL Hive Schema Check | 开源可自托管的 Schema 注册与检查服务 | 架构版本管理、变更检查、CI 集成 | 需部署服务或使用云服务 | 希望自建 Schema 治理体系、对数据可控性有要求的团队 | 优势：可自托管、生态完整；不足：引入额外服务组件，运维成本上升 |
| 纯文本 diff（如 git diff） | 通用代码差异工具 | 逐行比对文本差异 | 零门槛，Git 自带 | 快速查看 schema 文件改了什么 | 优势：随手可用；不足：无法区分破坏性与非破坏性变化，容易被格式调整淹没，不能作为发布门禁 |
整体来看，如果你只需要"这一次改动到底危不危险"，本技能配合 GraphQL Inspector CLI 是成本最低、最直接的选择；如果你需要基于真实调用流量的长期治理，才需要考虑 Apollo Studio 或 Hive 这类平台化方案。二者并不冲突，很多团队是先用 CLI 做门禁，再逐步引入平台。
该技能的典型应用场景与实际体验情况
场景一：后端工程师提交 Schema 变更的 PR
痛点：改完 schema 直接提 PR，评审者只能靠肉眼扫 diff，漏看一个字段删除就可能引发线上事故。
使用方式：在 PR 流水线中挂上 --onlyBreaking 的检查任务，一旦检测到重大变化，流水线失败，PR 无法合并；作者必须在 PR 中说明原因或改为"先弃用、后移除"的两步走。
实际体验：上手几乎零成本，配置一次长期生效。需要注意的是，如果团队大量使用 @deprecated 但迟迟不清理，初期会积累一批"已知重大变化"，建议同步启用 suppressRemovalOfDeprecatedField 规则来降噪。
场景二：平台团队规划架构迁移（如字段重命名）
痛点：字段重命名看起来只是换个名字，实际可能让所有调用方一起崩。
使用方式：按技能给出的"安全字段重命名"两步法执行——阶段一新增 displayName 并把 name 标记为 @deprecated(reason: "使用displayName")；阶段二在客户端迁移完成后移除旧字段。每个阶段都用 diff 验证：阶段一应当只有非重大变化和弃用添加，阶段二在加上抑制规则后才允许通过。
实际体验：这是这个技能最有价值的部分，它把"迁移节奏"变成了可验证的流程，而不是靠口头约定。注意迁移窗口需要真正留足，否则阶段二的检查会立刻暴露客户端还没迁完的问题。
场景三：排查预发与生产的架构漂移
痛点：线上偶发报错，怀疑是环境间 Schema 不一致，但没人能说清差在哪。
使用方式：直接比较两个远程端点：
npx @graphql-inspector/cli diff 'https://staging.api.com/graphql' 'https://prod.api.com/graphql'
实际体验：一个字面命令就能定位漂移范围，效率远高于逐个环境导出再比对。注意远程比较依赖端点开启内省查询，并需要在配置中提供鉴权头（如 Authorization: Bearer ${API_TOKEN}），否则会报"内省查询失败"。
场景四：微服务团队的联合架构治理
痛点：多个 subgraph 拼成一个聚合图，某个 subgraph 删字段，影响面在聚合层才显现。
使用方式：在 subgraph 仓库的 CI 中用 --federation 参数比较新旧 subgraph 文件，把检查左移到各自的仓库里。
实际体验：能有效防止"局部改动、全局崩坏"。需要注意联合架构的差异判断规则比单体架构更复杂，建议配合 --rule considerUsage 一起使用以控制误报量。
该技能能为用户带来的价值
第一，把"事后救火"变成"事前拦截"。 破坏性变更如果在发布后才被发现，成本是故障排查、紧急回滚、客户端热修；如果在 PR 阶段被发现，成本只是一条流水线红灯。这个技能提供的正是一套经过验证的事前拦截方法论。
第二，大幅降低 Schema 治理的专业门槛。 「哪些变化算破坏性的」这件事有大量边界情况：可空变非空在输入位置和输出位置意义不同、枚举值添加是危险而非重大、联合成员移除是重大而添加是危险。这些规则不需要每个工程师都背下来，技能会直接给出判断依据和示例。
第三，减少误报带来的"警报疲劳"。 通过 considerUsage 基于实际操作检查、通过抑制规则忽略弃用字段移除，团队可以在大型架构中把噪音降到可接受范围，让门禁真正被信任，而不是被随手绕过。
第四，形成可复用的长期资产。 CI 配置、.graphql-inspector.yaml 规则、弃用工作流、字段重命名范式，这些一旦沉淀下来，会随项目生命周期持续产生收益：每一次 Schema 变更都被自动审视，架构演进有了可审计的轨迹。
第五，跨角色协作成本下降。 前端/客户端团队不再需要靠"口头同步"来确认后端改了什么，一份 diff 结果就是最清晰的对齐依据。
常见问题 FAQ
Q1：这个技能应该怎么安装？为什么找不到可直接运行的命令？
A：这是一个专家知识型技能，元信息标注为「用户可调用: false」，不对外暴露独立的命令入口。正确的"安装"方式是在你的 AI 助手技能库中检索技能名 graphql-inspector-diff 或技能ID 13953 并启用，随后助手在 GraphQL 架构差异相关话题上会给出专家级回答。真正的比较动作仍由 npx @graphql-inspector/cli diff 或全局安装的 CLI 执行。具体安装入口与命令以官方说明为准。
Q2：它是收费的吗？
A：技能详情中未包含任何价格或计费信息，因此本文不对收费情况作判断。技能所依托的 GraphQL Inspector 命令行工具的授权与使用条款，请以官方说明为准。建议在正式引入 CI 前先确认团队的合规与授权要求。
Q3：它和普通的 git diff 到底有什么区别？
A：git diff 比较的是文本行，它无法判断"删除一个字段"和"新增一个字段"哪一个会破坏客户端。这个技能背后的工具理解 GraphQL 语义，会把变化归入重大、危险、非重大三类，还能结合实际操作（considerUsage）判断某个重大变化是否真的有人在用。简单说：git diff 告诉你"变了什么"，它告诉你"这次变更能不能发"。
Q4：接入 CI 后老是失败，怎么减少误报？
A：三个方向：一是启用 --rule considerUsage 配合 --documents "src/**/*.graphql"，只标记真正影响实际操作的变更；二是在 .graphql-inspector.yaml 中加入抑制规则，如 suppressRemovalOfDeprecatedField、suppressCommonPrefixChanges；三是把危险变化与重大变化区别对待，重大变化阻塞合并、危险变化仅提示并人工复核。
Q5：这个技能适合谁用？不需要 GraphQL 经验也能用吗？
A：最适合 GraphQL 后端开发者、平台/SDK 团队和 API 治理负责人。如果你完全不熟悉 GraphQL，技能仍能在"这个概念为什么危险"的层面给出解释，但要真正落地 CI 门禁和弃用工作流，需要具备基本的 Schema 阅读能力和 Node.js 环境操作能力。对于刚开始接触 GraphQL 的团队，建议先在本地手动跑几次 diff、读懂输出，再接入流水线。