《互联网产品的客户端架构·端形态与体验基础》3.1 首屏、可交互与流畅度

// file: src/quality/percentiles.ts
// tier: L1
// verify: node --test test/quality/percentiles.test.ts

export type MetricName = "FP" | "FCP" | "LCP" | "INP" | "TBT";

export interface MetricSample {
  metric: MetricName;
  value: number;
}

export interface MetricSummary {
  metric: MetricName;
  count: number;
  min: number;
  max: number;
  mean: number;
  p50: number;
  p75: number;
  p95: number;
}

export interface BudgetRule {
  p75: number;
  p95: number;
}

export interface BudgetVerdict {
  metric: MetricName;
  status: "pass" | "warn" | "fail";
  reasons: string[];
}

export interface TimedSample {
  metric: MetricName;
  value: number;
  atMs: number;
}

export interface Sampler {
  record(value: number): TimedSample;
  values(): number[];
  summary(): MetricSummary;
  reset(): void;
}

/**
 * 最近秩（nearest-rank）分位数：返回排序后第 ceil(p * n) 个样本。
 * 对延迟指标，最近秩不会像线性插值那样凭空造出一个更小的中间值。
 */
export function percentile(samples: readonly number[], p: number): number {
  if (samples.length === 0) {
    throw new Error("percentile: samples 不能为空");
  }
  if (!(p > 0 && p <= 1)) {
    throw new Error(`percentile: p 必须在 (0, 1] 内，收到 ${p}`);
  }
  const sorted = [...samples].sort((a, b) => a - b);
  const rank = Math.max(1, Math.ceil(p * sorted.length));
  return sorted[rank - 1];
}

/** 把一组同指标样本压缩成均值与常用分位；均值只作参考，不参与预算判定。 */
export function summarizeMetric(
  metric: MetricName,
  values: readonly number[],
): MetricSummary {
  if (values.length === 0) {
    throw new Error(`summarizeMetric: ${metric} 没有样本`);
  }
  const total = values.reduce((sum, value) => sum + value, 0);
  return {
    metric,
    count: values.length,
    min: Math.min(...values),
    max: Math.max(...values),
    mean: total / values.length,
    p50: percentile(values, 0.5),
    p75: percentile(values, 0.75),
    p95: percentile(values, 0.95),
  };
}

/**
 * p75 是预警线，p95 是失败线。
 * 平均值被极少数超长任务拉高时，只记录一条说明，不改变判定。
 */
export function judgeBudget(
  summary: MetricSummary,
  rule: BudgetRule,
): BudgetVerdict {
  const reasons: string[] = [];
  const p75Over = summary.p75 > rule.p75;
  const p95Over = summary.p95 > rule.p95;

  if (p95Over) {
    reasons.push(
      `${summary.metric} p95 ${summary.p95.toFixed(1)}ms 超过失败线 ${rule.p95}ms`,
    );
  }
  if (p75Over) {
    reasons.push(
      `${summary.metric} p75 ${summary.p75.toFixed(1)}ms 超过预警线 ${rule.p75}ms`,
    );
  }
  if (summary.mean > rule.p95 && !p95Over) {
    reasons.push(
      `${summary.metric} 平均值 ${summary.mean.toFixed(1)}ms 高于失败线，但 p95 未超标，按分位口径不判失败`,
    );
  }

  const status = p95Over ? "fail" : p75Over ? "warn" : "pass";
  return { metric: summary.metric, status, reasons };
}

/**
 * 采样器把“何时记录”交给注入的时钟，测试里因此不需要真实定时器。
 * 生产代码可以把 clock 换成 performance.now，测试里换成手动推进的假时钟。
 */
export function createSampler(
  metric: MetricName,
  clock: () => number,
): Sampler {
  const samples: TimedSample[] = [];

  return {
    record(value: number): TimedSample {
      if (!Number.isFinite(value) || value < 0) {
        throw new Error(`sampler: ${metric} 样本必须是非负有限数，收到 ${value}`);
      }
      const sample: TimedSample = { metric, value, atMs: clock() };
      samples.push(sample);
      return sample;
    },
    values(): number[] {
      return samples.map((sample) => sample.value);
    },
    summary(): MetricSummary {
      return summarizeMetric(metric, samples.map((sample) => sample.value));
    },
    reset(): void {
      samples.length = 0;
    },
  };
}

node --test test/quality/percentiles.test.ts

✔ 最近秩分位返回排序后第 ceil(p*n) 个样本 (0.474625ms)
✔ 空样本与非法分位会直接抛错 (0.236ms)
✔ 汇总同时给出均值与分位 (0.094209ms)
✔ p75 超线判预警，p95 超线判失败 (0.154458ms)
✔ 均值被极端样本拉高时，只要分位达标仍判通过 (0.65775ms)
✔ 采样器使用注入时钟，并可重置 (0.626541ms)
✔ 采样器拒绝负数与非有限值 (0.116666ms)
ℹ tests 7
ℹ suites 0
ℹ pass 7
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 155.804708