API 设计 / 系统课时

定义 GraphQL 性能基线

定义 GraphQL 性能基线

性能优化前先把“当前有多快、在什么负载下变慢”量化。本课建立固定压测条件,记录请求速率、GraphQL 错误率、P50/P95/P99 延迟,并把慢请求继续下钻到 Resolver 字段耗时。

学习目标

  • 用固定场景定义可重复的 GraphQL 性能基线。
  • 正确区分吞吐、错误率和 P50/P95/P99 延迟。
  • 采集 Resolver 耗时,定位尾延迟由哪些字段贡献。

先固定基线条件

基线不是某次请求的耗时,而是一组可复现的实验条件加统计分布。至少固定服务版本、数据集规模、实例规格、请求并发、操作组合、缓存状态和测试时长;冷缓存与热缓存应分开记录,否则相同版本也无法公平比较。

GraphQL 还要额外固定操作文档和变量分布。一个只查询 id 的轻量请求,不能代表包含多级列表、远程调用或批量加载的真实流量。建议按实际业务占比建立 2~5 个代表性 operation,再汇总整体和分 operation 指标。

GraphQL 性能基线从固定负载到请求与 Resolver 指标的数据链路

先定义指标口径

请求速率用单位时间内完成的 GraphQL 请求数表示;错误率应同时识别 HTTP 失败和 GraphQL errors,因为 Resolver 出错时 HTTP 状态仍可能是 200。延迟至少保留 P50、P95、P99:P50 表示典型体验,P95/P99 更容易暴露排队、慢依赖和少量高成本查询。

Resolver 耗时要按固定的 Schema 字段维度聚合,例如 Query.product。不要把用户 ID、原始变量或完整查询文本做成指标标签,否则会制造高基数,既拖慢指标系统,也让不同时间窗口难以比较。

在 Apollo Server 采集请求与 Resolver 耗时

下面示例要求 Node.js 20+、Apollo Server 5、GraphQL 16.11+、Express 5、@as-integrations/express5,并额外安装 prom-client。请求层记录成功与错误两个 outcome,Resolver 层只使用 parent_type 和 field 两个稳定标签,因此后续可以在 Prometheus 中聚合多实例并计算分位数。

js
import http from 'node:http';
import express from 'express';
import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@as-integrations/express5';
import {
  Counter,
  Histogram,
  Registry,
} from 'prom-client';

const register = new Registry();

const requests = new Counter({
  name: 'graphql_requests_total',
  help: 'Completed GraphQL requests',
  labelNames: ['outcome'],
  registers: [register],
});

const requestDuration = new Histogram({
  name: 'graphql_request_duration_seconds',
  help: 'GraphQL request duration in seconds',
  labelNames: ['outcome'],
  buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
  registers: [register],
});

const resolverDuration = new Histogram({
  name: 'graphql_resolver_duration_seconds',
  help: 'GraphQL resolver duration in seconds',
  labelNames: ['parent_type', 'field'],
  buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1],
  registers: [register],
});

const metricsPlugin = {
  async requestDidStart() {
    const started = process.hrtime.bigint();
    let outcome = 'ok';

    return {
      async didEncounterErrors() {
        outcome = 'error';
      },
      async executionDidStart() {
        return {
          willResolveField({ info }) {
            const stop = resolverDuration.startTimer({
              parent_type: info.parentType.name,
              field: info.fieldName,
            });
            return () => stop();
          },
        };
      },
      async willSendResponse() {
        const seconds =
          Number(process.hrtime.bigint() - started) / 1_000_000_000;
        requests.inc({ outcome });
        requestDuration.observe({ outcome }, seconds);
      },
    };
  },
};

const typeDefs = `#graphql
  type Product { id: ID!, name: String!, price: Float! }
  type Query { product(id: ID!): Product }
`;

const products = new Map([
  ['1', { id: '1', name: 'Keyboard', price: 99 }],
]);

const resolvers = {
  Query: {
    product: async (_, { id }) => {
      await new Promise((resolve) => setTimeout(resolve, 20));
      return products.get(id) ?? null;
    },
  },
};

const app = express();
const httpServer = http.createServer(app);
const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [metricsPlugin],
});

await server.start();

app.get('/metrics', async (_, res) => {
  res.set('Content-Type', register.contentType);
  res.end(await register.metrics());
});

app.use('/graphql', express.json(), expressMiddleware(server));

await new Promise((resolve) => httpServer.listen({ port: 4000 }, resolve));
console.log('GraphQL ready at http://localhost:4000/graphql');

预期结果:保存为 server.mjs 并安装示例依赖后,服务会在 /graphql 提供查询,在 /metrics 暴露请求计数、请求耗时直方图和 Resolver 耗时直方图。该插件统计的是已进入 Apollo 请求生命周期的请求;若 SLO 还包含反向代理拒绝、Body 解析失败等 HTTP 级错误,应在网关或 Express 层补充入口指标。

bash
node server.mjs

预期输出

text
GraphQL ready at http://localhost:4000/graphql

用固定并发生成一份基线样本

下面的 Node.js 20+ 压测脚本只依赖内置 fetch。它固定 10 个并发 worker,每个发送 50 次相同 operation,并把 HTTP 失败或 GraphQL errors 都计为错误。

js
const url = process.env.URL ?? 'http://localhost:4000/graphql';
const concurrency = 10;
const requestsPerWorker = 50;
const latencies = [];
let errors = 0;

async function worker() {
  for (let i = 0; i < requestsPerWorker; i += 1) {
    const started = performance.now();
    const response = await fetch(url, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        query: 'query Baseline { product(id: "1") { id name price } }',
      }),
    });
    const body = await response.json();
    latencies.push(performance.now() - started);

    if (!response.ok || body.errors?.length) {
      errors += 1;
    }
  }
}

const started = performance.now();
await Promise.all(Array.from({ length: concurrency }, () => worker()));
const seconds = (performance.now() - started) / 1000;

latencies.sort((a, b) => a - b);
const percentile = (p) =>
  latencies[Math.min(
    latencies.length - 1,
    Math.ceil(latencies.length * p) - 1,
  )];

console.log(JSON.stringify({
  requests: latencies.length,
  rps: latencies.length / seconds,
  errorRate: errors / latencies.length,
  p50Ms: percentile(0.50),
  p95Ms: percentile(0.95),
  p99Ms: percentile(0.99),
}, null, 2));

预期输出

text
{
  "requests": 500,
  "rps": <VALUE>,
  "errorRate": 0,
  "p50Ms": <VALUE>,
  "p95Ms": <VALUE>,
  "p99Ms": <VALUE>
}

<VALUE> 取决于机器、Node.js 版本和当时系统负载。真实基线应把运行时间拉长,并先完成预热,再至少重复多轮,记录中位轮次而不是挑最好的一次。

用指标系统复核尾延迟来源

客户端压测能看到端到端体验,但不能解释慢在哪里。Prometheus 抓取 /metrics 后,可以用以下查询同时得到吞吐、错误率、请求分位数和最慢 Resolver 的 P95。

promql
sum(rate(graphql_requests_total[5m]))

sum(rate(graphql_requests_total{outcome="error"}[5m]))
/
sum(rate(graphql_requests_total[5m]))

histogram_quantile(
  0.50,
  sum by (le) (rate(graphql_request_duration_seconds_bucket[5m]))
)

histogram_quantile(
  0.95,
  sum by (le) (rate(graphql_request_duration_seconds_bucket[5m]))
)

histogram_quantile(
  0.99,
  sum by (le) (rate(graphql_request_duration_seconds_bucket[5m]))
)

histogram_quantile(
  0.95,
  sum by (le, parent_type, field) (
    rate(graphql_resolver_duration_seconds_bucket[5m])
  )
)

预期结果:前五个查询依次得到 RPS、错误率、P50、P95、P99;最后一个查询按 parent_type 与 field 返回各 Resolver 的 P95。实际数值均为 <VALUE>,应与同一版本、同一负载条件下保存的 baseline snapshot 比较。

当 P95/P99 明显恶化而 RPS、错误率和实验条件保持稳定时,再从高耗时 Resolver 向数据库、远程服务、DataLoader 批处理和缓存命中率继续下钻。这样性能优化才是在对比同一把尺子,而不是凭单次请求体感判断。

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

目录与阅读设置

阅读设置

17

记录一个想法

定义 GraphQL 性能基线

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

登录哪都通