JsonMind
API 与接口12 分钟阅读更新于 2026年11月17日

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

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

JM作者:JsonMind Engineering最后复核: 2026年11月17日依据权威规范与引用来源复核。
快速答案

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超大文档和变量载荷
query AbuseExample {
  viewer {
    orders(first: 100) {
      nodes {
        items(first: 100) {
          product {
            reviews(first: 100) {
              author { orders(first: 100) { totalCount } }
            }
          }
        }
      }
    }
  }
}

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

分页上限与无界列表字段

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

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

批量、别名与请求放大

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

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

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

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

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

持久化查询与可信文档

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

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

按操作限流,而不是按 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 或网关变更,再对生产重复其中一部分。

# 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 片段、内部主机名、依赖版本和字段建议应写入服务端日志,而不是出现在攻击者可以读取的响应里。

依据权威规范与引用来源复核。

JsonMind 指南由工程团队撰写和复核。我们会对照相关 RFC 或厂商文档检查内容,列出主要来源,并在行为变化时更新指南。

每篇指南末尾都列出了主要来源。

参考资料

把指南用起来

浏览全部工具

打开浏览器工具。输入内容保留在浏览器中,不会上传到业务服务器。

相关指南

全部指南