《互联网产品的客户端架构·端形态与体验基础》11.1 错误边界与白屏治理

// file: src/error/error-boundary.ts
// tier: L1
// verify: node --test test/error/error-boundary.test.ts

export type ErrorSource = "network" | "render" | "contract" | "auth" | "unknown";
export type ErrorClass = "recoverable" | "degradable" | "fatal";
export type RecoveryAction = "retry" | "reauth" | "fallback" | "disable-feature" | "reload" | "contact-support";
export type FallbackScope = "inline" | "section" | "page" | "app";

export interface ErrorSignal {
  source: ErrorSource;
  /** HTTP 状态码，只在 network/auth 来源下有意义 */
  status?: number;
  /** 同一位置连续失败的次数，由调用方统计 */
  repeats?: number;
  /** 适配器给出的可重试提示；缺省时按状态码推断 */
  retryable?: boolean;
  message?: string;
}

export interface ErrorDecision {
  class: ErrorClass;
  action: RecoveryAction;
  retryBudget: number;
  reason: string;
}

const FATAL_REPEATS = 2;

function decision(
  cls: ErrorClass,
  action: RecoveryAction,
  retryBudget: number,
  reason: string,
): ErrorDecision {
  return { class: cls, action, retryBudget, reason };
}

/**
 * 把一次失败信号翻译成三类处理策略。
 * 分类只回答「这个错误应该被谁接住」，不负责渲染，也不读取 DOM。
 */
export function classifyError(signal: ErrorSignal): ErrorDecision {
  const repeats = signal.repeats ?? 0;
  const status = signal.status ?? 0;

  if (signal.source === "auth") {
    if (status === 401) return decision("recoverable", "reauth", 0, "凭证过期，需要用户重新登录后重放");
    if (status === 403) return decision("degradable", "disable-feature", 0, "当前角色无权限，隐藏入口比反复重试更诚实");
    return decision("fatal", "contact-support", 0, "认证状态无法判定，继续重试只会放大故障");
  }

  if (signal.source === "network") {
    if (status === 401) return decision("recoverable", "reauth", 0, "网关要求重新认证");
    if (status === 403) return decision("degradable", "disable-feature", 0, "请求被拒绝，重试不会改变权限");
    if (status === 404 || status === 410) return decision("degradable", "fallback", 0, "资源已不存在，应展示空态或上一份缓存");
    if (status === 400 || status === 422) return decision("degradable", "disable-feature", 0, "客户端与服务端契约不一致，原样重试没有意义");
    if (status === 429) return decision("recoverable", "retry", 1, "被限流，只允许一次带延迟的重试");
    if (signal.retryable === false) return decision("degradable", "fallback", 0, "适配器明确标记不可重试，直接进入兜底");
    if (status === 0 || status === 408 || status >= 500) {
      return decision("recoverable", "retry", 2, "超时或服务端暂时不可用，可在预算内重试");
    }
  }

  if (signal.source === "render") {
    if (repeats >= FATAL_REPEATS) return decision("fatal", "reload", 0, `同一渲染位置连续失败 ${repeats} 次，局部兜底已不可信`);
    return decision("degradable", "fallback", 0, "首次渲染失败，先替换该子树并保留页面其余部分");
  }

  if (signal.source === "contract") {
    return decision("degradable", "disable-feature", 0, "数据结构不符合预期，关闭依赖该字段的功能");
  }

  if (repeats >= FATAL_REPEATS) {
    return decision("fatal", "contact-support", 0, "未知错误重复出现，需要人工介入");
  }
  return decision("degradable", "fallback", 0, "未知错误首次出现，先用局部兜底隔离影响面");
}

export interface BoundarySpec {
  id: string;
  /** 父边界；critical 边界不允许局部降级，必须向上一层升级 */
  parentId?: string;
  /** 该边界失败时替换的最小区域 */
  scope: FallbackScope;
  critical?: boolean;
  /** 恢复尝试次数上限，默认 2 */
  retryBudget?: number;
}

export type BoundaryStatus = "active" | "tripped" | "recovering";

export interface BoundarySnapshot {
  id: string;
  status: BoundaryStatus;
  failures: number;
  recoveryAttempts: number;
  lastMessage: string;
  lastAtMs: number;
}

export interface Incident {
  boundaryId: string;
  decision: ErrorDecision;
  fallback: FallbackScope;
  /** 升级后的边界 id；应用级兜底用 "app" 表示 */
  escalatedTo: string | null;
  snapshot: BoundarySnapshot;
}

export interface RecoveryResult {
  status: "recovered" | "tripped" | "escalated";
  boundaryId: string;
  nextBoundaryId: string | null;
  retriesLeft: number;
}

/**
 * 边界模型只维护「谁接住了错误、还剩几次恢复机会」。
 * 真实框架可以把它映射成组件树，测试里则完全不需要 DOM。
 */
export class BoundaryModel {
  private readonly now: () => number;
  private readonly specs: Map<string, BoundarySpec>;
  private readonly runtimes: Map<string, BoundarySnapshot>;

  constructor(now: () => number) {
    this.now = now;
    this.specs = new Map();
    this.runtimes = new Map();
  }

  register(spec: BoundarySpec): void {
    if (this.specs.has(spec.id)) throw new Error(`边界 ${spec.id} 重复注册`);
    if (spec.parentId !== undefined && !this.specs.has(spec.parentId)) {
      throw new Error(`父边界 ${spec.parentId} 尚未注册`);
    }
    this.specs.set(spec.id, spec);
    this.runtimes.set(spec.id, {
      id: spec.id, failures: 0, recoveryAttempts: 0,
      status: "active", lastMessage: "", lastAtMs: this.now(),
    });
  }

  snapshot(id: string): BoundarySnapshot | undefined {
    const runtime = this.runtimes.get(id);
    return runtime === undefined ? undefined : { ...runtime };
  }

  /**
   * 可恢复错误留在原边界；可降级错误替换局部；
   * 致命错误或关键边界上的降级错误向父边界升级。
   */
  capture(boundaryId: string, signal: ErrorSignal): Incident {
    const spec = this.specs.get(boundaryId);
    const runtime = this.runtimes.get(boundaryId);
    if (spec === undefined || runtime === undefined) throw new Error(`边界 ${boundaryId} 未注册`);

    runtime.failures += 1;
    runtime.lastMessage = signal.message ?? "";
    runtime.lastAtMs = this.now();
    const decision = classifyError({
      ...signal,
      repeats: Math.max(signal.repeats ?? 0, runtime.failures),
    });

    const mustEscalate =
      decision.class === "fatal" ||
      (spec.critical === true && decision.class !== "recoverable");

    runtime.status = "tripped";
    if (!mustEscalate) {
      return {
        boundaryId,
        decision,
        fallback: spec.scope,
        escalatedTo: null,
        snapshot: this.snapshot(boundaryId)!,
      };
    }

    const parent = spec.parentId ?? null;
    if (parent !== null) {
      const parentRuntime = this.runtimes.get(parent);
      if (parentRuntime !== undefined) {
        parentRuntime.status = "tripped";
        parentRuntime.failures += 1;
        parentRuntime.lastMessage = runtime.lastMessage;
        parentRuntime.lastAtMs = runtime.lastAtMs;
      }
    }
    return {
      boundaryId,
      decision,
      fallback: parent === null ? "app" : this.specs.get(parent)!.scope,
      escalatedTo: parent ?? "app",
      snapshot: this.snapshot(boundaryId)!,
    };
  }

  /**
   * 用户或上层触发一次恢复。成功则复位；失败则消耗一次恢复预算，
   * 预算耗尽后升级到父边界。时钟通过构造函数注入，不依赖真实定时器。
   */
  recover(boundaryId: string, success: boolean): RecoveryResult {
    const spec = this.specs.get(boundaryId);
    const runtime = this.runtimes.get(boundaryId);
    if (spec === undefined || runtime === undefined) throw new Error(`边界 ${boundaryId} 未注册`);
    const budget = spec.retryBudget ?? 2;

    if (success) {
      runtime.status = "active";
      runtime.failures = 0;
      runtime.recoveryAttempts = 0;
      return { status: "recovered", boundaryId, nextBoundaryId: null, retriesLeft: budget };
    }

    runtime.recoveryAttempts += 1;
    const retriesLeft = budget - runtime.recoveryAttempts;
    if (retriesLeft > 0) {
      runtime.status = "tripped";
      return { status: "tripped", boundaryId, nextBoundaryId: null, retriesLeft };
    }

    const parent = spec.parentId ?? "app";
    runtime.status = "tripped";
    if (parent !== "app") {
      const parentRuntime = this.runtimes.get(parent);
      if (parentRuntime !== undefined) parentRuntime.status = "tripped";
    }
    return { status: "escalated", boundaryId, nextBoundaryId: parent, retriesLeft: 0 };
  }
}

app
└── page: 商品详情
    ├── section: 评价列表      scope=section
    └── section: 结算面板      scope=section, critical=true
        └── inline: 优惠券行    scope=inline

node --test test/error/error-boundary.test.ts

✔ 超时与服务端 5xx 归为可恢复错误 (0.540333ms)
✔ 404 归为可降级错误，直接进入兜底 (0.067584ms)
✔ 契约不一致与无权限都关闭依赖功能，而不是重试 (0.554458ms)
✔ 渲染错误连续两次升级为致命错误 (0.1305ms)
✔ 边界捕获可恢复错误时保留局部兜底 (0.202833ms)
✔ 关键边界不允许局部降级，必须升级到父边界 (0.086709ms)
✔ 没有父边界的致命错误落到应用级兜底 (0.079333ms)
✔ 恢复成功后边界复位并清空失败计数 (0.108458ms)
✔ 恢复预算耗尽后升级，剩余次数逐次递减 (0.104042ms)
ℹ tests 9
ℹ suites 0
ℹ pass 9
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 138.942125