《互联网产品的客户端架构·端形态与体验基础》5.3 状态机的引入判据

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

export interface MachineSignals {
  /** 互斥状态的数量 */
  stateCount: number;
  /** 合法迁移的数量 */
  transitionCount: number;
  /** 是否存在“绝不能发生”的状态组合 */
  hasForbiddenPairs: boolean;
  /** 状态是否跨越网络或其他异步边界 */
  asyncBoundary: boolean;
  /** 平均每个迁移绑定的副作用数量 */
  effectsPerTransition: number;
  /** 状态是否只由单一筛选输入推导出来 */
  derivedFromSingleInput: boolean;
}

export interface MachineDecision {
  use: boolean;
  score: number;
  reason: string;
}

/**
 * 判断一段状态是否值得引入状态机。
 * 单一输入推导出的列表筛选先被排除，其余按禁止迁移、异步边界与状态数量计分。
 */
export function shouldUseStateMachine(signals: MachineSignals): MachineDecision {
  if (
    signals.derivedFromSingleInput &&
    !signals.asyncBoundary &&
    !signals.hasForbiddenPairs
  ) {
    return {
      use: false,
      score: 0,
      reason: "状态只由单一输入推导，普通派生值更简单",
    };
  }

  let score = 0;
  if (signals.stateCount >= 3) score += 2;
  if (signals.transitionCount >= 4) score += 2;
  if (signals.hasForbiddenPairs) score += 3;
  if (signals.asyncBoundary) score += 2;
  if (signals.effectsPerTransition >= 2) score += 1;

  const use = score >= 4;
  const reason = signals.hasForbiddenPairs
    ? `存在禁止迁移，需要显式迁移表（得分 ${score}）`
    : signals.asyncBoundary
      ? `跨越异步边界，需要可恢复的状态（得分 ${score}）`
      : use
        ? `状态与迁移数量已达到阈值（得分 ${score}）`
        : `状态与迁移都较少，用布尔标记即可（得分 ${score}）`;
  return { use, score, reason };
}

export type UploadState =
  | "idle"
  | "uploading"
  | "paused"
  | "verifying"
  | "done"
  | "failed"
  | "cancelled";

export type UploadEvent =
  | "start"
  | "pause"
  | "resume"
  | "sent"
  | "verify-ok"
  | "verify-fail"
  | "cancel"
  | "retry";

export interface UploadContext {
  attempts: number;
  maxAttempts: number;
  totalBytes: number;
  error?: string;
}

export interface TransitionResult {
  ok: boolean;
  state: UploadState;
  context: UploadContext;
  effects: string[];
  error?: string;
}

/** 显式迁移表：没有列出的组合一律拒绝，而不是靠 if 顺序兜底。 */
const TRANSITIONS: Record<UploadState, Partial<Record<UploadEvent, UploadState>>> = {
  idle: { start: "uploading" },
  uploading: { pause: "paused", sent: "verifying", cancel: "cancelled" },
  paused: { resume: "uploading", cancel: "cancelled" },
  verifying: { "verify-ok": "done", "verify-fail": "failed" },
  failed: { retry: "uploading", cancel: "cancelled" },
  done: {},
  cancelled: {},
};

const EFFECTS: Record<UploadEvent, string[]> = {
  start: ["create-upload-token"],
  pause: ["persist-resume-token"],
  resume: ["resume-upload"],
  sent: ["start-verification"],
  "verify-ok": ["publish-result"],
  "verify-fail": ["keep-temp-file"],
  cancel: ["delete-temp-file"],
  retry: ["create-upload-token"],
};

/**
 * 上传状态机：纯函数，不发起真实请求，也不读时钟。
 * 非法事件返回 ok:false，状态与上下文保持不变，便于界面直接回显错误。
 */
export function transition(
  state: UploadState,
  event: UploadEvent,
  context: UploadContext,
): TransitionResult {
  const next = TRANSITIONS[state][event];
  if (!next) {
    return {
      ok: false,
      state,
      context,
      effects: [],
      error: `状态 ${state} 不接受事件 ${event}`,
    };
  }
  if (event === "retry" && context.attempts >= context.maxAttempts) {
    return {
      ok: false,
      state,
      context,
      effects: [],
      error: "重试次数已用尽",
    };
  }

  const nextContext: UploadContext = { ...context };
  if (event === "start" || event === "retry") {
    nextContext.attempts = context.attempts + 1;
  }
  if (event === "resume") nextContext.error = undefined;
  if (event === "verify-fail") nextContext.error = "verification-failed";
  return { ok: true, state: next, context: nextContext, effects: EFFECTS[event] };
}

/** 从起始状态做广度优先遍历，返回可达状态，用于发现永远进不去的分支。 */
export function reachableStates(from: UploadState = "idle"): UploadState[] {
  const seen = new Set<UploadState>([from]);
  const queue: UploadState[] = [from];
  while (queue.length > 0) {
    const current = queue.shift() as UploadState;
    for (const target of Object.values(TRANSITIONS[current])) {
      if (target && !seen.has(target)) {
        seen.add(target);
        queue.push(target);
      }
    }
  }
  return [...seen].sort();
}

/** 迁移表里出现的每个目标都必须是已声明的状态。 */
export function allTargetsKnown(): boolean {
  const states = new Set(Object.keys(TRANSITIONS));
  for (const row of Object.values(TRANSITIONS)) {
    for (const target of Object.values(row)) {
      if (target && !states.has(target)) return false;
    }
  }
  return true;
}

node --test test/state/machine.test.ts

✔ 上传成功路径按迁移表推进并返回副作用 (0.932542ms)
✔ 非法事件被拒绝，状态与上下文不变 (0.647333ms)
✔ 暂停与恢复往返，暂停时持久化续传令牌 (0.094ms)
✔ 失败后重试会累加次数，超过上限后拒绝 (0.076916ms)
✔ 校验失败留在 failed 并记录错误，临时文件保留 (0.065375ms)
✔ 取消会清理临时文件，终态不再接受事件 (0.072208ms)
✔ 迁移表的目标全部是已声明状态 (0.08725ms)
✔ 七个状态都从 idle 可达，没有进不去的分支 (0.086666ms)
✔ 列表筛选不适合状态机 (0.114625ms)
✔ 上传与订单流程因禁止迁移与异步边界被判为适合 (0.146208ms)
✔ 状态与迁移刚好到阈值时才启用状态机 (0.060458ms)
ℹ tests 11
ℹ suites 0
ℹ pass 11
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 163.55