名称: graphql-inspector-diff 用户可调用: false 描述: 用于检测GraphQL架构版本之间的重大变化、跨分支比较架构或验证架构迁移时使用。允许工具: [读取, 写入, 编辑, Bash, Glob, Grep]

GraphQL检查器 - 架构差异

GraphQL检查器的diff命令的专家知识，用于检测GraphQL架构版本之间的重大、非重大和危险变化。

概述

GraphQL检查器的diff命令比较两个GraphQL架构，并输出精确的变化列表。每个变化被分类为重大、非重大或危险，帮助团队防止API回归。

核心命令

基本差异

# 比较两个架构文件
npx @graphql-inspector/cli diff old-schema.graphql new-schema.graphql

# 与git分支比较
npx @graphql-inspector/cli diff 'git:origin/main:schema.graphql' schema.graphql

# 与特定提交比较
npx @graphql-inspector/cli diff 'git:abc123:schema.graphql' schema.graphql

# 与标签比较
npx @graphql-inspector/cli diff 'git:v1.0.0:schema.graphql' schema.graphql

基于URL的比较

# 将本地架构与远程端点比较
npx @graphql-inspector/cli diff 'https://api.example.com/graphql' schema.graphql

# 比较两个远程端点
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

# 自定义规则
npx @graphql-inspector/cli diff old.graphql new.graphql --rule suppressRemovalOfDeprecatedField

# 输出为JSON
npx @graphql-inspector/cli diff old.graphql new.graphql --json

变化类别

重大变化

会破坏现有客户端的变化：

变化类型	示例
字段移除	`User.email` 被移除
类型移除	`UserType` 被删除
必需参数添加	查询上新增 `id: ID!`
类型更改	`User.age: Int` → `User.age: String`
非空约束添加	`email: String` → `email: String!`
联合成员移除	`SearchResult` 失去 `Product` 类型
枚举值移除	`Status.PENDING` 被移除
接口字段移除	`Node.id` 从接口移除

危险变化

可能破坏某些客户端的变化：

变化类型	示例
参数默认值更改	`limit = 10` → `limit = 20`
枚举值添加	新增 `Status.ARCHIVED`
可选参数添加	新增 `User.name(format: String)`
联合成员添加	`SearchResult` 获得 `Article` 类型
接口添加到类型	`User` 实现 `Timestampable`
可空字段变为非空	`email: String` → `email: String!` 在输出上

非重大变化

不会破坏客户端的更改：

变化类型	示例
字段添加	新增 `User.avatar` 字段
类型添加	新增 `Comment` 类型
可选参数添加	新增 `users(filter: String)`
弃用添加	`@deprecated(reason: "使用newField")`
描述更改	更新的字段文档
指令添加	`@cacheControl(maxAge: 60)`

配置

规则配置

创建 .graphql-inspector.yaml：

diff:
  rules:
    - suppressRemovalOfDeprecatedField
    - considerUsage
  failOnBreaking: true
  failOnDangerous: false

可用规则

# 抑制规则
- suppressRemovalOfDeprecatedField  # 可以移除弃用的字段
- suppressCommonPrefixChanges       # 忽略前缀重命名

# 基于使用的规则
- considerUsage                     # 检查重大变化是否影响实际使用

架构源

# 本地文件
old: ./old-schema.graphql

# Git引用
old: git:origin/main:schema.graphql

# 带头的URL
old:
  url: https://api.example.com/graphql
  headers:
    Authorization: Bearer ${API_TOKEN}

# Glob模式
new: ./**/*.graphql

CI/CD集成

GitHub Actions

name: 架构差异
用户可调用: false
on:
  pull_request:
    paths:
      - 'schema.graphql'
      - '**/*.graphql'

jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 安装检查器
        run: npm install -g @graphql-inspector/cli

      - name: 检查重大变化
        run: |
          graphql-inspector diff \
            'git:origin/main:schema.graphql' \
            schema.graphql \
            --onlyBreaking

GitLab CI

架构差异:
  image: node:20
  script:
    - npm install -g @graphql-inspector/cli
    - graphql-inspector diff "git:origin/main:schema.graphql" schema.graphql
  rules:
    - changes:
        - "**/*.graphql"

基于使用的差异检测

检查重大变化是否影响实际操作：

# 提供操作以检查
npx @graphql-inspector/cli diff old.graphql new.graphql \
  --rule considerUsage \
  --documents "src/**/*.graphql"

好处：

仅标记影响实际操作的重大变化
允许安全移除未使用的字段
在大型架构中减少误报

联合支持

对于Apollo联合架构：

# 比较联合架构
npx @graphql-inspector/cli diff \
  --federation \
  old-subgraph.graphql \
  new-subgraph.graphql

最佳实践

部署前始终差异 - 在每次架构更改时在CI中运行差异
使用Git引用 - 与主分支比较，而非任意文件
启用使用检查 - 通过检查实际使用减少噪音
记录弃用 - 在移除字段前添加 @deprecated
审查危险变化 - 它们可能仍会破坏边缘情况
保持弃用窗口 - 给客户端时间迁移
自动化在PR中 - 在拉取请求上评论差异结果
版本化你的架构 - 标记发布以便轻松比较

常见模式

弃用工作流

# 步骤1: 添加新字段并弃用旧字段
type User {
  fullName: String!
  name: String @deprecated(reason: "使用fullName代替")
}

# 步骤2: 迁移窗口后，移除旧字段
type User {
  fullName: String!
}

安全字段重命名

# 阶段1: 添加别名并弃用旧名称
type User {
  displayName: String!
  name: String @deprecated(reason: "使用displayName")
}

# 阶段2: 客户端迁移后移除
type User {
  displayName: String!
}

故障排除

常见问题

“架构未找到”

验证文件路径正确
检查Git引用语法：git:branch:path
确保架构文件存在于指定位置

“CI中检测到重大变化”

审查变化是否是有意的
如果移除字段，添加弃用
如果字段已被弃用，使用 --rule suppressRemovalOfDeprecatedField

“内省查询失败”

检查URL是否可访问
验证身份验证头部
确保端点上启用了内省

何时使用此技能

规划架构迁移
审查拉取请求中的架构更改
设置CI/CD以进行架构验证
检测部署前的重大变化
比较生产与开发架构
审计架构随时间演变

名称: graphql-inspector-diff 用户可调用: false 描述: 用于检测GraphQL架构版本之间的重大变化、跨分支比较架构或验证架构迁移时使用。 允许工具: [读取, 写入, 编辑, Bash, Glob, Grep]