feature-flag-guide

功能标志指南技能

为服务或团队编写一份完整的功能标志管理指南，涵盖标志如何命名和分类、如何安全地创建和发布标志、发布期间要监控什么、何时以及如何清理标志，以及各阶段由谁负责。缺乏规范的功能标志会变成永久的技术债务。本指南为团队提供一套可重复的流程，确保有意创建标志、安全地发布，并在完成后移除。

必需输入

如果尚未提供，请询问以下信息：

• 服务或团队名称 — 指南的适用范围
• 功能标志平台 — LaunchDarkly、Split、Unleash、Flagsmith、Flipt 或自定义／内部解决方案
• 要记录的标志（如果编写的是单个标志的指南），或“通用指南”（如果编写的是团队级政策）
• 发布限制 — 关于谁可以看到某项功能的合规、数据隐私或合同限制（例如 HIPAA、仅限欧盟、仅限企业客户）

输出格式

---

功能标志管理指南：[服务／团队名称]

团队： [团队名称] | 平台： [LaunchDarkly / Split / Unleash / Custom] 文档负责人： [姓名] | 最后更新： [日期] 审查周期： 每季度一次，以及功能标志平台发生变更时

---

1. 标志分类

每个标志只能属于一个类别。类别决定默认行为、谁可以在生产环境中启用它，以及何时必须清理它。

类型	用途	默认状态	生产环境审批要求	最长存续时间
发布标志	控制新功能的发布 — 将部署与发布解耦	关闭	技术负责人批准	功能上线后 90 天
实验标志	A/B 或多变量测试 — 衡量变更的影响	关闭（对照组）	产品负责人 + 技术负责人	实验持续时间 + 30 天
运维标志	运维控制 — 熔断器、紧急开关、限流	开启（正常行为）	值班工程师可切换	无限期（每年审查）
权限标志	按用户群体、层级或地区限制访问	关闭（受限）	产品负责人 + 客户负责人	无限期（每年审查）

不确定时： 如果标志是临时的（与特定功能发布相关），则属于发布标志。如果它将作为控制开关永久存在，则属于运维标志。

---

2. 标志命名规范

所有标志必须遵循以下命名方案：

[type]-[service]-[feature-description]

部分	值	示例
类型	release、exp、ops、perm	release
服务	服务的简短标识符，使用小写字母和连字符	payments
功能描述	以连字符分隔的描述，最多 5 个单词	new-checkout-flow

完整示例：

• release-payments-new-checkout-flow — payments 服务中新结账功能的发布标志
• exp-search-personalized-ranking — 个性化搜索排名实验
• ops-api-rate-limit-override — 用于覆盖 API 速率限制的运维标志
• perm-dashboard-beta-users-only — 限制仅测试版用户访问仪表板的权限标志

不要：

• 在标志名称中使用工单编号（release-JIRA-1234 → 不便搜索，也无法自我说明）
• 在标志名称中使用日期（release-dark-mode-jan-2024 → 标志的存续时间可能超过对应日期）
• 使用含糊的名称（release-new-thing → 当你有 50 个标志时毫无用处）

---

3. 标志创建检查清单

在生产环境中创建标志之前，必须完成所有项目。

创建标志之前：

• 根据分类确定标志类型（第 1 节）
• 标志名称符合命名规范（第 2 节）
• 指定标志负责人 — 由一名明确的工程师负责清理
• 在标志描述字段中设置清理日期（适用于发布标志和实验标志）
• 制定发布策略 — 参见第 4 节
• 制定监控计划 — 参见第 5 节
• 代码评审已批准，且已设置标志保护逻辑

标志描述字段（必填）：

Type: [Release / Experiment / Ops / Permission]
Owner: [Name]
Linked ticket: [JIRA-XXXX or GitHub issue URL]
Purpose: [One sentence — what this flag controls]
Cleanup by: [Date — required for Release and Experiment flags; "Annual review" for Ops/Permission]
Rollout plan: [Link to this document or inline summary]

代码要求：

# Good — behaviour is clear when flag is off, and cleanup is obvious
if flag_client.is_enabled("release-[service]-[feature]", user_context):
    return new_feature_handler(request)
else:
    return existing_handler(request)

# Bad — nested flags, ternaries, and implicit defaults make cleanup error-prone
result = new_handler() if (f1 and not f2) or f3 else old_handler()

---

4. 发布策略

决策树

使用此决策树，为 Release 或 Experiment 标志选择合适的发布策略：

Is the change reversible without a deploy?
├── No → Use an Ops flag with manual enable, not a percentage rollout
└── Yes → Continue

Is there a user-level identifier available (user ID, session ID)?
├── No → Use server-side percentage (stateless, but inconsistent per user)
└── Yes → Use user-based percentage (consistent experience per user) ← preferred

Is the change risky (touches payments, auth, or data writes)?
├── Yes → Start at 1% → 5% → 25% → 50% → 100%, with 24-hour holds
└── No → Start at 10% → 50% → 100%, with 4-hour holds

Does the change affect specific customer tiers or geographies?
├── Yes → Use segment-based targeting, not percentage rollout
└── No → Use percentage rollout

发布阶段

阶段	百分比	保持时长	推进前的通过标准
金丝雀发布	1%	24 小时	错误率符合 SLO，且没有 P1 事故
早期发布	5–10%	24 小时	错误率和延迟与对照组一致
部分发布	25–50%	24–48 小时	业务指标相较于对照组未退化
大多数用户	75%	24 小时	最终检查——没有回归
全量发布	100%	48 小时	稳定——安排清理工作

**生产环境中的 Release 标志不得跳过阶段。**发布速度不值得以生产事故为代价。

基于分群的定向

如果发布范围必须受到限制，请使用分群定向：

# LaunchDarkly segment example — adapt for your platform
targeting_rules:
  - clause:
      attribute: "subscription_tier"
      operator: "in"
      values: ["enterprise", "team"]
    serve: "on"
  - clause:
      attribute: "country"
      operator: "in"
      values: ["US", "CA", "GB"]
    serve: "on"
  default: "off"

---

5. 监控要求

凡是发布比例不为 0% 或 100% 的标志，都需要主动监控。不要发布标志后就置之不理。

每个标志必需的指标

指标	比较对象	告警阈值
错误率	启用标志的群组与未启用标志的群组	启用标志的群组中，错误率超过基线的 2 倍
p99 延迟	启用标志与未启用标志	启用标志的群组中，延迟高出 20% 以上
[主要业务指标]	启用标志与未启用标志	启用标志的群组中，指标退化超过 5%
[转化率／完成率]	启用标志与未启用标志	启用标志的群组中，指标下降超过 2%

在 [LaunchDarkly / Split / Datadog] 中设置分组指标监控：

1. Navigate to the flag → Metrics tab
2. Add metric: [primary business metric]
3. Add metric: error_rate (service-level)
4. Add metric: p99_latency (endpoint-level)
5. Set alert: notify [flag owner] in Slack #[team-channel] if metric degrades by [threshold]
6. Set experiment duration: [N days] if this is an Experiment flag

护栏指标

无论主要指标表现如何，这些指标都不得退化。如果触发护栏，请立即回滚——不要等待调查结果。

• 错误率超过 SLO 阈值（[X]%）
• p99 延迟超过 SLO 阈值（[Y] 毫秒）
• [服务专属护栏——例如支付失败率、身份验证失败率]

触发护栏时的立即回滚命令：

# [LaunchDarkly CLI]
ld-cli flag update [project-key] [flag-key] --default-variation off

# [Split CLI]
split-cli update-treatment [flag-name] --treatment "off" --percentage 100

# [Unleash CLI / API]
curl -X POST https://[unleash-host]/api/admin/features/[flag-name]/disable \
  -H "Authorization: [admin-token]"

# [Custom — adapt to your implementation]
[command or dashboard step]

---

6. 标志创建模板

创建新标志时，将此模板复制到标志的描述字段和关联工单中：

## Flag: [flag-name]

**Type:** [Release / Experiment / Ops / Permission]
**Owner:** [Name] ([Slack handle])
**Created:** [Date]
**Cleanup by:** [Date]
**Linked ticket:** [URL]

### Purpose
[One paragraph: what this flag controls, why it exists, what "on" and "off" mean]

### Rollout Plan
| Stage | Target | Date | Approved by |
|---|---|---|---|
| Canary | 1% | [Date] | [Name] |
| Early | 10% | [Date] | [Name] |
| Partial | 50% | [Date] | [Name] |
| Full | 100% | [Date] | [Name] |

### Monitoring
- Primary metric: [metric name and dashboard link]
- Guardrail metrics: error rate < [X]%, p99 < [Y] ms
- Alert channel: #[team-channel]

### Rollback Procedure
[Exact steps to turn the flag off in an emergency — should take < 2 minutes]

### Cleanup Checklist
- [ ] Flag at 100% for 48+ hours with no incidents
- [ ] Code path for flag-off branch removed from codebase
- [ ] Flag deleted from [platform]
- [ ] Ticket closed

---

7. 紧急终止开关流程

生产事故发生时，如果需要立即禁用标志：

目标时间：在做出决定后的 2 分钟内禁用标志。

1. Go to [platform URL] — bookmark this: [URL]
2. Search for the flag by name: [flag-name]
3. Set to 0% / "off" for ALL users
4. Verify the service error rate drops within 60 seconds
5. Post to #incidents:
   "🟡 Feature flag [flag-name] disabled — rolling back [feature description].
    Owner: [name]. Error rate before: [X]%. Monitoring for recovery."
6. Page the flag owner if not already aware

对于运维标志（必须关闭正常开启行为的终止开关）：

# These flags are "on" by default and turned "off" to disable a feature
# Confirm the flag polarity before toggling — "off" may mean "disabled" or "enabled" depending on naming
# Flag [flag-name]: OFF = [feature behaviour when off]
[kill switch command for your platform]

---

8. 过期标志策略与清理

过期标志是指发布比例为 100%、达到 100% 已超过 48 小时，或已过清理日期的标志。过期标志属于技术债务。

过期标志的定义

符合以下任一条件的标志即为过期：

• Release 标志已过清理日期
• 发布比例处于 100%（或 0%）已超过 30 天
• 关联工单已关闭，但代码尚未清理
• 负责人已离开团队

清理清单

[ ] Flag is at 100% rollout and has been stable for 48+ hours
[ ] Monitoring shows no issues for the flag-on cohort
[ ] Code changes:
    [ ] Remove the flag check from application code
    [ ] Remove the "off" code path entirely — do not leave dead code
    [ ] Remove any flag-related tests that test the off behaviour
    [ ] Update any documentation that references the flag
[ ] PR merged and deployed to production
[ ] Flag deleted from [platform] (do not just disable — delete)
[ ] Cleanup ticket closed
[ ] Flag owner confirms cleanup in Slack: "Flag [name] has been cleaned up — [commit link]"

自动检测过期标志：

# Run weekly — flags past cleanup date or at 100% for > 30 days
# [Platform-specific query — adapt:]

# LaunchDarkly API
curl -s "https://app.launchdarkly.com/api/v2/flags/[project-key]" \
  -H "Authorization: [api-key]" | \
  jq '.items[] | select(.creationDate < (now - 2592000) * 1000) | {key: .key, created: .creationDate}'

# Notify #engineering-housekeeping with list of stale flags

过期标志升级处理

超过清理日期的时长	操作
0–14 天	在 Slack 中提醒标志负责人
14–30 天	在 Slack 中提醒标志负责人和技术负责人
30 天以上	技术负责人安排清理，并创建优先级为 P2 的工单
60 天以上	工程经理审核——标志可能会被强制删除

---

9. 治理

权限说明

操作	执行者	所需审批
创建标志（任何环境）	任何工程师	无——但必须完成创建清单
在开发环境启用标志	任何工程师	无
在预发布环境启用标志	任何工程师	无
在生产环境启用标志（0–10%）	标志负责人	告知技术负责人
推进生产环境中的发布比例（10–100%）	标志负责人	每个阶段均须获得技术负责人批准
在生产环境启用 Ops 标志	值班工程师	无——这些是紧急破窗控制项
删除标志	标志负责人	技术负责人确认代码已清理
创建 Permission 标志	标志负责人	产品经理批准

审计日志

生产环境中的所有标志变更都必须可追溯。确保已在 [platform] 中配置以下内容：

• 变更日志： 每次生产环境中的标志变更都要记录：谁进行了更改、改了什么，以及何时更改。
• Slack 通知： 生产环境中的标志变更会自动发布到 #[team]-flag-changes。
• 季度审查： 每季度，技术负责人都会审查完整的标志清单，确认负责人信息仍然有效，并移除没有负责人的标志。

---

质量检查

• 每个标志的描述中都注明了负责人——不存在无人负责的标志
• Release 和 Experiment 标志都设置了清理日期——没有无期限的标志
• 所有当前处于 1–99% 灰度发布的标志都配置了监控
• 已测试紧急 kill-switch 流程——值班工程师已收藏平台 URL 并了解操作步骤
• 自动运行过时标志检测，并每周审查检测结果
• 代码审查清单包含：“此 PR 是否引入了标志？如果是，标志创建检查清单是否已完成？”
• 至少有一位非标志负责人知道如何在紧急情况下禁用任意标志

反面模式

• 不要创建没有清理日期的发布标志——没有到期日期的标志会悄然积累，变成永久技术债务，直至代码库无法维护
• 不要跳过对处于 1–99% 灰度发布的标志配置监控——没有指标对比的部分发布标志，就像没有传感器的风险
• 不要在其他标志中嵌套标志——复合标志逻辑会让清理几乎不可能，并产生无法测试的代码路径
• 标志负责人离开团队时，不要不重新分配负责人——无人负责的标志永远不会得到清理
• 不要将功能标志用作永久配置系统——处于 100% 或 0% 状态超过 30 天的标志必须清理；将标志用作永久配置会使业务逻辑与功能标志平台耦合