《互联网产品的客户端架构·规模化与架构演进》5.2 降级、开关与兜底

// file: src/stability/degrade-switch.ts
// tier: L1
// verify: node --test test/stability/degrade-switch.test.ts

export type SwitchScope = "global" | "endpoint" | "experiment" | "user";

export type Endpoint = "web" | "ios" | "android" | "miniprogram" | "desktop";

export type SwitchRule = {
  id: string;
  key: string;
  scope: SwitchScope;
  enabled: boolean;
  targets: string[];
  priority: number;
};

export type SwitchContext = { key: string; endpoint: Endpoint; userId?: string; experimentGroups?: string[] };

export type SwitchConflict = { key: string; scope: SwitchScope; ruleIds: string[]; targets: string[] };

export type SwitchAudit = {
  total: number;
  enabled: number;
  disabled: number;
  byScope: Record<SwitchScope, number>;
  conflicts: SwitchConflict[];
};

const SCOPE_RANK: Record<SwitchScope, number> = { global: 1, endpoint: 2, experiment: 3, user: 4 };

export const SWITCH_RULES: SwitchRule[] = [
  { id: "g-cashier-on", key: "checkout.cashier", scope: "global", enabled: true, targets: [], priority: 0 },
  { id: "e-ios-off", key: "checkout.cashier", scope: "endpoint", enabled: false, targets: ["ios"], priority: 10 },
  { id: "x-cashier-v2", key: "checkout.cashier", scope: "experiment", enabled: true, targets: ["cashier-v2"], priority: 5 },
  { id: "u-vip-off", key: "checkout.cashier", scope: "user", enabled: false, targets: ["u-1001"], priority: 1 },
  { id: "g-feed-cache", key: "feed.cache", scope: "global", enabled: true, targets: [], priority: 0 },
  { id: "e-miniprogram-feed-off", key: "feed.cache", scope: "endpoint", enabled: false, targets: ["miniprogram"], priority: 0 },
];

export function scopeRank(scope: SwitchScope): number {
  return SCOPE_RANK[scope];
}

export function ruleMatches(rule: SwitchRule, context: SwitchContext): boolean {
  if (rule.key !== context.key) return false;
  switch (rule.scope) {
    case "global":
      return true;
    case "endpoint":
      return rule.targets.includes(context.endpoint);
    case "user":
      return context.userId !== undefined && rule.targets.includes(context.userId);
    case "experiment":
      return (context.experimentGroups ?? []).some((group) => rule.targets.includes(group));
  }
}

function compareRules(a: SwitchRule, b: SwitchRule): number {
  const byRank = SCOPE_RANK[b.scope] - SCOPE_RANK[a.scope];
  if (byRank !== 0) return byRank;
  const byPriority = b.priority - a.priority;
  if (byPriority !== 0) return byPriority;
  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
}

export function resolveSwitch(rules: SwitchRule[], context: SwitchContext): SwitchRule | undefined {
  return rules.filter((rule) => ruleMatches(rule, context)).sort(compareRules)[0];
}

export function isEnabled(rules: SwitchRule[], context: SwitchContext, fallback = false): boolean {
  const winner = resolveSwitch(rules, context);
  return winner === undefined ? fallback : winner.enabled;
}

function overlapTargets(a: string[], b: string[]): string[] | undefined {
  if (a.length === 0 && b.length === 0) return [];
  if (a.length === 0) return [...b];
  if (b.length === 0) return [...a];
  const second = new Set(b);
  const shared = a.filter((target) => second.has(target));
  return shared.length === 0 ? undefined : shared;
}

export function findConflicts(rules: SwitchRule[]): SwitchConflict[] {
  const conflicts: SwitchConflict[] = [];
  for (let i = 0; i < rules.length; i += 1) {
    for (let j = i + 1; j < rules.length; j += 1) {
      const a = rules[i];
      const b = rules[j];
      if (a.key !== b.key || a.scope !== b.scope || a.enabled === b.enabled) continue;
      const targets = overlapTargets(a.targets, b.targets);
      if (targets === undefined) continue;
      conflicts.push({ key: a.key, scope: a.scope, ruleIds: [a.id, b.id].sort(), targets });
    }
  }
  return conflicts.sort((a, b) => {
    if (a.key !== b.key) return a.key < b.key ? -1 : 1;
    if (a.scope !== b.scope) return a.scope < b.scope ? -1 : 1;
    return 0;
  });
}

export function auditSwitches(rules: SwitchRule[] = SWITCH_RULES): SwitchAudit {
  const byScope: Record<SwitchScope, number> = { global: 0, endpoint: 0, experiment: 0, user: 0 };
  let enabled = 0;
  for (const rule of rules) {
    byScope[rule.scope] += 1;
    if (rule.enabled) enabled += 1;
  }
  return {
    total: rules.length,
    enabled,
    disabled: rules.length - enabled,
    byScope,
    conflicts: findConflicts(rules),
  };
}

export type FailureKind = "timeout" | "error" | "unavailable" | "slow";

export type Criticality = "core" | "important" | "optional";

export type FallbackKind = "cache" | "static" | "none";

export type DegradeAction = "serve-cache" | "serve-static" | "retry-later" | "hide-entry" | "block-with-message";

export type DegradeInput = { failure: FailureKind; criticality: Criticality; fallback: FallbackKind };

export type DegradePlan = { action: DegradeAction; retryable: boolean; userVisible: boolean; reason: string };

export function chooseDegrade(input: DegradeInput): DegradePlan {
  const retryable = input.failure === "timeout" || input.failure === "unavailable";
  if (input.fallback === "cache") {
    return { action: "serve-cache", retryable, userVisible: true, reason: "cache-fallback" };
  }
  if (input.fallback === "static") {
    return { action: "serve-static", retryable, userVisible: true, reason: "static-fallback" };
  }
  if (input.criticality === "core") {
    return { action: "block-with-message", retryable, userVisible: true, reason: "core-no-fallback" };
  }
  if (input.criticality === "important" && retryable) {
    return { action: "retry-later", retryable, userVisible: true, reason: "important-retryable" };
  }
  return { action: "hide-entry", retryable, userVisible: false, reason: `${input.criticality}-no-fallback` };
}

export type FallbackContent = { featureId: string; title: string; body: string; actionLabel: string };

export const FALLBACKS: FallbackContent[] = [
  { featureId: "feed", title: "暂时无法刷新", body: "正在展示上次加载的内容，网络恢复后会自动更新。", actionLabel: "重新加载" },
  { featureId: "orders", title: "订单暂时不可用", body: "已提交的订单不会丢失，请稍后重试。", actionLabel: "重试" },
  { featureId: "wallet", title: "余额加载失败", body: "为保护资金安全，请确认网络后重新进入。", actionLabel: "重新进入" },
];

export function fallbackFor(featureId: string): FallbackContent {
  const registered = FALLBACKS.find((item) => item.featureId === featureId);
  if (registered !== undefined) return registered;
  return {
    featureId,
    title: "功能暂不可用",
    body: "网络恢复后会自动重试，你也可以稍后手动刷新。",
    actionLabel: "重试",
  };
}

export type FeatureFallback = { featureId: string; plan: DegradePlan; content: FallbackContent | undefined };

export function planFallback(input: DegradeInput & { featureId: string }): FeatureFallback {
  const plan = chooseDegrade(input);
  return {
    featureId: input.featureId,
    plan,
    content: plan.userVisible ? fallbackFor(input.featureId) : undefined,
  };
}

ℹ tests 27
ℹ suites 0
ℹ pass 27
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 123.109833