《互联网产品的客户端架构·端形态与体验基础》3.2 包体与内存预算

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

export type AssetKind = "entry" | "route" | "image" | "font";

export interface AssetRecord {
  path: string;
  kind: AssetKind;
  bytes: number;
  /** route 类型必填：该资源属于哪个路由包 */
  route?: string;
}

export interface SizePolicy {
  entry: number;
  route: number;
  image: number;
  font: number;
  total: number;
}

export interface BudgetIssue {
  code: "asset-over" | "route-over" | "total-over";
  target: string;
  actual: number;
  limit: number;
}

export interface BundleReport {
  totals: Record<AssetKind, number>;
  totalBytes: number;
  routes: Record<string, number>;
  issues: BudgetIssue[];
  status: "pass" | "fail";
}

export interface MemorySample {
  atMs: number;
  heapMb: number;
}

export interface MemoryPolicy {
  peakMb: number;
  growthMbPerMinute: number;
}

export interface MemoryVerdict {
  peakMb: number;
  growthMbPerMinute: number;
  status: "pass" | "fail";
  reasons: string[];
}

export interface MemorySampler {
  sample(heapMb: number): MemorySample;
  samples(): readonly MemorySample[];
}

/**
 * 体积预算检查器只吃已经解析好的资产清单，不读文件系统。
 * 这样 CI 里的文件扫描、gzip/brotli 测量都可以在外面做，
 * 预算规则本身可以在普通单元测试里被完整覆盖。
 */
export function checkBundleBudget(
  assets: readonly AssetRecord[],
  policy: SizePolicy,
): BundleReport {
  const totals: Record<AssetKind, number> = {
    entry: 0,
    route: 0,
    image: 0,
    font: 0,
  };
  const routes: Record<string, number> = {};
  const issues: BudgetIssue[] = [];

  for (const asset of assets) {
    if (!Number.isInteger(asset.bytes) || asset.bytes < 0) {
      throw new Error(`资产 ${asset.path} 的 bytes 必须是非负整数`);
    }
    totals[asset.kind] += asset.bytes;
    if (asset.kind === "route") {
      if (!asset.route) {
        throw new Error(`路由资产 ${asset.path} 缺少 route`);
      }
      routes[asset.route] = (routes[asset.route] ?? 0) + asset.bytes;
    }
  }

  for (const kind of Object.keys(totals) as AssetKind[]) {
    if (kind === "route") {
      // route 预算按单个路由包比对，聚合总量由 total 兜底，避免同一超限报两次。
      continue;
    }
    if (totals[kind] > policy[kind]) {
      issues.push({
        code: "asset-over",
        target: kind,
        actual: totals[kind],
        limit: policy[kind],
      });
    }
  }

  for (const [route, bytes] of Object.entries(routes)) {
    if (bytes > policy.route) {
      issues.push({
        code: "route-over",
        target: route,
        actual: bytes,
        limit: policy.route,
      });
    }
  }

  const totalBytes = Object.values(totals).reduce((sum, value) => sum + value, 0);
  if (totalBytes > policy.total) {
    issues.push({
      code: "total-over",
      target: "total",
      actual: totalBytes,
      limit: policy.total,
    });
  }

  return {
    totals,
    totalBytes,
    routes,
    issues,
    status: issues.length === 0 ? "pass" : "fail",
  };
}

/**
 * 内存预算同时看峰值与斜率。
 * 峰值回答“会不会被系统杀掉”，斜率回答“是不是在慢慢泄漏”。
 */
export function checkMemoryBudget(
  samples: readonly MemorySample[],
  policy: MemoryPolicy,
): MemoryVerdict {
  if (samples.length < 2) {
    throw new Error("checkMemoryBudget: 至少需要 2 个内存样本");
  }
  for (let index = 1; index < samples.length; index += 1) {
    if (samples[index].atMs <= samples[index - 1].atMs) {
      throw new Error("checkMemoryBudget: 样本时间必须严格递增");
    }
  }

  const peakMb = Math.max(...samples.map((sample) => sample.heapMb));
  const first = samples[0];
  const last = samples[samples.length - 1];
  const minutes = (last.atMs - first.atMs) / 60_000;
  const growthMbPerMinute = (last.heapMb - first.heapMb) / minutes;
  const reasons: string[] = [];

  if (peakMb > policy.peakMb) {
    reasons.push(`峰值 ${peakMb.toFixed(1)}MB 超过上限 ${policy.peakMb}MB`);
  }
  if (growthMbPerMinute > policy.growthMbPerMinute) {
    reasons.push(
      `增长 ${growthMbPerMinute.toFixed(2)}MB/min 超过上限 ${policy.growthMbPerMinute}MB/min`,
    );
  }

  return {
    peakMb,
    growthMbPerMinute,
    status: reasons.length === 0 ? "pass" : "fail",
    reasons,
  };
}

/**
 * 时钟由外部注入：生产里用 performance.now，测试里用手动推进的假时钟。
 * 这样采样器本身不依赖定时器，也不需要等待真实时间流逝。
 */
export function createMemorySampler(clock: () => number): MemorySampler {
  const collected: MemorySample[] = [];

  return {
    sample(heapMb: number): MemorySample {
      if (!Number.isFinite(heapMb) || heapMb < 0) {
        throw new Error(`memory sampler: heapMb 必须是非负有限数，收到 ${heapMb}`);
      }
      const sample: MemorySample = { atMs: clock(), heapMb };
      collected.push(sample);
      return sample;
    },
    samples(): readonly MemorySample[] {
      return collected;
    },
  };
}

node --test test/quality/bundle-budget.test.ts

✔ 全部资源都在预算内时状态为 pass (0.837ms)
✔ 路由包按路由聚合后再比对预算 (0.080917ms)
✔ 单类资源与总量可同时报告 (0.125792ms)
✔ 非法字节数与缺少 route 的资产会抛错 (0.606458ms)
✔ 内存峰值超限判失败 (0.180417ms)
✔ 内存斜率超限判失败 (0.069917ms)
✔ 采样器使用注入时钟，稳定内存判通过 (0.098875ms)
✔ 样本时间不递增或数量不足会抛错 (0.076666ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 149.9365