《互联网产品的客户端架构·交易、增长与平台化》10.1 实验分流与曝光口径

// file: src/experiment/split.ts
// tier: L1
// verify: node --test test/experiment/split.test.ts

export type UnitKind = "user" | "device";

export interface VariantDef {
  name: string;
  weight: number;
}

export interface ExperimentDef {
  key: string;
  layer: string;
  salt: string;
  unit: UnitKind;
  enabled: boolean;
  rollout: number;
  variants: VariantDef[];
}

export type AssignReason =
  | "assigned"
  | "disabled"
  | "out-of-rollout"
  | "layer-busy";

export interface Assignment {
  experiment: string;
  variant: string | null;
  bucket: number;
  reason: AssignReason;
}

const TOTAL_WEIGHT = 10_000;

// FNV-1a 32 位，跨端、跨语言都容易实现，结果只依赖输入字符串。
export function hash32(input: string): number {
  let hash = 0x811c9dc5;
  for (let i = 0; i < input.length; i += 1) {
    hash ^= input.charCodeAt(i);
    hash = Math.imul(hash, 0x01000193);
  }
  return hash >>> 0;
}

// 盐参与哈希：同一用户在 A 实验落 bucket 100，在 B 实验完全独立。
export function bucketOf(unitId: string, salt: string): number {
  if (unitId.length === 0) {
    throw new Error("分流单元不能为空");
  }
  if (salt.length === 0) {
    throw new Error("实验盐不能为空");
  }
  return hash32(`${salt}:${unitId}`) % TOTAL_WEIGHT;
}

export function validateExperiment(def: ExperimentDef): string[] {
  const errors: string[] = [];
  if (def.key.length === 0) errors.push("实验 key 不能为空");
  if (def.layer.length === 0) errors.push("实验必须声明分层");
  if (def.salt.length === 0) errors.push("实验必须声明盐");
  if (!Number.isSafeInteger(def.rollout) || def.rollout < 0 || def.rollout > TOTAL_WEIGHT) {
    errors.push("rollout 必须是 0..10000 的整数");
  }
  if (def.variants.length < 2) {
    errors.push("至少需要两个分组");
  }
  const names = new Set<string>();
  let total = 0;
  for (const variant of def.variants) {
    if (variant.name.length === 0) errors.push("分组名不能为空");
    if (names.has(variant.name)) errors.push(`分组名重复：${variant.name}`);
    names.add(variant.name);
    if (!Number.isSafeInteger(variant.weight) || variant.weight <= 0) {
      errors.push(`分组权重非法：${variant.name}`);
    } else {
      total += variant.weight;
    }
  }
  if (total !== TOTAL_WEIGHT) {
    errors.push(`分组权重之和必须为 ${TOTAL_WEIGHT}，实际 ${total}`);
  }
  return errors;
}

export function variantForBucket(variants: VariantDef[], bucket: number): string {
  if (!Number.isInteger(bucket) || bucket < 0 || bucket >= TOTAL_WEIGHT) {
    throw new Error(`bucket 越界：${bucket}`);
  }
  let upper = 0;
  for (const variant of variants) {
    upper += variant.weight;
    if (bucket < upper) {
      return variant.name;
    }
  }
  throw new Error("分组权重之和不足 10000");
}

export function assign(def: ExperimentDef, unitId: string): Assignment {
  const errors = validateExperiment(def);
  if (errors.length > 0) {
    throw new Error(errors.join("；"));
  }
  const bucket = bucketOf(unitId, def.salt);
  if (!def.enabled) {
    return { experiment: def.key, variant: null, bucket, reason: "disabled" };
  }
  if (bucket >= def.rollout) {
    return { experiment: def.key, variant: null, bucket, reason: "out-of-rollout" };
  }
  return {
    experiment: def.key,
    variant: variantForBucket(def.variants, bucket),
    bucket,
    reason: "assigned",
  };
}

// 同一层同时只允许一个实验命中：按传入顺序取第一个，其余标记 layer-busy。
// 层的价值在于让多个实验共享同一批用户而不互相污染，而不是共享同一个盐。
export function assignPlan(defs: ExperimentDef[], unitId: string): Assignment[] {
  const busyLayers = new Set<string>();
  const plan: Assignment[] = [];
  for (const def of defs) {
    const assignment = assign(def, unitId);
    if (assignment.reason === "assigned" && busyLayers.has(def.layer)) {
      plan.push({ ...assignment, variant: null, reason: "layer-busy" });
      continue;
    }
    if (assignment.reason === "assigned") {
      busyLayers.add(def.layer);
    }
    plan.push(assignment);
  }
  return plan;
}

export type ExposureStage = "render" | "visible" | "click";

export interface ExposureEvent {
  experiment: string;
  unitId: string;
  variant: string;
  stage: ExposureStage;
  at: number;
}

export function exposureKey(experiment: string, unitId: string): string {
  return `${experiment}\u0000${unitId}`;
}

// 曝光只报一次：先到的阶段决定记录，后续 visible/click 只做本地计数。
export class ExposureLog {
  private seen = new Set<string>();
  private events: ExposureEvent[] = [];

  record(event: ExposureEvent): boolean {
    const key = exposureKey(event.experiment, event.unitId);
    if (this.seen.has(key)) {
      return false;
    }
    this.seen.add(key);
    this.events.push({ ...event });
    return true;
  }

  size(): number {
    return this.events.length;
  }

  list(): ExposureEvent[] {
    return this.events.map((event) => ({ ...event }));
  }

  clear(): void {
    this.seen.clear();
    this.events = [];
  }
}

$ node --test test/experiment/split.test.ts
✔ 哈希在小样本上保持稳定 (1.059125ms)
✔ 不同实验盐让同一用户落到不同桶 (0.089833ms)
✔ bucket 始终落在 0..9999 (0.11925ms)
✔ 同一用户重复分流得到相同分组 (0.484459ms)
✔ 权重边界决定分组 (0.068667ms)
✔ bucket 越界时拒绝分组 (0.221542ms)
✔ 灰度比例之外不返回分组 (0.080833ms)
✔ 实验关闭后不返回分组 (0.065375ms)
✔ 同一层第二个命中的实验让位 (0.105875ms)
✔ 不同层可以同时命中 (0.105625ms)
✔ 分组权重之和必须是 10000 (0.120042ms)
✔ 分组名重复与 rollout 越界被拒绝 (0.064791ms)
✔ 空用户或空盐不允许分流 (0.070959ms)
✔ 曝光键只由实验与用户决定 (0.04075ms)
✔ 同一用户同一实验只记录一次曝光 (0.094416ms)
✔ 不同实验或不同用户分别记录 (0.062ms)
✔ 清空后可以重新记录曝光 (0.084875ms)
ℹ tests 17
ℹ suites 0
ℹ pass 17
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 159.841375