graphql-inspector-validate

用途

GraphQL Inspector - Validate 是 GraphQL Inspector 的 validate 命令相关技能，用于将 GraphQL 操作（queries、mutations、subscriptions）和 fragments 与 schema 进行校验。它能在运行时之前捕获未定义字段、参数类型错误、无效的 fragment spread 等错误。

主要能力

基础校验

可对 .graphql 文件或 TypeScript 文件中的操作进行校验：

# Validate operations against schema
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql'

# Validate operations from TypeScript files
npx @graphql-inspector/cli validate './src/**/*.tsx' './schema.graphql'

支持 glob 模式：

npx @graphql-inspector/cli validate './**/*.{graphql,gql}' './schema.graphql'

Federation 支持

# 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 directives
npx @graphql-inspector/cli validate './operations/**/*.graphql' './schema.graphql' \
  --aws

校验规则

深度限制（Depth Limiting）：防止过深嵌套查询导致性能问题。

# Fail if query depth exceeds 10
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxDepth 10

别名数量（Alias Count）：限制别名使用，防止响应爆炸。

# Max 5 aliases per operation
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxAliasCount 5

指令数量（Directive Count）：限制指令以防止滥用。

# Max 10 directives per operation
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxDirectiveCount 10

Token 数量（Token Count）：按 token 数量限制查询复杂度。

# Max 1000 tokens per operation
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxTokenCount 1000

复杂度分数（Complexity Score）：计算并限制查询复杂度。

# Max complexity score of 100
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxComplexityScore 100

配置文件

可创建 .graphql-inspector.yaml：

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

  # Validation limits
  maxDepth: 10
  maxAliasCount: 5
  maxDirectiveCount: 10
  maxTokenCount: 1000
  maxComplexityScore: 100

  # Federation support
  federation: false
  federationV2: false
  aws: false

常见校验错误

Unknown Field：Cannot query field "unknownField" on type "User". 修复：检查字段名拼写或向 schema 添加字段。
Wrong Argument Type：Argument "id" has invalid value "123". Expected type "ID!", found "123" (String). 修复：使用正确的参数类型。
Missing Required Argument：Field "user" argument "id" of type "ID!" is required. 修复：提供必需参数。
Invalid Fragment Spread：Fragment "UserFields" cannot be spread here as objects of type "Post" can never be of type "User". 修复：确保 fragment 类型与展开位置匹配。
Unused Fragment：Fragment "UnusedFragment" is never used. 修复：移除或使用该 fragment。

使用方式

CI/CD 集成（GitHub Actions）

name: Validate Operations
user-invocable: false
on:
  pull_request:
    paths:
      - 'src/**/*.graphql'
      - 'src/**/*.tsx'
      - 'schema.graphql'

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

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

      - name: Validate operations
        run: |
          graphql-inspector validate \
            'src/**/*.graphql' \
            schema.graphql \
            --maxDepth 10 \
            --maxAliasCount 5

Pre-commit 钩子

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

从代码中提取操作

GraphQL Inspector 可从多种文件类型中提取操作，例如 TypeScript/JavaScript 模板字面量以及 React 中的 tagged template literals：

// Operations in template literals are detected
const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      name
      email
    }
  }
`;

// Tagged template literals in React files
import { gql } from '@apollo/client';

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

适用场景

在 CI/CD 中设置操作校验
强制执行查询复杂度限制
在部署前校验操作
尽早捕获 schema 与操作不匹配
防止过深嵌套查询
审计现有操作是否符合规范

最佳实践

在 CI 中校验：对每个影响 GraphQL 文件的 PR 运行校验
设置合理限制：从宽松限制开始，逐步收紧
针对生产 schema 校验：确保操作在生产环境可用
从代码中提取操作：校验所有操作，而不仅是 .graphql 文件
使用 Federation 标志：如使用 Apollo Federation 则启用
对警告失败：在 CI 中将未使用 fragment 视为错误
为 schema 版本化：针对特定 schema 版本校验
记录限制原因：向开发者解释限制存在的原因

常见模式

多 Schema 校验

适用于包含多个 schema 的 monorepo：

# Validate against specific service schema
npx @graphql-inspector/cli validate \
  './packages/app/src/**/*.graphql' \
  './packages/api/schema.graphql'

# Validate against federated supergraph
npx @graphql-inspector/cli validate \
  './packages/web/src/**/*.graphql' \
  './supergraph.graphql' \
  --federationV2

渐进式采用

从宽松开始，逐步添加更严格的规则：

# Phase 1: Basic validation only
validate:
  schema: './schema.graphql'
  documents: './src/**/*.graphql'

# Phase 2: Add depth limiting
validate:
  schema: './schema.graphql'
  documents: './src/**/*.graphql'
  maxDepth: 15

# Phase 3: Add complexity limits
validate:
  schema: './schema.graphql'
  documents: './src/**/*.graphql'
  maxDepth: 10
  maxAliasCount: 10
  maxComplexityScore: 200

限制与故障排查

"Schema file not found"：确认 schema 路径正确；检查 glob 模式是否匹配 schema 位置；相对路径失败时可使用绝对路径。
"No documents found"：检查 glob 模式是否匹配操作文件；确认文件扩展名正确；确保文件包含 GraphQL 操作。
"Unknown directive"：为 Federation 指令添加 --federation 或 --federationV2；为 AppSync 指令添加 --aws；检查自定义指令是否在 schema 中定义。
代码中未检测到操作：确保使用 tagged template literal（gql...）；检查文件扩展名是否包含在 glob 中；确认 GraphQL Inspector 能解析该文件类型。

关于收费、价格、平台支持范围等具体信息，资料中暂未提供。