GraphQL 限流与成本控制：查询成本分析、复杂度限制与按量计费

GraphQL 的「查询即正文」让同一个端点可以承载从「请求一个标量」到「请求十万个嵌套字段」的极端差异。REST 限流按 URL 计数，而 GraphQL 如果只按请求数限流，一条 100KB 的超深查询和一条 1KB 的轻查询会被同等对待——这既不公平，也极易被打穿。本文将深入查询成本分析（Query Cost Analysis）、深度/宽度/别名限制、速率限制策略与按量计费模型，帮助你建立一套既能防御滥用、又能公平收费的 GraphQL 成本治理体系。

一、为什么 GraphQL 需要成本控制

1.1 查询复杂度不受 URL 约束

REST 的资源边界在 URL 上，一个请求的成本大体可预测。GraphQL 把「取什么」的权力交给了客户端，于是出现了两种滥用形态：

深度攻击（Deep Nesting）：

query Deep {
  a { b { c { d { e { f { g { h { ... } } } } } } }
}

别名放大（Alias Amplification）：

query AliasFlood {
  p1: user(id: 1) { name }
  p2: user(id: 1) { name }
  p3: user(id: 1) { name }
  # ... 重复数百次
}

这两种查询都在一个请求内，但成本是普通查询的成百上千倍。仅按「请求次数」限流完全无法防御。

1.2 成本失控的连锁反应

成本失控不仅拖垮数据库，还拖垮「所有用户」——一个超深查询占满连接池，其他用户的请求全部排队。同时，若开放 API 按调用计费，滥用者还能享受「一条请求拿全量数据」的免费午餐。成本治理的三大目标：防御 DoS、保障公平、支撑计费。

二、查询成本分析（Query Cost Analysis）

2.1 字段权重模型

Query Cost Analysis 的核心是给查询树中的每个节点分配权重，累加为查询总成本。最简模型（graphql-cost-analysis 库）为每个字段设置权重，列表字段再乘以系数：

import costAnalysis from 'graphql-cost-analysis';

const costLimitRule = costAnalysis({
  maximumCost: 1000,
  defaultCost: 1,
  costMap: {
    Product: { title: 1, price: 2 },
    Query: { products: 10, product: 5 },   // 列表根字段成本更高
  },
  variables: true,   // 允许变量参与成本计算
  onCost: (cost) => console.log(`查询成本：${cost}`),
});

总成本公式：

总成本 = Σ(字段权重) + Σ(列表字段 × 列表系数)

2.2 列表与嵌套的成本放大

列表是成本放大器，因为 [Product!]! 的 first: 100 会把下游字段成本乘上 100。成熟方案对列表字段引入「节点成本 × 预计列表长度」的模型：

# 成本预估：products(5 个) × (title:1 + price:2) + root 10 ≈ 25
query Cheap {
  products(first: 5) { title price }
}

# 成本预估：products(100) × (title:1 + price:2 + stock:3 + tags:50) + root 10 ≈ 610
query Expensive {
  products(first: 100) {
    title price stock
    tags { name weight }
  }
}

2.3 成本分析的服务端实现

在生产网关（Apollo Server / Yoga / Router）中接入成本校验：

import { createYoga } from 'graphql-yoga';
import costAnalysis from 'graphql-cost-analysis';

const yoga = createYoga({
  schema,
  plugins: [
    {
      onParse() {},
      async onExecute({ args }) {
        const validationRule = costAnalysis({ maximumCost: 1000, defaultCost: 1 });
        const errors = validationRule(args.contextValue);
        if (errors.length > 0) {
          throw new Error('查询成本超限，请联系 API 提供方');
        }
      },
    },
  ],
});

超限查询在进入 resolver 前被拦截，返回可读错误而非让解析器执行。

三、深度、宽度与别名限制

3.1 深度限制

深度限制防止无限嵌套。设置 max_depth: 8 时，超过 8 层的查询直接拒绝。实现上，校验规则在查询 AST 中遍历嵌套层级：

query TooDeep {
  user {
    orders {
      items {
        product {
          category {
            brand {
              owner {        # 深度超限
                address { city }
              }
            }
          }
        }
      }
    }
  }
}

3.2 宽度与别名限制

宽度指根字段数量、别名指同一字段重复出现的次数。两者都限制「单个请求的扇出」。Apollo Router 的 limits 配置可一次性覆盖：

limits:
  preview_operation_limits:
    max_depth: 10          # 最大深度
    max_height: 100        # 最大字段总量
    max_aliases: 30        # 最大别名数
    max_root_fields: 5     # 最大根字段数

3.3 限制与业务正当需求的平衡

限制过严会误伤正常业务（如管理后台需要大列表）。建议按「调用方身份」分层设定阈值：

限流规则通常结合「客户端标识 + 用户身份」动态计算，而不是全局一刀切。

四、速率限制策略

4.1 请求数 vs 成本配额

比「每分钟 100 请求」更公平的是「每分钟 1000 成本点」。GraphQL 生态的实践是按成本点计数的令牌桶（Token Bucket）：每个查询消耗其成本分析值，桶内令牌用完则 429 拒绝。

// 令牌桶实现（伪代码，生产用 Redis 分布式版本）
const bucket = {
  capacity: 1000,        // 每分钟可消耗 1000 成本点
  tokens: 1000,
  refillPerMin: 1000,
};

function consume(queryCost) {
  if (bucket.tokens >= queryCost) {
    bucket.tokens -= queryCost;
    return true;
  }
  return false; // 触发 429
}

收益：一个 500 成本的查询和一个 5 成本的查询，前者只能发 2 次，后者能发 200 次——既公平又能防御单点滥用。

4.2 分布式限流

多实例部署下，限流计数必须集中。Redis 的滑动窗口或令牌桶实现：

import { createClient } from 'redis';

const redis = createClient();

async function checkRateLimit(clientId: string, cost: number): Promise<boolean> {
  const key = `rl:${clientId}:${Math.floor(Date.now() / 60000)}`; // 分钟窗口
  const current = await redis.incrBy(key, cost);
  if (current === cost) await redis.expire(key, 65); // 首次创建时设 TTL
  return current <= 1000; // 每分钟 1000 成本点
}

4.3 优雅降级与错误语义

限流不应「杀死」用户体验。推荐响应语义：

• 429 Too Many Requests + Retry-After 头，客户端可据此退避。
• GraphQL errors 的 extensions.code: "RATE_LIMITED"，附带配额剩余与重置时间。

{
  "data": null,
  "errors": [
    {
      "message": "查询成本超限，请降低查询规模或在 60 秒后重试",
      "extensions": {
        "code": "RATE_LIMITED",
        "cost": 1200,
        "limit": 1000,
        "retryAfterSec": 45
      }
    }
  ]
}

五、按量计费模型

5.1 基于成本点的计费

开放 GraphQL API 若按「请求数」计费，同样的钱买到的是天差地别的算力。基于成本点的计费更公平：账单 = 每次查询成本点累加 × 单价。

5.2 配额与套餐

• 免费层：每天 5000 成本点，面向开发者试用。
• 按量付费：超出免费层按「成本点 / 1000」阶梯计价。
• 企业套餐：包月配额 + 超量按量，内部服务不限。

计费数据来源就是「成本分析 + 实际执行日志」：每次查询记录 clientId + operationName + cost + bytes + latency，定时聚合生成账单。

5.3 用量观测与账单仪表盘

成本治理离不开观测。推荐指标：

• graphql.query.cost（Histogram）：查询成本分布。
• graphql.rate_limit.rejected_total：被限流请求计数。
• graphql.query.cost_by_operation：按操作名聚合的成本占比。

仪表盘展示 Top N 高成本操作、Top N 高成本客户端，让团队持续发现「哪些查询在烧钱」并针对性优化 resolver 或调整权重。

六、成本模型维护与校准

6.1 权重校准流程

成本权重不是一次写死就完事。生产实践采用「假设 → 观测 → 校准」循环：

1. 为字段设定初始权重（按解析耗时、数据量估）。
2. 上线后观测各字段实际延迟与返回体积。
3. 每季度校准：把高成本字段的权重上调，低成本字段下调。

6.2 字段权重的动态来源

理想情况下权重与「实测成本」联动：

{
  "Query.products": { "cost": 10 },
  "Product.tags": { "cost": 5, "listMultiplier": 1.5 }
}

对新增字段默认给 defaultCost（如 1），接入观测后逐步细化。避免「字段极多但权重全部为 1」导致成本模型失真。

6.3 成本与缓存的联动

缓存命中能大幅降低真实成本。成本控制体系应区分「执行成本」与「计费成本」：

• 计费按「查询成本点」计，与是否缓存无关（保证公平）。
• 资源负载按「实际执行」计，缓存命中不消耗 DB。
• 对高频读接口引导走 CDN/边缘缓存，降低源站压力，也让用户的成本点用得更值。

七、生产落地清单

1. 分阶段启用：先只记录成本（不拒绝），上线一周收集真实分布。
2. 定阈值：基于 P99 成本分布设定三层阈值（告警 / 限流 / 拒绝）。
3. 按身份分层：匿名、登录、内部服务使用不同限制。
4. 分布式计数：多实例统一走 Redis。
5. 可读错误：RATE_LIMITED + 剩余配额 + 重试时间。
6. 观测闭环：成本分布、被拒请求、Top 操作仪表盘。
7. 定期校准：按实测延迟/体积调整字段权重。

八、一句话总结

GraphQL 成本治理的答案是把「请求」转化为「成本点」：用查询成本分析给每个查询算分，用深度/宽度/别名限制防放大攻击，用基于成本点的令牌桶做公平限流，再把成本点直接映射为按量计费——从而实现防御滥用、保障公平与支撑商业化的三赢。

FAQ

Q1: 只做深度限制够吗？

A: 不够。深度限制只防嵌套攻击，防不了宽度扇出（大量根字段）、别名放大（同一字段重复）与高成本列表（超大 first）。完整防线是「深度 + 宽度 + 别名 + 成本分析」四者组合，各自覆盖不同的放大维度。

Q2: 请求数限流和成本限流哪个更好？

A: 成本限流严格更公平，但它需要成本模型维护成本。务实做法是双轨：请求数限流做兜底（防止高频小查询刷接口），成本限流做精细化控制（防超深/超大查询）。两者结合覆盖「频率滥用」与「单次滥用」两类威胁。

Q3: 按量计费的数据从哪里来？

A: 来自「成本分析 + 执行日志」的聚合：每次查询记录 clientId、operationName、cost、bytes、latency。计费系统按客户与时间窗口聚合成本点，乘单价生成账单。关键在于 cost 的归属要准确——通过 API key / 客户端标识绑定到具体租户。

Q4: 成本权重怎么设定初始值？

A: 先用统一 defaultCost（如 1），再为高频与高成本字段单独设权重：列表根字段 510，嵌套对象字段按「预计解析成本」设为 25，昂贵外部调用（推荐算法、搜索）10~50。上线后按实测延迟/体积每季度校准，让权重逼近真实资源消耗。

Q5: 限流对合法但大查询的客户误伤怎么办？

A: 分层限制 + 弹性配额：企业/内部服务用更高的成本上限；合法客户超限时返回带 retryAfterSec 的 429 并允许排队重试；提供「按量付费」通道，让超配额请求走计费而不是直接拒绝。误伤的核心解法是「身份分层」而非一刀切。

相关阅读

• GraphQL 安全与防护：深度查询、认证授权与错误信息泄漏防控
• GraphQL Resolver 性能与 N+1 优化
• API 缓存与性能优化
• GraphQL Federation：分布式 Schema 设计与服务编排