# GraphQL 查询安全：深度限制、复杂度、持久化查询与滥用防护

> 用深度与复杂度限制、分页上限、别名与批量控制、持久化查询、按操作限流和字段级授权，系统加固 GraphQL 端点。

**快速答案:** GraphQL 要按操作而非按 URL 防护：在执行前拒绝超过深度、复杂度、别名、批量或分页预算的文档；限制内省但不能依赖它保证安全；在服务端强制执行持久化查询；按操作名和成本限流；逐字段授权；每个请求使用独立 DataLoader 合并查询；错误只返回稳定错误码，不返回堆栈。

## 核心要点

- 单一 GraphQL 端点把操作藏在请求体里，基于路径的限流、WAF 规则和缓存键无法区分便宜查询与昂贵变更。
- 深度限制只能挡住递归，挡不住宽度、别名和列表乘法；复杂度必须基于校验后的文档并结合变量值计算。
- 关闭内省和使用持久化查询只能减少暴露面，前提是服务端仍强制执行深度、成本、批量和授权检查。
- 客户端白名单只是建议；服务端必须只执行可信文档，并按操作成本而不是原始请求数计费限流。
- 字段级授权、请求级 DataLoader、输入上限和脱敏错误，才能补上查询形状限制覆盖不到的缺口。

---

GraphQL 把 Schema 交给客户端，并允许客户端决定每个响应的形状。这种灵活性既是特性，也是攻击面：一个 HTTP 端点接受 Schema 暴露的所有查询、变更和订阅，而一次请求的成本由客户端提交的文档决定，不由 URL 决定。REST API 可以按 `GET /users/:id` 限流，因为路由本身就说明了操作。GraphQL 服务器收到的是 `POST /graphql` 加请求体里的查询，基于 URL 的规则、WAF 签名和缓存键几乎看不到有用信息。真正有效的控制必须理解操作本身：解析、评分、授权，最后才执行。

## 为什么单一端点会打破限流与 WAF 假设

在 REST 中，路径标识资源，也大致标识成本。WAF 可以拦截 `/admin/*`，CDN 可以缓存 `GET /products`，限流器可以给每条路由独立预算。GraphQL 把这些区分全部压平。`POST /graphql` 既可能承载 `query { viewer { id } }`，也可能承载删除账户的变更，两者都可能返回 HTTP 200。因此基于状态码的监控会漏掉 GraphQL 故障：校验错误、授权失败和解析器异常都可能以 200 加 `errors` 数组的形式返回。

这带来三个后果。第一，按 HTTP 请求限流用错了单位；一个请求可能包含数千次字段解析，每秒十个便宜查询可能无害，而每分钟一个昂贵查询就能拖垮数据库。第二，按路径和方法匹配的 WAF 规则无法区分操作，拦截必须发生在解析之后，放在 GraphQL 层或理解 GraphQL 的网关里。第三，共享缓存基本帮不上忙：POST 请求体默认不可缓存，除非采用 GET 加持久化查询，否则流量全部落到源站。请为每个请求记录操作名、规范化查询哈希和预估成本；这三个字段是限流与追查滥用所需的最低信息。

## 查询深度与复杂度限制

深度限制会拒绝嵌套层数超过固定值的文档。它实现成本低，能挡住递归 Schema 中被无限展开的 `comment { replies { comment { replies { ... } } } }`。但它并不充分。深度忽略宽度：一个深度只有三层、却包含上千个兄弟字段的操作依然很贵。深度也忽略列表乘法：`orders(first: 100) { items(first: 100) }` 仅两级就能返回一万行。

复杂度评分可以补上这两个缺口。为每个字段指定成本，把子节点成本乘以每个连接的分页大小，再汇总整个操作。评分必须使用变量值，因为 `first: $pageSize` 会把真实分页大小藏起来。片段、内联片段以及 `@include` 之类的指令都会改变实际执行形状，所以要在变量强制转换之后分析校验过的文档，而不是原始字符串。超过单操作预算的请求应返回 `QUERY_TOO_COMPLEX` 这类稳定错误码，并记录哈希、分值和已认证主体。预算要按真实数据库工作量校准，不要照抄博客里的整数。

| 控制项 | 限制对象 | 合理起点 | 拦截的攻击 |
| --- | --- | --- | --- |
| 深度 | 字段嵌套层数 | 10 到 15 层 | 递归评论、组织架构无限展开 |
| 复杂度 | 字段与连接的加权成本 | 按查询计划推导的单操作预算 | 宽选择集与嵌套分页乘法 |
| 别名上限 | 单操作中重复字段 | 100 到 300 个别名 | 针对昂贵解析器的别名炸弹 |
| 批量上限 | 每个 HTTP 请求的操作数 | 10 个以内 | 数组批量放大 |
| 分页上限 | 每个连接的行数 | 每页 100 行以内 | 无界的 `first: 10000` 读取 |
| 请求体上限 | 请求大小 | 几百 KB | 超大文档和变量载荷 |

```graphql
query AbuseExample {
  viewer {
    orders(first: 100) {
      nodes {
        items(first: 100) {
          product {
            reviews(first: 100) {
              author { orders(first: 100) { totalCount } }
            }
          }
        }
      }
    }
  }
}
```

上面的操作不到十层深，但连接参数相乘后行数估算达到六位数。深度限制设为 10 会放行。把分页大小计入的复杂度评分则不会。[GraphQL 格式化器](/tools/graphql-formatter)能让嵌套结构更易读，但评分必须来自校验后的抽象语法树，因为格式化不会改变服务器实际执行的内容。

## 分页上限与无界列表字段

每个列表字段都需要服务端强制最大值、默认值，以及客户端超限时可预测的拒绝方式。不能因为 Schema 接受整数，就让 `first: 10000` 直接打到数据库。上限应放在解析器或数据访问层，而不是文档或客户端代码里；超限时返回带稳定错误码的字段错误，不要悄悄截断：静默截断会让客户端缺陷不可见，也让分页逻辑更难写对。

嵌套连接会相乘。一页 50 个订单、每个订单 50 个条目就是 2,500 行，再加一层连接又会翻倍。复杂度公式必须体现这一点，Schema 也应要求大集合使用连接参数，而不是返回无界列表。大表优先用游标分页：偏移分页会让数据库扫描并丢弃所有被跳过的行，即使页大小很小，深页也很贵。`totalCount` 要单独计成本；带过滤的 join 计数可能比取页本身还贵，应缓存或从热路径移除。

## 批量、别名与请求放大

别名让一个操作用不同参数多次访问同一字段。`a0: user(id: 0)`、`a1: user(id: 1)` 这样排下去，一个 HTTP 请求就变成上千次解析器调用。这个操作语法合法、深度为一，只按字段数计一次的朴素复杂度评分会漏掉它。要按字段和按操作统计别名数量，设置硬上限，并在执行前拒绝超限文档。对查询文本做模式匹配不能作为强制手段：别名、片段、注释和空白都能绕过它。[正则表达式验证器](/tools/regex-tester)适合研究可疑载荷，但真正的限制必须落在解析后的文档上。

数组批量又加一层放大器：有些服务器接受一个 JSON 数组，在单次请求中执行多个操作，而每个元素本身还可能含别名。要限制批量大小，对多数客户端来说十个已经很宽裕，或者对不受信任的客户端直接关闭批量。在反向代理设置请求体大小上限、每个文档的片段数上限和变量载荷上限。批量中的每个操作都要解析、校验，并接受同样的深度、复杂度、别名和授权检查。不要让 `operationName` 只选中一个操作，却让其余操作绕开校验。

## 生产环境的内省、Schema 暴露与发现

内省是正当功能：客户端、代码生成器和 IDE 靠它发现类型。但在生产环境，它也是侦察工具：攻击者可以了解每个字段、参数、枚举值和弃用说明，再挑授权薄弱的字段下手。对公开生产端点关闭内省是合理的默认值，但它本身不是安全边界。Schema 细节还会通过错误消息、“你是不是想找”字段提示、GraphiQL 和 Apollo Sandbox 页面、Web 客户端里的 source map，以及打包进移动端的持久化查询清单泄露。

实际策略要分层。生产环境用校验规则关闭内省，在预发环境或管理员认证之后保留内省，并为可信工具发布生成的 Schema 文件。关闭错误格式化中的字段建议，移除开发者着陆页，检查错误文本是否暗示 Schema 结构。然后无论内省是否关闭，都强制执行深度、复杂度、别名限制和授权，因为关闭内省只是拖慢发现过程；它不能阻止客户端发送从别处学到的合法查询。

## 持久化查询与可信文档

持久化查询用哈希代替查询文本。在自动持久化查询流程中，客户端发送 SHA-256 哈希，服务器执行此前注册过的文档，或者要求客户端重新发送一次完整文本。这能节省带宽，但自动持久化查询本身只是缓存，不是白名单：如果服务器接受任何客户端提交的哈希到查询注册，攻击者就能先注册昂贵查询再调用它。可信文档是更强的模型。在构建阶段提取所有操作，发布哈希清单，并配置服务器只执行清单中存在的哈希。未知哈希返回稳定错误，绝不走动态注册路径。

这个模型还能让缓存和成本控制更安全。服务器知道哈希背后的确切文档，就能预先计算深度和复杂度、绑定固定成本，并让 GET 请求经过 CDN，缓存键包含哈希。清单版本要谨慎发布：先部署新清单，再发布使用它的客户端；重叠期内保留旧哈希；对已移除的哈希返回明确要求客户端刷新的错误。[JSON 格式化器](/tools/json-formatter)能让清单在代码评审中更容易比较差异，这一点很重要，因为清单被意外放宽就是一次安全变更。

## 按操作限流，而不是按 URL

限流要从身份开始。强制操作命名以便监控，对规范化后的文档做哈希，并按用户、IP、操作名和成本单位计数。登录、密码重置和支付变更应比可缓存的产品查询拥有更紧的预算。按主体使用令牌桶，再叠加按操作的并发上限，既能防持续滥用，也能防饿死其他客户端的突发流量。不要只依赖 IP：移动运营商和企业 NAT 会把成千上万的用户放在同一个地址后面。

返回标准信号：HTTP 层拒绝时返回 `429` 加 `Retry-After`；操作层拒绝时返回带稳定错误码和重试提示的 GraphQL 错误。技术栈支持草案头时，发布 `RateLimit-Limit`、`RateLimit-Remaining` 和 `RateLimit-Reset`。计数器放在 Redis 之类的共享存储中，确保跨实例仍然有效，并明确决定计数器存储不可用时，昂贵变更是失败关闭还是排队。使用可信文档时，成本在执行前已知，配额可以直接按复杂度单位计费，而不是按请求数。

## 字段级授权、输入校验与 Schema 边界

网关认证只能证明请求是谁发的，不能证明用户有权读取查询到达的每个节点。授权应放在解析器或服务层，靠近数据。加载记录时带上所有者条件，例如 `WHERE id = ? AND tenant_id = ?`，不要先取回再比较；解析器没有显式规则时应默认拒绝。要针对每个角色测试每个字段，包括通过用户合法拥有的父节点到达的嵌套字段，因为父节点授权通过不代表子节点也通过。

输入校验属于同一条边界。为邮箱、URL、UUID 和日期使用自定义标量，限制字符串长度和列表大小，校验数值范围，封闭集合只接受枚举。变量和字面量要用同一套规则校验。Schema 设计应暴露最小集合：不提供通用的 `executeSQL`，不把任意过滤字符串传进查询构造器，不使用容易被枚举的连续整数 ID，也不把管理员专用字段放进公开 Schema。内外部受众不同时应拆分 Schema，敏感字段应弃用而不是继续可达。

## N+1 查询、DataLoader 与安全的错误响应

逐个加载条目的列表解析器会把一个 GraphQL 字段变成数百次数据库查询。N+1 是性能缺陷，也会变成安全问题：攻击者可以选一个放大查询次数的页大小，在朴素复杂度预算之内耗尽连接池。DataLoader 会在同一个 tick 内合并键，并为本次请求缓存它们。每个请求创建新的 DataLoader，绝不能全局复用，并在批处理函数中逐条应用授权；忽略用户的请求级缓存可能泄露另一个租户的行。监控每个 GraphQL 操作的数据库查询次数，设置预算，在解析器模式退化时失败或告警。

错误处理需要同样的纪律。生产响应应携带稳定错误码、安全提示和请求 ID，而不是堆栈、SQL 片段、内部主机名或依赖版本。配置服务器的错误格式化器，把原始错误连同请求 ID 写入日志，只向客户端返回脱敏结构。区分校验错误和执行错误：前者是客户端的责任，后者是你的责任；错误响应绝不进入共享缓存。字段建议和内省错误也一样，它们都是 Schema 泄露。

## 验证清单与生产规则

要从外部验证，用攻击者会发的那类请求。先在预发环境按生产配置执行这些检查，之后每次 Schema 或网关变更，再对生产重复其中一部分。

```bash
# 1. 深层或别名密集查询：应在执行前被拒绝
curl -sS https://api.example.com/graphql \
  -H 'content-type: application/json' \
  --data-binary @abusive-query.json | jq '.errors[0].extensions.code'

# 2. 关闭内省后：应返回错误，而不是 Schema
curl -sS https://api.example.com/graphql \
  -H 'content-type: application/json' \
  --data-binary '{"query":"{ __schema { types { name } } }"}'

# 3. 未知持久化查询哈希：应返回稳定拒绝
curl -sS 'https://api.example.com/graphql?extensions=%7B%22persistedQuery%22%3A%7B%22version%22%3A1%2C%22sha256Hash%22%3A%22deadbeef%22%7D%7D'
```

然后重复与授权有关的检查：用 ID 请求另一个租户的节点，以普通用户身份请求管理员字段，确认响应是错误或 null，而不是数据。只有以下条件全部满足，才算通过：

| 检查项 | 验证方式 | 通过标准 |
| --- | --- | --- |
| 深度限制 | 发送比上限多一层的递归查询 | 返回 `QUERY_TOO_DEEP`，无部分数据，延迟在预算内 |
| 复杂度限制 | 用变量值把评分推过预算 | 返回 `QUERY_TOO_COMPLEX`；变量被计入，而不是被忽略 |
| 别名放大 | 对同一昂贵字段发送 500 个别名 | 执行前拒绝；上限按字段和按操作同时生效 |
| 分页上限 | 对每个连接请求 `first: 10000` | 返回字段错误或截断到上限，绝不产生无界数据库读取 |
| 批量大小 | 发送 100 个操作的数组 | 按文档化的最大批量拒绝 |
| 内省 | 匿名发送 `__schema` 和 `__type` 查询 | 两者都被拒绝；授权工具仍可获取 Schema |
| 持久化查询 | 先发未知哈希，再发已知哈希 | 未知哈希被拒绝；已知哈希按其预计算成本执行 |
| 操作限流 | 用便宜和昂贵操作分别超出预算 | 昂贵操作消耗更多预算；`429` 包含 `Retry-After` |
| 字段授权 | 请求他人节点和管理员字段 | 返回错误或 null；错误消息不泄露数据 |
| 错误信息控制 | 强制触发解析器异常 | 只返回稳定错误码和请求 ID；无堆栈、SQL 或主机名 |

可预测的错误包括：信任客户端查询白名单，移动应用或单页应用自带允许列表，但服务器仍然接受任何请求；只关闭内省，却没有深度、复杂度、别名和授权控制；返回堆栈和原始数据库错误，把 Schema 与查询形状直接交给攻击者；只做深度限制，放行别名炸弹和宽查询；按路径或原始请求数限流，让一个昂贵请求造成一千个请求的破坏；只从查询文本计算复杂度而不代入变量，低估 `first: $pageSize`。这些不是边缘情况，而是未防护 GraphQL 端点的默认行为。

生产规则很短。执行前解析和校验，结合变量为每个操作评分，限制深度、别名、批量大小、分页大小和请求体，并用稳定错误码拒绝。把授权放进解析器，采用默认拒绝的所有者检查；用明确的标量和上限校验每个输入；Schema 只暴露客户端真正需要的字段。客户端已知后改用可信文档，按操作和成本限流，逐请求批处理解析器，并对错误脱敏。最后从外部验证限制，把检查放进 CI 作为安全回归套件，并为每个请求记录操作哈希、成本、主体和结果。GraphQL 端点是否安全，取决于服务器而不是客户端来决定一次查询允许花多少成本。

## 常见问题

### 关闭内省就能让 GraphQL API 安全吗？

不能。关闭内省只会拖慢侦察，每个字段仍然可以被调用。错误消息、字段提示、客户端打包文件和公开 Schema 依然会泄露结构，因此深度、复杂度、别名、批量和授权限制必须继续生效。

### 为什么按 URL 对 GraphQL 限流不够？

所有操作都走同一条路径，基于 URL 的计数器无法区分便宜的查看查询和昂贵的嵌套变更。单个请求可以包含数百个别名或一批操作，每个操作消耗的数据库工作量可能完全不同。

### 持久化查询等同于客户端白名单吗？

不等同。客户端列表只说明客户端打算发什么，攻击者仍然可以发送任意内容。只有当服务端拒绝清单之外的所有哈希时，持久化查询才真正变成白名单。

### 只做深度限制能挡住昂贵的 GraphQL 查询吗？

不能。浅层查询可以包含数千个别名，也可以把 orders(first: 100) 和 items(first: 100) 这类嵌套连接层层相乘。深度必须与复杂度评分、别名上限、批量上限和服务端分页上限一起使用。

### 生产环境的 GraphQL 错误应该暴露什么？

只暴露稳定的错误码、安全的提示信息和请求 ID。堆栈、SQL 片段、内部主机名、依赖版本和字段建议应写入服务端日志，而不是出现在攻击者可以读取的响应里。

## 参考资料

- [GraphQL Specification](https://spec.graphql.org/October2021/)
- [OWASP: GraphQL Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html)
- [OWASP API Security Top 10](https://owasp.org/API-Security/editions/2023/en/0x11-t10/)
- [GraphQL.org: Security](https://graphql.org/learn/security/)

---

- Canonical: https://www.jsonmind.com/zh-CN/guides/graphql-query-security
- Locale: zh-CN
- Published: 2026-11-17
- Updated: 2026-11-17
- Tools: graphql-formatter, regex-tester, json-formatter