API 设计 / 系统课时

用操作签名治理热点查询

用操作签名治理热点查询

同一个 GraphQL 操作只因空格、注释或客户端格式化不同,就可能被日志系统拆成多条记录。本课把操作文档规范化并生成稳定签名,再按签名聚合频率、p95、错误率和总耗时,形成可行动的热点榜单。

学习目标

  • 理解操作签名为什么不能直接使用原始查询文本。
  • 用规范化文档和哈希生成稳定的操作标识。
  • 按签名汇总流量、延迟和错误,建立热点治理闭环。

为什么先做操作归一化

按原始 query 字符串聚合会受到空格、换行、逗号和注释影响;这些差异通常不改变操作含义,却会把同一查询拆成多个桶。更稳妥的做法是先移除 GraphQL 中可忽略字符,再对“操作名 + 规范化文档”做哈希。

变量值不应进入签名。$id 的每个实际值都属于同一个操作,否则高基数变量会让热点统计失去意义。反过来,如果客户端把动态值直接内联成字面量,例如 product(id: "123"),每个值都会生成不同签名,因此生产客户端应优先使用变量或持久化操作。

GraphQL 操作签名到热点榜单的数据流

生成签名并汇总热点

下面的 Node.js 主示例使用 GraphQL.js 的 stripIgnoredCharacters 规范化文档,再用 SHA-256 生成签名。两份 Product 查询只有空白与注释差异,因此会落到同一个签名;随后用一组请求样本生成热点榜单。

js
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 位十六进制前缀。

text
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 是否同步改善。签名不变意味着“同一个客户端操作”有稳定时间序列,这正是从一次性排障升级为长期性能治理的关键。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用操作签名治理热点查询

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通