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 或厂商文档检查内容,列出主要来源,并在行为变化时更新指南。
每篇指南末尾都列出了主要来源。