《互联网产品的客户端架构·端形态与体验基础》5.2 服务端状态的缓存与失效

// file: src/state/cache.ts
// tier: L1
// verify: node --test test/state/cache.test.ts

export type ResourceKind = "price" | "session" | "feed" | "detail" | "config";
export type RevalidateMode = "background" | "blocking" | "none";

export interface CachePolicy {
  /** 可以直接展示的时长 */
  ttlMs: number;
  /** 超过 ttl 后仍可继续展示、同时后台刷新的时长 */
  staleMs: number;
  /** background 允许展示旧值，blocking 不允许，none 不主动刷新 */
  mode: RevalidateMode;
}

/**
 * 按资源类型决定过期策略，而不是给所有 key 一个统一 TTL。
 * 价格必须新鲜，配置几乎不变，内容流允许在旧值上停留一会儿。
 */
export const CACHE_POLICIES: Record<ResourceKind, CachePolicy> = {
  price: { ttlMs: 5_000, staleMs: 0, mode: "blocking" },
  session: { ttlMs: 30_000, staleMs: 120_000, mode: "background" },
  feed: { ttlMs: 60_000, staleMs: 300_000, mode: "background" },
  detail: { ttlMs: 300_000, staleMs: 900_000, mode: "background" },
  config: { ttlMs: 3_600_000, staleMs: 0, mode: "background" },
};

export type CacheStatus = "fresh" | "stale" | "expired" | "miss";

export interface ReadResult<T> {
  status: CacheStatus;
  value?: T;
  ageMs: number | null;
  shouldRevalidate: boolean;
}

interface Entry {
  kind: ResourceKind;
  value: unknown;
  fetchedAt: number;
}

export interface RevalidateToken {
  key: string;
  generation: number;
}

/**
 * 服务端状态缓存：注入 now，不使用真实时钟。
 * 失效会推进 generation，使失效前发出的请求无法回写旧数据。
 */
export class ResourceCache {
  private entries = new Map<string, Entry>();
  private generations = new Map<string, number>();
  private inflight = new Map<string, number>();
  private readonly now: () => number;

  constructor(now: () => number) {
    this.now = now;
  }

  get size(): number {
    return this.entries.size;
  }

  read<T>(kind: ResourceKind, key: string): ReadResult<T> {
    const entry = this.entries.get(key);
    if (!entry || entry.kind !== kind) {
      return { status: "miss", ageMs: null, shouldRevalidate: true };
    }
    const policy = CACHE_POLICIES[kind];
    const ageMs = Math.max(0, this.now() - entry.fetchedAt);
    if (ageMs <= policy.ttlMs) {
      return {
        status: "fresh",
        value: entry.value as T,
        ageMs,
        shouldRevalidate: false,
      };
    }
    const withinStale =
      policy.mode === "background" &&
      policy.staleMs > 0 &&
      ageMs <= policy.ttlMs + policy.staleMs;
    if (withinStale) {
      return {
        status: "stale",
        value: entry.value as T,
        ageMs,
        shouldRevalidate: true,
      };
    }
    return { status: "expired", ageMs, shouldRevalidate: policy.mode !== "none" };
  }

  write<T>(
    kind: ResourceKind,
    key: string,
    value: T,
    fetchedAt: number = this.now(),
  ): void {
    this.entries.set(key, { kind, value, fetchedAt });
  }

  /** 同一 key 只允许一个刷新在飞；已有刷新时返回 undefined。 */
  beginRevalidate(key: string): RevalidateToken | undefined {
    if (this.inflight.has(key)) return undefined;
    const generation = this.generations.get(key) ?? 0;
    this.inflight.set(key, generation);
    return { key, generation };
  }

  /** 只有 token 仍对应当前 generation 时才写入，防止旧响应覆盖新数据。 */
  commit<T>(
    token: RevalidateToken,
    kind: ResourceKind,
    value: T,
    fetchedAt: number = this.now(),
  ): boolean {
    if (this.inflight.get(token.key) !== token.generation) return false;
    this.inflight.delete(token.key);
    if ((this.generations.get(token.key) ?? 0) !== token.generation) return false;
    this.entries.set(token.key, { kind, value, fetchedAt });
    return true;
  }

  abort(token: RevalidateToken): void {
    if (this.inflight.get(token.key) === token.generation) {
      this.inflight.delete(token.key);
    }
  }

  /** 删除缓存并推进 generation，返回此前是否存在条目。 */
  invalidate(key: string): boolean {
    this.generations.set(key, (this.generations.get(key) ?? 0) + 1);
    this.inflight.delete(key);
    return this.entries.delete(key);
  }

  invalidatePrefix(prefix: string): number {
    let removed = 0;
    for (const key of [...this.entries.keys()]) {
      if (key.startsWith(prefix)) {
        this.invalidate(key);
        removed += 1;
      }
    }
    return removed;
  }

  clear(): void {
    for (const key of [...this.entries.keys()]) this.invalidate(key);
  }
}

node --test test/state/cache.test.ts

✔ 空缓存读取为 miss，并请求拉取 (0.5535ms)
✔ ttl 内为 fresh，不触发刷新 (0.416292ms)
✔ 超过 ttl 但在 stale 窗口内，先展示旧值再后台刷新 (0.58525ms)
✔ 超过 stale 窗口后为 expired，不再展示旧值 (0.153083ms)
✔ blocking 策略的价格不允许展示过期值 (0.085709ms)
✔ 失效会推进 generation，失效前发出的刷新无法回写 (0.176792ms)
✔ 同一 key 的刷新按 token 去重，abort 后可以重新开始 (0.068583ms)
✔ 前缀失效只删除匹配的 key 并返回数量 (0.0815ms)
✔ 时钟回拨时年龄按 0 处理，不会误判为过期 (0.086833ms)
✔ 同 key 换了资源类型按 miss 处理，避免策略串用 (0.165208ms)
✔ 策略表保持资源类型的过期顺序 (0.082584ms)
ℹ tests 11
ℹ suites 0
ℹ pass 11
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 202.344