《互联网产品的客户端架构·端形态与体验基础》10.2 水合与首屏一致性

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

export type MismatchCause = "clock" | "random" | "local-state" | "permission" | "content";

/** 生成首帧所需的输入；服务端与客户端拿到的是不同的快照。 */
export interface RenderView {
  /** 渲染时刻（毫秒时间戳） */
  now: number;
  /** 每次渲染生成的随机标识 */
  nonce: string;
  /** 只存在浏览器里的草稿 */
  localDraft: string | null;
  /** 当前会话权限 */
  canEdit: boolean;
  /** 页面正文 */
  title: string;
}

export interface FrameField {
  name: string;
  cause: MismatchCause;
  value: string;
}

export interface FrameDiff {
  name: string;
  cause: MismatchCause | "structure";
  server: string | null;
  client: string | null;
}

/** 服务端首帧：没有草稿，权限来自服务端会话，时间与随机数各生成一次。 */
export function serverFrame(view: RenderView): FrameField[] {
  return [
    { name: "title", cause: "content", value: view.title },
    { name: "rendered-at", cause: "clock", value: new Date(view.now).toISOString() },
    { name: "nonce", cause: "random", value: view.nonce.slice(0, 8) },
    { name: "role", cause: "permission", value: view.canEdit ? "editor" : "reader" },
  ];
}

/** 客户端首帧：除正文外，每个字段都可能与服务端快照不同。 */
export function clientFrame(view: RenderView): FrameField[] {
  const fields = serverFrame(view);
  if (view.localDraft !== null) {
    fields.push({ name: "draft", cause: "local-state", value: view.localDraft });
  }
  return fields;
}

/**
 * 比较两帧。字段级差异保留来源原因；缺字段或多字段统一记为 structure，
 * 因为结构差异意味着组件树本身不一致，比单个值不一致更难恢复。
 */
export function diffFrames(server: FrameField[], client: FrameField[]): FrameDiff[] {
  const serverMap = new Map(server.map((field) => [field.name, field]));
  const clientMap = new Map(client.map((field) => [field.name, field]));
  const diffs: FrameDiff[] = [];

  for (const [name, left] of serverMap) {
    const right = clientMap.get(name);
    if (right === undefined) {
      diffs.push({ name, cause: "structure", server: left.value, client: null });
      continue;
    }
    if (left.value !== right.value) {
      diffs.push({
        name,
        cause: left.cause === right.cause ? left.cause : "structure",
        server: left.value,
        client: right.value,
      });
    }
  }

  for (const [name, right] of clientMap) {
    if (!serverMap.has(name)) {
      diffs.push({ name, cause: "structure", server: null, client: right.value });
    }
  }

  return diffs;
}

export interface StabilizedFrame {
  /** 水合时直接采用服务端快照的字段，保证首帧逐字节一致 */
  frame: FrameField[];
  /** 必须等水合完成后再写入的本地字段 */
  deferred: FrameField[];
  /** 客户端多出来、又不属于本地状态的字段，应视为缺陷 */
  unexpected: FrameField[];
}

/**
 * 把客户端帧收敛到服务端快照：时钟、随机数、权限一律以服务端为准；
 * 本地草稿不进首帧，放到 deferred，由挂载后的副作用写入。
 */
export function stabilize(server: FrameField[], client: FrameField[]): StabilizedFrame {
  const clientMap = new Map(client.map((field) => [field.name, field]));
  const frame = server.map((field) => {
    if (field.cause === "local-state") {
      return clientMap.get(field.name) ?? field;
    }
    return field;
  });

  const serverNames = new Set(server.map((field) => field.name));
  const extra = client.filter((field) => !serverNames.has(field.name));

  return {
    frame,
    deferred: extra.filter((field) => field.cause === "local-state"),
    unexpected: extra.filter((field) => field.cause !== "local-state"),
  };
}

/**
 * 水合前只允许本地状态缺席；时钟、随机数、权限、正文任何一项不一致都要报错。
 * 返回空数组表示两帧可以安全水合。
 */
export function hydrationViolations(server: FrameField[], client: FrameField[]): FrameDiff[] {
  const localNames = new Set(
    client.filter((field) => field.cause === "local-state").map((field) => field.name),
  );
  return diffFrames(server, client).filter((diff) => {
    if (diff.cause === "local-state") return false;
    return !(diff.cause === "structure" && localNames.has(diff.name));
  });
}

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

✔ 同一份视图生成的两帧没有差异 (2.380959ms)
✔ 时钟与随机数差异被归到各自来源 (0.170917ms)
✔ 权限快照不同记为 permission (0.101375ms)
✔ 只在客户端存在的草稿是结构差异，但可被延后处理 (0.5295ms)
✔ 本地草稿在默认规则下不算水合违规 (0.131958ms)
✔ 正文不一致必须报错，不能被当成可延后状态 (0.081209ms)
✔ 时钟、随机数、权限一律以服务端快照为准 (0.083416ms)
✔ 客户端多出的非本地字段被列为意外结构 (0.080792ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 112.042708