feature-flags

Feature Flags Skill — 特性开关

何时使用

• 想发布一个功能但能立即关闭（不重新部署）
• 灰度放量（先 1% 用户 → 10% → 50% → 100%）
• A/B 测试不同版本效果
• 给特定客户 / 内部用户开放预览
• 故障应急：紧急关闭某条线路
• 业务参数调优（库存阈值 / 限额 / 折扣率）不想发版

一、五类 Toggle（Pete Hodgson 分类）

类型	寿命	例子	清理紧迫性
Release Toggle	短（数天-周）	"新支付流程" 灰度	高 — 上线后立刻清
Experiment Toggle	中（实验周期）	A/B 测试两种结账 UI	中 — 实验结束清
Ops Toggle	长（月-永久）	"降级关闭推荐算法"	低 — kill switch 永久保留
Permission Toggle	长（永久）	"premium 用户看新报表"	低 — 业务逻辑
Kill Switch	永久	"支付通道熔断"	永久保留

核心原则：Release Toggle 必须有清理 deadline。否则代码库充满死代码，开关数指数膨胀。

二、Toggle Point 抽象

// ✅ 抽象层
interface FeatureFlags {
  isEnabled(key: string, ctx: EvalContext): Promise<boolean>
  getVariant(key: string, ctx: EvalContext): Promise<string>     // 多变体
  getNumber(key: string, ctx: EvalContext, dflt: number): Promise<number>
  getJSON<T>(key: string, ctx: EvalContext, dflt: T): Promise<T>
}

// 业务代码不直接读环境变量 / 配置文件 / Redis
if (await flags.isEnabled('new-checkout-flow', { userId, country })) {
  return newCheckoutFlow()
}
return oldCheckoutFlow()

调用点叫 Toggle Point，决策代码（取值 / targeting）叫 Toggle Router。业务代码只见 Toggle Point。

三、Targeting Rules（决策规则）

{
  "key": "new-checkout-flow",
  "default": false,
  "rules": [
    // 优先级从上到下
    { "if": { "userId": { "in": ["u_admin", "u_test1"] } }, "then": true },
    { "if": { "country": { "eq": "JP" } }, "then": false },     // 日本暂不开
    { "if": { "isPremium": true }, "then": true },              // premium 用户先开
    { "if": { "userId": { "rolloutPercentage": 10 } }, "then": true },  // 其余 10%
    { "if": { "anyOf": [...] }, "then": true }
  ]
}

Percentage rollout 的稳定性

// ❌ 错：Math.random() — 同一用户每次结果不同
function isInRollout(pct: number) {
  return Math.random() * 100 < pct
}

// ✅ 对：基于 user ID hash — 同用户始终同结果
function isInRollout(userId: string, flagKey: string, pct: number) {
  const hash = crc32(`${flagKey}:${userId}`)
  return (hash % 100) < pct
}