《互联网产品的客户端架构·规模化与架构演进》4.1 性能预算与分端指标

// file: src/perf/perf-budget.ts
// tier: L1
// verify: node --test test/perf/perf-budget.test.ts

export type Endpoint = "web" | "ios" | "android" | "miniprogram" | "desktop";

export type Metric = "startup" | "first-screen" | "interaction" | "memory";

export type Unit = "ms" | "MB";

export type Budget = {
  target: number;
  hard: number;
};

export type BudgetTable = Record<Endpoint, Record<Metric, Budget>>;

export type Measurement = Partial<Record<Metric, number>>;

export const ENDPOINTS: Endpoint[] = ["web", "ios", "android", "miniprogram", "desktop"];

export const METRICS: Metric[] = ["startup", "first-screen", "interaction", "memory"];

export const UNITS: Record<Metric, Unit> = {
  startup: "ms",
  "first-screen": "ms",
  interaction: "ms",
  memory: "MB",
};

export const BUDGETS: BudgetTable = {
  web: {
    startup: { target: 900, hard: 1500 },
    "first-screen": { target: 1200, hard: 2000 },
    interaction: { target: 150, hard: 300 },
    memory: { target: 120, hard: 200 },
  },
  ios: {
    startup: { target: 700, hard: 1200 },
    "first-screen": { target: 900, hard: 1500 },
    interaction: { target: 100, hard: 200 },
    memory: { target: 180, hard: 300 },
  },
  android: {
    startup: { target: 900, hard: 1600 },
    "first-screen": { target: 1100, hard: 1900 },
    interaction: { target: 120, hard: 240 },
    memory: { target: 220, hard: 360 },
  },
  miniprogram: {
    startup: { target: 1100, hard: 1900 },
    "first-screen": { target: 1500, hard: 2500 },
    interaction: { target: 180, hard: 320 },
    memory: { target: 150, hard: 260 },
  },
  desktop: {
    startup: { target: 1400, hard: 2400 },
    "first-screen": { target: 1000, hard: 1800 },
    interaction: { target: 100, hard: 180 },
    memory: { target: 300, hard: 500 },
  },
};

export const BASELINES: Record<Endpoint, Record<Metric, number>> = {
  web: { startup: 820, "first-screen": 1000, interaction: 120, memory: 95 },
  ios: { startup: 640, "first-screen": 780, interaction: 88, memory: 160 },
  android: { startup: 830, "first-screen": 980, interaction: 105, memory: 200 },
  miniprogram: { startup: 1020, "first-screen": 1340, interaction: 160, memory: 135 },
  desktop: { startup: 1260, "first-screen": 900, interaction: 86, memory: 270 },
};

export type BudgetIssue = {
  path: string;
  message: string;
};

export function budgetFor(endpoint: Endpoint, metric: Metric, table: BudgetTable = BUDGETS): Budget | undefined {
  return table[endpoint]?.[metric];
}

export function validateBudgetTable(table: BudgetTable): BudgetIssue[] {
  const issues: BudgetIssue[] = [];
  for (const endpoint of ENDPOINTS) {
    const row = table[endpoint];
    if (!row) {
      issues.push({ path: endpoint, message: "缺少该端的预算行" });
      continue;
    }
    for (const metric of METRICS) {
      const budget = row[metric];
      const path = `${endpoint}/${metric}`;
      if (!budget) {
        issues.push({ path, message: "缺少该指标的预算" });
        continue;
      }
      if (!Number.isFinite(budget.target) || budget.target <= 0) {
        issues.push({ path, message: "软预算必须是正数" });
      }
      if (!Number.isFinite(budget.hard) || budget.hard <= 0) {
        issues.push({ path, message: "硬上限必须是正数" });
      }
      if (Number.isFinite(budget.target) && Number.isFinite(budget.hard) && budget.target > budget.hard) {
        issues.push({ path, message: "软预算不能高于硬上限" });
      }
    }
  }
  return issues;
}

export type Overrun = {
  endpoint: Endpoint;
  metric: Metric;
  unit: Unit;
  value: number;
  target: number;
  hard: number;
  excess: number;
  ratio: number;
  severity: "warn" | "fail";
};

export function overruns(
  endpoint: Endpoint,
  measurement: Measurement,
  table: BudgetTable = BUDGETS,
): Overrun[] {
  const out: Overrun[] = [];
  for (const metric of METRICS) {
    const value = measurement[metric];
    if (value === undefined) continue;
    const budget = budgetFor(endpoint, metric, table);
    if (!budget) continue;
    if (value <= budget.target) continue;
    out.push({
      endpoint,
      metric,
      unit: UNITS[metric],
      value,
      target: budget.target,
      hard: budget.hard,
      excess: value - budget.target,
      ratio: value / budget.target,
      severity: value > budget.hard ? "fail" : "warn",
    });
  }
  return out;
}

export function rankOverruns(items: Overrun[]): Overrun[] {
  return [...items].sort((a, b) => {
    if (b.ratio !== a.ratio) return b.ratio - a.ratio;
    if (a.severity !== b.severity) return a.severity === "fail" ? -1 : 1;
    return a.metric.localeCompare(b.metric);
  });
}

export function evaluateBudget(
  endpoint: Endpoint,
  measurement: Measurement,
  table: BudgetTable = BUDGETS,
): { endpoint: Endpoint; pass: boolean; overruns: Overrun[]; missing: Metric[] } {
  const items = rankOverruns(overruns(endpoint, measurement, table));
  return {
    endpoint,
    pass: items.every((item) => item.severity !== "fail"),
    overruns: items,
    missing: METRICS.filter((metric) => measurement[metric] === undefined),
  };
}

export function baselineFor(endpoint: Endpoint): Record<Metric, number> | undefined {
  return BASELINES[endpoint];
}

export type BaselineDrift = {
  metric: Metric;
  baseline: number;
  value: number;
  changePct: number;
};

export function driftFromBaseline(endpoint: Endpoint, measurement: Measurement): BaselineDrift[] {
  const baseline = baselineFor(endpoint);
  if (!baseline) return [];
  const out: BaselineDrift[] = [];
  for (const metric of METRICS) {
    const value = measurement[metric];
    if (value === undefined) continue;
    const base = baseline[metric];
    out.push({
      metric,
      baseline: base,
      value,
      changePct: ((value - base) / base) * 100,
    });
  }
  return out;
}

export function worstMetric(endpoint: Endpoint, measurement: Measurement): Metric | undefined {
  let worst: Metric | undefined;
  let worstRatio = 0;
  for (const metric of METRICS) {
    const value = measurement[metric];
    const budget = budgetFor(endpoint, metric);
    if (value === undefined || !budget) continue;
    const ratio = value / budget.target;
    if (ratio > worstRatio) {
      worstRatio = ratio;
      worst = metric;
    }
  }
  return worst;
}

export function softPassRate(endpoint: Endpoint, measurement: Measurement): number {
  const measured = METRICS.filter((metric) => measurement[metric] !== undefined);
  if (measured.length === 0) return 1;
  const passed = measured.filter((metric) => {
    const value = measurement[metric] as number;
    const budget = budgetFor(endpoint, metric);
    return budget !== undefined && value <= budget.target;
  });
  return passed.length / measured.length;
}

export function budgetCoverage(table: BudgetTable = BUDGETS): number {
  let count = 0;
  for (const endpoint of ENDPOINTS) {
    for (const metric of METRICS) {
      if (table[endpoint]?.[metric]) count += 1;
    }
  }
  return count;
}

export function formatOverrun(item: Overrun): string {
  const level = item.severity === "fail" ? "超硬上限" : "超软预算";
  return `${item.endpoint}/${item.metric} ${item.value}${item.unit} ${level} ${item.hard}${item.unit}（${item.ratio.toFixed(2)}×）`;
}

✔ 默认预算表覆盖全部端与指标
✔ 软预算高于硬上限被报错
✔ 超过软预算但未过硬上限只告警
✔ 超过硬上限判为失败
✔ 超限明细按超出比例降序排列
✔ 基线漂移按指标计算百分比
ℹ tests 21
ℹ pass 21
ℹ fail 0