名称: graphql-inspector-validate 用户可调用: false 描述: 用于根据架构验证GraphQL操作/文档，检查查询深度、复杂性或片段使用情况。允许的工具: [读取, 写入, 编辑, Bash, Glob, Grep]

GraphQL Inspector - 验证

GraphQL Inspector的验证命令的专家知识，用于根据可配置规则检查操作和文档与架构的匹配。

概述

验证命令检查GraphQL操作（查询、变更、订阅）和片段是否与架构匹配。它在运行时之前捕获错误，如未定义的字段、错误的参数类型和无效的片段扩展。

核心命令

基本验证

# 根据架构验证操作
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql'

# 从TypeScript文件验证操作
npx @graphql-inspector/cli validate './src/**/*.tsx' './schema.graphql'

# 使用全局模式验证
npx @graphql-inspector/cli validate './**/*.{graphql,gql}' './schema.graphql'

联邦支持

# Apollo Federation V1
npx @graphql-inspector/cli validate './operations/**/*.graphql' './schema.graphql' \
  --federation

# Apollo Federation V2
npx @graphql-inspector/cli validate './operations/**/*.graphql' './schema.graphql' \
  --federationV2

# AWS AppSync指令
npx @graphql-inspector/cli validate './operations/**/*.graphql' './schema.graphql' \
  --aws

验证规则

深度限制

防止可能导致性能问题的深度嵌套查询：

# 如果查询深度超过10则失败
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxDepth 10

违规示例：

# 深度为8 - 可能超过限制
query DeepQuery {
  user {                     # 1
    posts {                  # 2
      author {               # 3
        followers {          # 4
          posts {            # 5
            comments {       # 6
              author {       # 7
                name         # 8
              }
            }
          }
        }
      }
    }
  }
}

别名数量

限制别名使用以防止响应爆炸：

# 每个操作最多5个别名
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxAliasCount 5

违规示例：

# 6个别名 - 超过5个限制
query TooManyAliases {
  user1: user(id: "1") { name }
  user2: user(id: "2") { name }
  user3: user(id: "3") { name }
  user4: user(id: "4") { name }
  user5: user(id: "5") { name }
  user6: user(id: "6") { name }  # 超过限制
}

指令数量

限制指令以防止滥用：

# 每个操作最多10个指令
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxDirectiveCount 10

令牌数量

通过令牌数量限制查询复杂性：

# 每个操作最多1000个令牌
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxTokenCount 1000

复杂性分数

计算并限制查询复杂性：

# 最大复杂性分数为100
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxComplexityScore 100

配置文件

创建 .graphql-inspector.yaml：

validate:
  schema: './schema.graphql'
  documents: './src/**/*.graphql'

  # 验证限制
  maxDepth: 10
  maxAliasCount: 5
  maxDirectiveCount: 10
  maxTokenCount: 1000
  maxComplexityScore: 100

  # 联邦支持
  federation: false
  federationV2: false
  aws: false

常见验证错误

未知字段

错误: 无法在类型“User”上查询字段“unknownField”。

修复: 检查字段名称拼写或将字段添加到架构。

错误的参数类型

错误: 参数“id”具有无效值“123”。
预期类型“ID!”，找到“123”（字符串）。

修复: 使用正确的参数类型。

缺少必需参数

错误: 字段“user”的参数“id”类型为“ID!”是必需的。

修复: 提供必需参数。

无效的片段扩展

错误: 片段“UserFields”无法在此处扩展，因为类型“Post”的对象永远不能是类型“User”。

修复: 确保片段类型与扩展位置匹配。

未使用的片段

警告: 片段“UnusedFragment”从未使用。

修复: 删除或使用该片段。

CI/CD集成

GitHub Actions

name: 验证操作
用户可调用: false
on:
  pull_request:
    paths:
      - 'src/**/*.graphql'
      - 'src/**/*.tsx'
      - 'schema.graphql'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 安装Inspector
        run: npm install -g @graphql-inspector/cli

      - name: 验证操作
        run: |
          graphql-inspector validate \
            'src/**/*.graphql' \
            schema.graphql \
            --maxDepth 10 \
            --maxAliasCount 5

预提交钩子

{
  "husky": {
    "hooks": {
      "pre-commit": "graphql-inspector validate 'src/**/*.graphql' schema.graphql"
    }
  }
}

从代码中提取操作

GraphQL Inspector可以从各种文件类型中提取操作：

TypeScript/JavaScript

// 模板文字中的操作被检测到
const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      name
      email
    }
  }
`;

React with GraphQL

// React文件中的标记模板文字
import { gql } from '@apollo/client';

const USER_QUERY = gql`
  query UserQuery {
    currentUser {
      id
      name
    }
  }
`;

最佳实践

在CI中验证 - 每次影响GraphQL文件的PR都运行验证
设置合理限制 - 从宽松限制开始，随时间收紧
针对生产架构验证 - 确保操作在生产中工作
从代码中提取操作 - 验证所有操作，不仅是.graphql文件
使用联邦标志 - 如果使用Apollo Federation则启用
警告视为错误 - 在CI中将未使用的片段视为错误
版本化架构 - 针对特定架构版本验证
记录限制 - 向开发人员解释限制存在的原因

常见模式

多架构验证

对于具有多个架构的单体仓库：

# 针对特定服务架构验证
npx @graphql-inspector/cli validate \
  './packages/app/src/**/*.graphql' \
  './packages/api/schema.graphql'

# 针对联邦超图验证
npx @graphql-inspector/cli validate \
  './packages/web/src/**/*.graphql' \
  './supergraph.graphql' \
  --federationV2

增量采用

从宽松开始，随时间添加更严格的规则：

# 阶段1: 仅基本验证
validate:
  schema: './schema.graphql'
  documents: './src/**/*.graphql'

# 阶段2: 添加深度限制
validate:
  schema: './schema.graphql'
  documents: './src/**/*.graphql'
  maxDepth: 15

# 阶段3: 添加复杂性限制
validate:
  schema: './schema.graphql'
  documents: './src/**/*.graphql'
  maxDepth: 10
  maxAliasCount: 10
  maxComplexityScore: 200

故障排除

“架构文件未找到”

验证架构路径是否正确
检查全局模式是否匹配架构位置
如果相对路径失败，使用绝对路径

“未找到文档”

检查全局模式是否匹配操作文件
验证文件扩展名是否正确
确保文件包含GraphQL操作

“未知指令”

为联邦指令添加--federation或--federationV2
为AppSync指令添加--aws
检查自定义指令是否在架构中定义

代码中未检测到操作

确保使用标记模板文字（gql\…``）
检查文件扩展名是否包含在全局中
验证GraphQL Inspector可以解析文件类型

何时使用此技能

在CI/CD中设置操作验证
强制执行查询复杂性限制
在部署前验证操作
早期捕获架构-操作不匹配
防止深度嵌套查询
审计现有操作是否符合规定

名称: graphql-inspector-validate 用户可调用: false 描述: 用于根据架构验证GraphQL操作/文档，检查查询深度、复杂性或片段使用情况。 允许的工具: [读取, 写入, 编辑, Bash, Glob, Grep]