API 设计 / 系统课时
使用可信操作白名单
使用可信操作白名单
可信操作白名单把 GraphQL 的执行入口从“客户端可提交任意文档”收紧为“只能引用已审核文档”。本课用 persisted operations 与 trusted documents 的共同机制,建立构建期清单、运行时门禁和可平滑升级的发布流程。
学习目标
- 区分自动持久化查询与真正具备安全边界的可信操作机制。
- 构建“操作文档 → 稳定 ID → 服务端清单 → 运行时查表执行”的门禁。
- 处理未知操作、版本错配和变量滥用,避免白名单被旁路。
先区分缓存优化和安全白名单
“persisted operation”只描述操作文档被预先或持续存储,并不自动等于安全白名单。某些 APQ 流程在服务端未命中哈希时,允许客户端补交完整文档并注册缓存,这能省带宽,却不能阻止新操作进入系统。
| 机制 | 未知 ID 时可提交新文档 | 能否作为执行白名单 |
|---|---|---|
| APQ 自动注册 | 通常可以,取决于实现 | 否 |
| 预注册 persisted operation | 不可以 | 可以 |
| trusted documents | 不可以 | 可以 |
安全边界的关键规则只有一句:生产执行入口遇到未知 ID 必须拒绝,不能回退到任意 query 文本执行。 操作名也不能代替 ID,因为不同文档可以使用相同 operation name。
建立构建期清单和运行时门禁
推荐在 CI 中提取客户端操作,完成代码评审与安全检查后生成 manifest。服务端先发布这份 manifest,客户端再发布只携带操作 ID 与 variables 的版本。运行时先查表,命中后才把服务端保存的原始文档交给 GraphQL 执行器。

哈希型 ID 必须基于构建产物中约定的精确文档字节或统一规范化结果生成,客户端和服务端算法也必须一致。另一种更直接的做法是由构建系统分配不可变 ID;ID 是否可猜并不重要,因为它不是秘密,真正的授权仍由身份与字段级规则负责。
可运行的白名单门禁
下面示例依赖 Node.js 20+ 与 graphql 16.x。为了把重点放在门禁上,服务端只预注册一个 Viewer 操作;客户端提交完整 GraphQL 文本或未知 ID 都会被拒绝。
import { createHash } from "node:crypto";
import { buildSchema, graphql } from "graphql";
const schema = buildSchema(`
type User {
id: ID!
name: String!
}
type Query {
viewer: User!
}
`);
const rootValue = {
viewer: () => ({ id: "u-1", name: "Ada" })
};
const trustedSources = [
`query Viewer {
viewer {
id
name
}
}`
];
// 构建端与服务端必须对同一份文档使用完全一致的 ID 算法。
function documentId(source) {
return createHash("sha256").update(source).digest("hex");
}
// 生产环境通常从经过审核、带版本的 manifest 加载这张表。
const manifest = new Map(
trustedSources.map((source) => [documentId(source), source])
);
async function handleRequest(body) {
// 不接受“没有可信 ID、只有 query 文本”的回退路径。
if (typeof body.id !== "string") {
return {
status: 403,
body: { errors: [{ message: "TRUSTED_DOCUMENT_REQUIRED" }] }
};
}
const source = manifest.get(body.id);
// 未知 ID 必须在执行器之前被拒绝,不能自动注册客户端文档。
if (!source) {
return {
status: 403,
body: { errors: [{ message: "TRUSTED_DOCUMENT_REQUIRED" }] }
};
}
const result = await graphql({
schema,
source,
rootValue,
variableValues: body.variables ?? {}
});
return {
status: result.errors ? 400 : 200,
body: result
};
}
const allowedId = documentId(trustedSources[0]);
console.log(JSON.stringify(
await handleRequest({ id: allowedId, variables: {} })
));
console.log(JSON.stringify(
await handleRequest({ id: "deadbeef", variables: {} })
));
console.log(JSON.stringify(
await handleRequest({ query: trustedSources[0], variables: {} })
));预期输出:
{"status":200,"body":{"data":{"viewer":{"id":"u-1","name":"Ada"}}}}
{"status":403,"body":{"errors":[{"message":"TRUSTED_DOCUMENT_REQUIRED"}]}}
{"status":403,"body":{"errors":[{"message":"TRUSTED_DOCUMENT_REQUIRED"}]}}示例使用 403 表达“生产门禁不允许该文档”;实际系统也可以按网关约定选择其他 4xx 状态,但必须保证未知操作不会继续进入 GraphQL 解析与执行阶段。
防止白名单被旁路
白名单只限制“能执行哪份文档”,不能替代认证、授权和变量校验。一个被批准的列表查询如果允许客户端把 first 传到极大值,仍可能制造高成本操作,因此变量范围、分页上限和上一课的成本保护仍然需要保留。
还要检查是否存在第二入口,例如调试路由、旧版 /graphql、WebSocket 订阅端点或批处理端点。如果其中任何一个仍接受任意文档,主入口的 trusted documents 就不再构成完整边界。对开发环境开放任意查询时,也应使用独立配置而不是在生产代码中“未命中就回退”。
处理版本错配和回滚
服务端 manifest 与客户端版本必须按兼容顺序发布。Web 客户端通常可以先让服务端同时接受版本 N 与 N-1 的 ID,再发布 N 客户端,观察旧版本流量归零后删除 N-1;移动端升级更慢,保留窗口通常更长。
发布验证至少覆盖三类请求:当前版本合法 ID 应成功,未知 ID 应被拒绝,只有 query 文本而没有可信 ID 的请求也应被拒绝。这样才能证明白名单是执行前的硬门禁,而不是一个可以被自动注册、旧路由或回退逻辑绕开的缓存层。