名称: graphql-inspector-审计用户可调用: false 描述: 当需要审计 GraphQL 操作的复杂度指标、深度分析、指令使用情况或查询性能问题时使用。允许工具: [读取, 写入, 编辑, Bash, Glob, Grep]

GraphQL 检查器 - 审计

精通 GraphQL 检查器的审计命令，用于分析操作复杂性和识别潜在性能问题。

概述

审计命令分析 GraphQL 操作，提供查询深度、指令计数、别名计数和复杂度等指标。这有助于识别可能在生产环境引起性能问题的操作。

核心命令

基本审计

# 审计所有 GraphQL 操作
npx @graphql-inspector/cli audit './src/**/*.graphql'

# 审计 TypeScript 文件中的操作
npx @graphql-inspector/cli audit './src/**/*.tsx'

# 使用多个模式审计
npx @graphql-inspector/cli audit './packages/**/*.graphql' './apps/**/*.tsx'

使用架构审计

# 针对特定架构审计
npx @graphql-inspector/cli audit './src/**/*.graphql' --schema './schema.graphql'

分析的指标

查询深度

测量查询的最大嵌套级别：

# 深度: 4
query 用户帖子 {
  user {           # 1
    posts {        # 2
      comments {   # 3
        author {   # 4
          name
        }
      }
    }
  }
}

高深度操作可能导致：

慢速数据库查询（N+1 问题）
解析器内存压力
长响应时间

别名计数

计数字段别名的数量：

# 别名计数: 3
query 多个用户 {
  admin: user(id: "1") { name }
  moderator: user(id: "2") { name }
  member: user(id: "3") { name }
}

高别名计数可能：

增加数据库查询次数
增大有效载荷大小
指示查询批处理滥用

指令计数

计操作中使用的指令数量：

# 指令计数: 4
query 条件数据($includeEmail: Boolean!, $skipPhone: Boolean!) {
  user {
    name
    email @include(if: $includeEmail)
    phone @skip(if: $skipPhone)
    avatar @cacheControl(maxAge: 3600)
    bio @deprecated
  }
}

令牌计数

计操作中的总令牌数量：

# 更高的令牌计数 = 更复杂的查询
query 复杂查询 {
  users(
    filter: { status: ACTIVE, role: ADMIN }
    orderBy: { field: NAME, direction: ASC }
    pagination: { limit: 10, offset: 0 }
  ) {
    id
    name
    email
    role
    createdAt
    updatedAt
  }
}

审计输出

审计命令为每个操作输出详细指标：

┌──────────────────────────────────────────────────────────────┐
│ 获取用户 (./src/queries/user.graphql)                         │
├──────────────────────────────────────────────────────────────┤
│ 深度        │ 5                                              │
│ 别名      │ 0                                              │
│ 指令   │ 2                                              │
│ 令牌       │ 45                                             │
│ 复杂度   │ 12                                             │
└──────────────────────────────────────────────────────────────┘

配置

创建 .graphql-inspector.yaml：

审计:
  文档: './src/**/*.graphql'

  # 警告阈值
  阈值:
    深度: 10
    别名: 5
    指令: 10
    令牌: 500
    复杂度: 100

CI/CD 集成

GitHub Actions

名称: 审计操作
用户可调用: false
在:
  拉取请求:
    路径:
      - 'src/**/*.graphql'
      - 'src/**/*.tsx'

作业:
  审计:
    运行在: ubuntu-latest
    步骤:
      - 使用: actions/checkout@v4

      - 名称: 安装检查器
        运行: npm install -g @graphql-inspector/cli

      - 名称: 审计操作
        运行: |
          graphql-inspector audit 'src/**/*.graphql'

审计报告

生成详细报告：

# JSON 输出用于处理
npx @graphql-inspector/cli audit './src/**/*.graphql' --json > 审计报告.json

# 人类可读输出
npx @graphql-inspector/cli audit './src/**/*.graphql' 2>&1 | tee 审计报告.txt

用例

预-PR 检查

在创建拉取请求前运行：

# 脚本在 PR 前检查操作
#!/bin/bash
echo "审计 GraphQL 操作..."
npx @graphql-inspector/cli audit './src/**/*.graphql'

如果 [ $? -ne 0 ]; 则
  echo "警告: 某些操作可能有性能问题"
fi

定期分析

安排定期审计：

# 每周 GraphQL 审计的 GitHub Action
名称: 每周 GraphQL 审计
用户可调用: false
在:
  计划:
    - cron: '0 9 * * 1'  # 周一 9am

作业:
  审计:
    运行在: ubuntu-latest
    步骤:
      - 使用: actions/checkout@v4
      - 运行: npm install -g @graphql-inspector/cli
      - 运行: graphql-inspector audit './src/**/*.graphql' --json > 审计.json
      - 名称: 上传审计报告
        使用: actions/upload-artifact@v4
        与:
          名称: graphql-审计
          路径: 审计.json

复杂度预算

按操作类型设置限制：

# 按操作类型的自定义阈值
审计:
  阈值:
    查询:
      深度: 10
      复杂度: 100
    变更:
      深度: 5
      复杂度: 50
    订阅:
      深度: 3
      复杂度: 25

最佳实践

定期审计 - 每周运行以捕获复杂性增长
设置阈值 - 为您的 API 定义可接受限制
跟踪趋势 - 随时间监控指标
审查异常值 - 调查高指标操作
优化热路径 - 关注频繁使用的操作
记录例外 - 解释为何需要复杂操作
教育团队 - 分享审计结果和最佳实践
自动化警报 - 当超出阈值时通知

常见模式

减少查询深度

之前（深度 6）：

query 深度查询 {
  user {
    posts {
      comments {
        author {
          profile {
            avatar
          }
        }
      }
    }
  }
}

之后（深度 3）：

query 扁平化查询 {
  user {
    posts {
      comments {
        作者姓名
        作者头像  # 去标准化字段
      }
    }
  }
}

减少别名计数

之前（5 个别名）：

query 多个用户 {
  user1: user(id: "1") { ...用户字段 }
  user2: user(id: "2") { ...用户字段 }
  user3: user(id: "3") { ...用户字段 }
  user4: user(id: "4") { ...用户字段 }
  user5: user(id: "5") { ...用户字段 }
}

之后（批处理查询）：

query 批处理用户 {
  users(ids: ["1", "2", "3", "4", "5"]) {
    ...用户字段
  }
}

故障排除

未找到操作

检查 glob 模式匹配文件
验证文件包含有效的 GraphQL 操作
确保文件扩展名已包含

指标似乎错误

验证操作完整
检查片段定义
审查内联片段使用

审计慢

使用特定 glob 限制范围
排除生成文件
如果可用，使用 --parallel

何时使用此技能

GraphQL 操作的性能分析
在生产前识别复杂查询
设置复杂度预算
定期代码库健康检查
培训开发人员查询优化
预发布质量门控

名称: graphql-inspector-审计 用户可调用: false 描述: 当需要审计 GraphQL 操作的复杂度指标、深度分析、指令使用情况或查询性能问题时使用。 允许工具: [读取, 写入, 编辑, Bash, Glob, Grep]