《互联网产品的客户端架构·端形态与体验基础》11.2 弱网与接口失败兜底

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

export type NetworkOutcome =
  | { state: "ok"; elapsedMs: number }
  | { state: "timeout"; elapsedMs: number }
  | { state: "failure"; elapsedMs: number; status?: number }
  | {
      state: "partial";
      elapsedMs: number;
      received: number;
      total: number;
      /** 缺失且会破坏主任务的字段名 */
      missingCritical: string[];
    };

export interface CacheSnapshot {
  savedAtMs: number;
  /** 测试只关心是否可读，真实实现放序列化后的数据 */
  value: unknown;
}

export interface FallbackPolicy {
  /** 超过这个年龄的缓存不再参与兜底 */
  maxStaleMs: number;
  /** 单次请求允许的重试次数 */
  retryBudget: number;
}

export type FallbackAction =
  | "use-network"
  | "retry-inline"
  | "use-cache"
  | "degraded-content"
  | "manual-retry";

export type DataTrust = "fresh" | "stale" | "partial";

export interface FallbackDecision {
  action: FallbackAction;
  trust: DataTrust;
  showBanner: boolean;
  cacheAgeMs: number | null;
  reason: string;
}

function cacheAge(cache: CacheSnapshot | undefined, now: number): number | null {
  if (cache === undefined) return null;
  return now - cache.savedAtMs;
}

function usableCache(
  cache: CacheSnapshot | undefined,
  now: number,
  policy: FallbackPolicy,
): boolean {
  const age = cacheAge(cache, now);
  return age !== null && age >= 0 && age <= policy.maxStaleMs;
}

/**
 * 把一次请求结果翻译成端上动作。决策不发起请求，只决定下一步，
 * 因此可以在测试里用纯数据覆盖超时、失败与半成功三态。
 */
export function decideFallback(
  outcome: NetworkOutcome,
  cache: CacheSnapshot | undefined,
  now: number,
  policy: FallbackPolicy,
  retriesLeft: number,
): FallbackDecision {
  const age = cacheAge(cache, now);

  if (outcome.state === "ok") {
    return {
      action: "use-network",
      trust: "fresh",
      showBanner: false,
      cacheAgeMs: null,
      reason: "请求成功，直接使用网络结果",
    };
  }

  if (outcome.state === "partial") {
    if (outcome.missingCritical.length === 0) {
      return {
        action: "degraded-content",
        trust: "partial",
        showBanner: true,
        cacheAgeMs: null,
        reason: "关键字段齐全，保留已到达内容并标注非关键字段缺失",
      };
    }
    if (retriesLeft > 0) {
      return {
        action: "retry-inline",
        trust: "partial",
        showBanner: true,
        cacheAgeMs: null,
        reason: `半成功且缺少 ${outcome.missingCritical.join(",")}，先用剩余预算补齐`,
      };
    }
    if (usableCache(cache, now, policy)) {
      return {
        action: "use-cache",
        trust: "stale",
        showBanner: true,
        cacheAgeMs: age,
        reason: "关键字段缺失且预算耗尽，回退到上一份完整缓存",
      };
    }
    return {
      action: "manual-retry",
      trust: "partial",
      showBanner: true,
      cacheAgeMs: age,
      reason: "半成功、无可用缓存且无预算，交给用户手动重试",
    };
  }

  if (outcome.state === "timeout") {
    if (usableCache(cache, now, policy)) {
      return {
        action: "use-cache",
        trust: "stale",
        showBanner: true,
        cacheAgeMs: age,
        reason: "超时优先展示缓存，避免用户继续等待",
      };
    }
    if (retriesLeft > 0) {
      return {
        action: "retry-inline",
        trust: "stale",
        showBanner: true,
        cacheAgeMs: null,
        reason: "没有可用缓存，在预算内做一次短重试",
      };
    }
    return {
      action: "manual-retry",
      trust: "stale",
      showBanner: true,
      cacheAgeMs: age,
      reason: "超时且无可用缓存、无预算，展示手动重试入口",
    };
  }

  if (retriesLeft > 0) {
    return {
      action: "retry-inline",
      trust: "stale",
      showBanner: true,
      cacheAgeMs: null,
      reason: `请求失败（${outcome.status ?? "无状态码"}），预算内先重试`,
    };
  }
  if (usableCache(cache, now, policy)) {
    return {
      action: "use-cache",
      trust: "stale",
      showBanner: true,
      cacheAgeMs: age,
      reason: "重试预算耗尽，使用未过期的缓存兜底",
    };
  }
  return {
    action: "manual-retry",
    trust: "stale",
    showBanner: true,
    cacheAgeMs: age,
    reason: "请求失败且没有可用兜底，交还用户决定",
  };
}

export interface RetryBudgetOptions {
  capacity: number;
  windowMs: number;
}

/**
 * 滑动窗口重试预算。只看注入的时钟，不启动定时器。
 * 窗口内的消耗到达容量后，必须等最早一次消耗滑出窗口才恢复。
 */
export class RetryBudget {
  private readonly capacity: number;
  private readonly windowMs: number;
  private spent: number[];

  constructor(options: RetryBudgetOptions) {
    if (options.capacity < 0) throw new Error("capacity 不能为负数");
    if (options.windowMs <= 0) throw new Error("windowMs 必须为正数");
    this.capacity = options.capacity;
    this.windowMs = options.windowMs;
    this.spent = [];
  }

  available(now: number): number {
    this.prune(now);
    return Math.max(0, this.capacity - this.spent.length);
  }

  consume(now: number): boolean {
    this.prune(now);
    if (this.spent.length >= this.capacity) return false;
    this.spent.push(now);
    return true;
  }

  reset(): void {
    this.spent = [];
  }

  private prune(now: number): void {
    const cutoff = now - this.windowMs;
    this.spent = this.spent.filter((at) => at > cutoff);
  }
}

node --test test/error/fallback-policy.test.ts

✔ 成功结果直接使用网络数据 (1.004583ms)
✔ 超时优先使用未过期缓存，避免用户继续等待 (0.132292ms)
✔ 超时且无缓存时在预算内短重试 (0.064833ms)
✔ 失败时先重试，即使有缓存也把网络当作首选 (0.061375ms)
✔ 失败且预算耗尽时回退到未过期缓存 (0.067875ms)
✔ 半成功但关键字段齐全时保留已到达内容 (0.053042ms)
✔ 半成功且关键字段缺失时先补请求，再考虑缓存 (0.060125ms)
✔ 缓存年龄超过上限后不再参与兜底 (0.043792ms)
✔ 重试预算按滑动窗口释放额度 (0.124708ms)
✔ 重置预算后重新获得全部额度 (0.108792ms)
ℹ tests 10
ℹ suites 0
ℹ pass 10
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 220.135541