《互联网产品的客户端架构·规模化与架构演进》6.3 发布流水线与灰度回滚

// file: src/build/release-pipeline.ts
// tier: L1
// verify: node --test test/build/release-pipeline.test.ts

export type CheckStatus = "pass" | "fail" | "skip";

export type StageSpec = {
  id: string;
  requires: string[];
  requiredChecks: string[];
};

export type CheckOutcome = {
  stage: string;
  check: string;
  status: CheckStatus;
};

export type GateStatus = "passed" | "failed" | "blocked";

export type Gate = {
  stage: string;
  status: GateStatus;
  blockers: string[];
};

export type PipelineReport = {
  allowed: boolean;
  gates: Gate[];
  firstBlocker: string | null;
};

export type HealthMetric = "errorRate" | "crashRate" | "p95Ms";

export type HealthThresholds = Record<HealthMetric, number>;

export type HealthObservation = {
  windowMs: number;
  samples: number;
  metrics: Record<HealthMetric, number>;
};

export type HealthVerdict = {
  healthy: boolean;
  reason: "healthy" | "breach" | "insufficient-samples";
  breaches: string[];
};

export type RolloutAction = "promote" | "hold" | "rollback" | "complete";

export type RolloutDecision = {
  action: RolloutAction;
  targetPercent: number;
  reason: string;
};

export type ReleaseEvent = {
  version: string;
  artifactKey: string;
  percent: number;
  action: RolloutAction;
  at: number;
  note?: string;
};

export const HEALTH_METRICS: HealthMetric[] = [
  "errorRate",
  "crashRate",
  "p95Ms",
];

export function evaluatePipeline(
  stages: StageSpec[],
  outcomes: CheckOutcome[],
): PipelineReport {
  const observed = new Map<string, CheckStatus>();
  for (const outcome of outcomes) {
    observed.set(`${outcome.stage}\u0000${outcome.check}`, outcome.status);
  }

  const gateByStage = new Map<string, Gate>();
  const gates: Gate[] = [];
  for (const stage of stages) {
    const blockers: string[] = [];
    for (const requirement of stage.requires) {
      const gate = gateByStage.get(requirement);
      if (!gate) {
        blockers.push(`requires:${requirement}:unknown`);
      } else if (gate.status !== "passed") {
        blockers.push(`requires:${requirement}`);
      }
    }
    for (const check of stage.requiredChecks) {
      const status = observed.get(`${stage.id}\u0000${check}`);
      if (status === undefined) blockers.push(`missing:${check}`);
      else if (status === "fail") blockers.push(`fail:${check}`);
      else if (status === "skip") blockers.push(`skip:${check}`);
    }
    let status: GateStatus = "passed";
    if (blockers.length > 0) {
      status = blockers.some((item) => item.startsWith("fail:"))
        ? "failed"
        : "blocked";
    }
    const gate: Gate = { stage: stage.id, status, blockers };
    gateByStage.set(stage.id, gate);
    gates.push(gate);
  }

  const allowed = gates.every((gate) => gate.status === "passed");
  const firstBlocker =
    gates.find((gate) => gate.blockers.length > 0)?.blockers[0] ?? null;
  return { allowed, gates, firstBlocker };
}

export function validatePlan(steps: number[]): string[] {
  const errors: string[] = [];
  if (steps.length === 0) errors.push("empty");
  for (let i = 0; i < steps.length; i += 1) {
    const step = steps[i];
    if (!Number.isInteger(step) || step < 1 || step > 100) {
      errors.push(`range:${i}`);
    }
    if (i > 0 && step <= steps[i - 1]) errors.push(`order:${i}`);
  }
  if (steps.length > 0 && steps[steps.length - 1] !== 100) {
    errors.push("final");
  }
  return errors;
}

export function nextStep(steps: number[], currentPercent: number): number | null {
  for (const step of steps) {
    if (step > currentPercent) return step;
  }
  return null;
}

export function stepIndex(steps: number[], percent: number): number {
  return steps.indexOf(percent);
}

export function evaluateHealth(
  observation: HealthObservation,
  thresholds: HealthThresholds,
  minSamples: number = 100,
): HealthVerdict {
  if (observation.samples < minSamples) {
    return {
      healthy: false,
      reason: "insufficient-samples",
      breaches: [],
    };
  }
  const breaches: string[] = [];
  for (const metric of HEALTH_METRICS) {
    const value = observation.metrics[metric];
    if (value > thresholds[metric]) {
      breaches.push(`${metric}=${value}>${thresholds[metric]}`);
    }
  }
  if (breaches.length > 0) {
    return { healthy: false, reason: "breach", breaches };
  }
  return { healthy: true, reason: "healthy", breaches: [] };
}

export function decideRollout(input: {
  plan: number[];
  currentPercent: number;
  observation: HealthObservation;
  thresholds: HealthThresholds;
  minSamples?: number;
}): RolloutDecision {
  const {
    plan,
    currentPercent,
    observation,
    thresholds,
    minSamples = 100,
  } = input;
  const index = stepIndex(plan, currentPercent);
  if (index < 0) {
    return {
      action: "hold",
      targetPercent: currentPercent,
      reason: "unknown-step",
    };
  }
  const planErrors = validatePlan(plan);
  if (planErrors.length > 0) {
    return {
      action: "hold",
      targetPercent: currentPercent,
      reason: `invalid-plan:${planErrors.join(",")}`,
    };
  }
  const verdict = evaluateHealth(observation, thresholds, minSamples);
  if (verdict.reason === "breach") {
    return {
      action: "rollback",
      targetPercent: 0,
      reason: verdict.breaches.join(";"),
    };
  }
  if (!verdict.healthy) {
    return {
      action: "hold",
      targetPercent: currentPercent,
      reason: verdict.reason,
    };
  }
  if (currentPercent >= 100) {
    return {
      action: "complete",
      targetPercent: 100,
      reason: "healthy-at-full",
    };
  }
  const target = plan[index + 1];
  return {
    action: "promote",
    targetPercent: target,
    reason: `healthy:${currentPercent}->${target}`,
  };
}

export function recordRelease(
  history: ReleaseEvent[],
  event: ReleaseEvent,
): ReleaseEvent[] {
  return [...history, { ...event }];
}

export function releaseTimeline(
  history: ReleaseEvent[],
  version: string,
): ReleaseEvent[] {
  return history
    .filter((event) => event.version === version)
    .map((event) => ({ ...event }))
    .sort((a, b) => a.at - b.at);
}

export function latestRelease(
  history: ReleaseEvent[],
  version: string,
): ReleaseEvent | undefined {
  const timeline = releaseTimeline(history, version);
  return timeline[timeline.length - 1];
}

node --test test/build/release-pipeline.test.ts

✔ 非法计划时拒绝推进 (0.034042ms)
✔ 版本时间线按时间排序且只含目标版本 (0.084083ms)
✔ 追加记录不修改原数组 (0.053167ms)
✔ 最新记录取时间线末尾 (0.043458ms)
ℹ tests 26
ℹ suites 0
ℹ pass 26
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 127.875958