《互联网产品的客户端架构·端形态与体验基础》10.1 CSR、SSR、SSG 与流式

// file: src/render/render-modes.ts
// tier: L1
// verify: node --test test/render/render-modes.test.ts

export type RenderMode = "csr" | "ssr" | "ssg" | "streaming";

export interface PageTraits {
  /** 页面是否承载搜索流量，爬虫必须拿到完整正文 */
  seoCritical: boolean;
  /** 首屏是否因登录用户不同而不同 */
  personalized: boolean;
  /** 内容允许的最大陈旧时间（分钟）；Infinity 表示可长期缓存 */
  contentVolatilityMinutes: number;
  /** 渲染首屏所需最慢数据源的 P75 耗时（毫秒） */
  slowestDataSourceMs: number;
  /** 页面交互密度 */
  interactionLevel: "low" | "medium" | "high";
  /** 是否需要登录才能访问 */
  authRequired: boolean;
  /** 首屏外壳是否能在数据到达前先输出 */
  shellStable: boolean;
}

export interface RenderCost {
  /** 每千次请求的服务端渲染 CPU 秒 */
  serverCpuSecPer1k: number;
  /** 客户端首屏 JS 体积（KB，未压缩） */
  clientJsKb: number;
  /** 缓存命中时的 TTFB（毫秒） */
  cachedTtfbMs: number;
  /** 首屏可交互时间（毫秒） */
  interactiveMs: number;
}

export interface RenderDecision {
  mode: RenderMode;
  reasons: string[];
  rejected: { mode: RenderMode; reason: string }[];
  cost: RenderCost;
}

/** 内容陈旧窗口的分界：一分钟级必须逐请求，一天以上可预生成。 */
const VOLATILE_MINUTES = 60;
const DAILY_MINUTES = 24 * 60;
/** 慢数据源的分界：超过 300ms 时，先吐外壳比等整页更有意义。 */
const SLOW_SOURCE_MS = 300;

const REJECTION: Record<RenderMode, string> = {
  csr: "首屏需要完整 HTML 或搜索流量占比高，纯客户端渲染会让首屏与抓取变差",
  ssr: "内容可以预生成或首屏不需要逐请求计算，逐请求渲染浪费服务端 CPU",
  ssg: "首屏个性化或内容陈旧窗口短于构建周期，预生成产物会立刻过期",
  streaming: "首屏外壳依赖数据，无法在数据到达前输出稳定骨架",
};

const BASE: Record<RenderMode, RenderCost> = {
  csr: { serverCpuSecPer1k: 0, clientJsKb: 180, cachedTtfbMs: 20, interactiveMs: 1200 },
  ssr: { serverCpuSecPer1k: 0.9, clientJsKb: 60, cachedTtfbMs: 250, interactiveMs: 600 },
  ssg: { serverCpuSecPer1k: 0.02, clientJsKb: 60, cachedTtfbMs: 30, interactiveMs: 400 },
  streaming: { serverCpuSecPer1k: 0.6, clientJsKb: 70, cachedTtfbMs: 90, interactiveMs: 450 },
};

/** 数据源耗时对可交互时间的贡献：CSR 全等，SSG 不等待，流式只等一部分。 */
const DATA_WAIT_FACTOR: Record<RenderMode, number> = {
  csr: 1,
  ssr: 1,
  ssg: 0,
  streaming: 0.4,
};

/**
 * 按固定优先级选择渲染模式。
 * 顺序有意为之：先排除“根本不该由服务端渲染”的页面，再判断 SEO 与个性化，
 * 最后才在新鲜度与构建周期之间做取舍。
 */
export function chooseRenderMode(traits: PageTraits): RenderDecision {
  const mode = pick(traits);
  return {
    mode,
    reasons: reasonsFor(mode, traits),
    rejected: (Object.keys(REJECTION) as RenderMode[])
      .filter((candidate) => candidate !== mode)
      .map((candidate) => ({ mode: candidate, reason: REJECTION[candidate] })),
    cost: estimateCost(traits, mode),
  };
}

function pick(traits: PageTraits): RenderMode {
  if (!traits.seoCritical && traits.authRequired && traits.interactionLevel === "high") {
    return "csr";
  }
  if (traits.seoCritical && traits.personalized) {
    if (traits.shellStable && traits.slowestDataSourceMs >= SLOW_SOURCE_MS) {
      return "streaming";
    }
    return "ssr";
  }
  if (traits.seoCritical && traits.contentVolatilityMinutes <= VOLATILE_MINUTES) {
    return "ssr";
  }
  if (!traits.seoCritical && traits.interactionLevel === "high") {
    return "csr";
  }
  if (!traits.personalized && traits.contentVolatilityMinutes >= DAILY_MINUTES) {
    return "ssg";
  }
  return "ssr";
}

function reasonsFor(mode: RenderMode, traits: PageTraits): string[] {
  if (mode === "csr") {
    const reasons = ["首屏不需要搜索引擎抓取，交互密度高"];
    reasons.push(traits.authRequired ? "登录后页面只存在于浏览器会话中" : "首屏可先给骨架，数据由客户端补齐");
    reasons.push("静态托管即可，服务端渲染 CPU 为零");
    return reasons;
  }
  if (mode === "ssr") {
    const reasons = traits.personalized
      ? ["首屏按会话不同，必须逐请求渲染"]
      : ["内容陈旧窗口短于预生成周期，构建产物会立即过期"];
    if (traits.seoCritical) reasons.push("需要把完整正文交给爬虫与分享卡片");
    return reasons;
  }
  if (mode === "streaming") {
    return [
      "首屏个性化，但外壳可以复用",
      `最慢数据源 ${traits.slowestDataSourceMs}ms，先输出外壳能缩短感知等待`,
      "数据到达后按片段补位，不阻塞首字节",
    ];
  }
  return [
    "内容非个性化且陈旧窗口长于构建周期",
    "预生成后可走边缘缓存，TTFB 与源站 CPU 都最低",
  ];
}

/** 成本是相对估算：只用于同一页面不同模式之间的比较，不是跨产品基准。 */
export function estimateCost(traits: PageTraits, mode: RenderMode): RenderCost {
  const base = BASE[mode];
  return {
    ...base,
    interactiveMs: Math.round(
      base.interactiveMs + traits.slowestDataSourceMs * DATA_WAIT_FACTOR[mode],
    ),
  };
}

cd .local/checks/echo-client-lab
node --test test/render/render-modes.test.ts

✔ 长陈旧窗口的内容页选择 SSG (0.672209ms)
✔ 登录后的高频交互页选择 CSR (0.116916ms)
✔ 个性化且外壳不稳定时退回 SSR (0.085042ms)
✔ 个性化、外壳稳定且数据源慢时选择流式 (0.090875ms)
✔ 分钟级新鲜度要求逐请求渲染 (0.08075ms)
✔ 同一页面下成本排序符合直觉 (0.065083ms)
✔ 每种模式都会拒绝另外三种并给出理由 (0.182166ms)
ℹ tests 7
ℹ suites 0
ℹ pass 7
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 152.627416