API 设计 / 系统课时
用操作签名治理热点查询
用操作签名治理热点查询
同一个 GraphQL 操作只因空格、注释或客户端格式化不同,就可能被日志系统拆成多条记录。本课把操作文档规范化并生成稳定签名,再按签名聚合频率、p95、错误率和总耗时,形成可行动的热点榜单。
学习目标
- 理解操作签名为什么不能直接使用原始查询文本。
- 用规范化文档和哈希生成稳定的操作标识。
- 按签名汇总流量、延迟和错误,建立热点治理闭环。
为什么先做操作归一化
按原始 query 字符串聚合会受到空格、换行、逗号和注释影响;这些差异通常不改变操作含义,却会把同一查询拆成多个桶。更稳妥的做法是先移除 GraphQL 中可忽略字符,再对“操作名 + 规范化文档”做哈希。
变量值不应进入签名。$id 的每个实际值都属于同一个操作,否则高基数变量会让热点统计失去意义。反过来,如果客户端把动态值直接内联成字面量,例如 product(id: "123"),每个值都会生成不同签名,因此生产客户端应优先使用变量或持久化操作。

生成签名并汇总热点
下面的 Node.js 主示例使用 GraphQL.js 的 stripIgnoredCharacters 规范化文档,再用 SHA-256 生成签名。两份 Product 查询只有空白与注释差异,因此会落到同一个签名;随后用一组请求样本生成热点榜单。
const { stripIgnoredCharacters } = require('graphql');
const { createHash } = require('node:crypto');
function operationSignature(source, operationName) {
const normalized = stripIgnoredCharacters(source);
const material = `${operationName ?? ''}:${normalized}`;
return createHash('sha256')
.update(material)
.digest('hex');
}
function p95(values) {
const sorted = [...values].sort((a, b) => a - b);
const index = Math.ceil(sorted.length * 0.95) - 1;
return sorted[Math.max(index, 0)];
}
const productA = `
query Product($id: ID!) {
product(id: $id) { id name price }
}
`;
const productB = `
# same operation, different formatting
query Product($id: ID!){product(id:$id){id name price}}
`;
const search = `
query Search($q: String!) {
search(q: $q) { id }
}
`;
const samples = [
{ source: productA, operationName: 'Product', durationMs: 120, error: false },
{ source: productB, operationName: 'Product', durationMs: 280, error: false },
{ source: productA, operationName: 'Product', durationMs: 420, error: true },
{ source: search, operationName: 'Search', durationMs: 80, error: false },
];
const groups = new Map();
for (const sample of samples) {
const signature = operationSignature(sample.source, sample.operationName);
const key = `${sample.operationName}:${signature}`;
const row = groups.get(key) ?? {
operationName: sample.operationName,
signature,
count: 0,
errorCount: 0,
totalDurationMs: 0,
durations: [],
};
row.count += 1;
row.errorCount += sample.error ? 1 : 0;
row.totalDurationMs += sample.durationMs;
row.durations.push(sample.durationMs);
groups.set(key, row);
}
const leaderboard = [...groups.values()]
.map((row) => ({
...row,
p95Ms: p95(row.durations),
errorRate: (row.errorCount / row.count) * 100,
}))
.sort((a, b) => b.totalDurationMs - a.totalDurationMs);
console.log(
`sameSignature=${operationSignature(productA, 'Product') === operationSignature(productB, 'Product')}`
);
for (const row of leaderboard) {
console.log(
`${row.operationName} signature=${row.signature.slice(0, 12)} ` +
`count=${row.count} p95=${row.p95Ms}ms ` +
`errorRate=${row.errorRate.toFixed(1)}% total=${row.totalDurationMs}ms`
);
}预期输出。签名是哈希标识,下面用 <ID> 代替实际 12 位十六进制前缀。
sameSignature=true
Product signature=<ID> count=3 p95=420ms errorRate=33.3% total=820ms
Search signature=<ID> count=1 p95=80ms errorRate=0.0% total=80ms这个示例按总耗时排序,适合先找“占用最多请求时间”的操作,但它不是 CPU 成本的精确估计,因为等待数据库或 HTTP 也会计入请求时长。生产榜单应保留多个独立维度,而不是压成一个看似精确的魔法分数。
榜单要同时看频率、延迟和错误
| 指标 | 说明 | 典型行动 |
|---|---|---|
count |
操作调用频率 | 高频但很快的操作优先检查缓存命中率、响应体大小与重复读取 |
p95 |
尾部延迟 | 结合 Resolver trace 找慢字段、串行等待和慢上游 |
errorRate |
错误请求占比 | 按错误码或异常类别继续拆分,避免热点只是失败重试造成 |
totalDurationMs |
样本请求时长总和 | 用于粗排整体负担,再结合 CPU、DB 时间等资源指标确认 |
榜单至少保留 operationName、签名、请求数、p95 和错误率,并能下钻到该签名最慢的 Resolver。这样才能区分“很多但便宜”“很少但极慢”和“高频且持续报错”三种完全不同的治理对象。
明确签名边界
最简单的生产约束是每个请求只发送一个具名操作。若允许一个文档包含多个 operation,签名键至少要带上实际执行的 operationName;更严格的实现会只抽取被执行的 operation 及其可达 fragments 后再规范化,避免未执行定义改变签名。
stripIgnoredCharacters 只消除可忽略字符,不会重排字段、参数或 fragment。不要为了“更像同一个查询”而自行排序 AST:字段顺序、别名和选择集差异可能反映真实客户端契约,过度归一化会把应该分开的操作合并。
用同一签名完成治理闭环
热点榜单产生后,先按类型处置:高频查询优先看请求级缓存、DataLoader 和响应缓存;高 p95 查询回到 Resolver 追踪找关键路径;错误率高的操作先排除重试风暴、参数契约和上游失败;异常复杂或成本过高的操作再考虑深度、复杂度或持久化操作限制。
修复发布后继续用同一签名比较前后窗口,观察请求数、p95、错误率和热点 Resolver 是否同步改善。签名不变意味着“同一个客户端操作”有稳定时间序列,这正是从一次性排障升级为长期性能治理的关键。