feature-flagging

功能标志

一份资深工程师指南，教你如何正确使用功能标志，而不只是频繁使用。

功能标志是基础设施。将其视为基础设施，它们就能在无需重新部署的情况下实现紧急关闭开关、逐步发布、A/B 实验、权限门控和运维开关。若随意使用，它们就会成为代码库中不断累积的最大技术债务：成千上万个失效标志、相互冲突的评估逻辑、脆弱的定向规则，以及无人能完全理解的权限范围。

这项技能旨在避免第二种结果。它假设你已有一个功能标志平台（LaunchDarkly、Flagsmith、Split.io、VWO FME、GrowthBook、Statsig、PostHog、Optimizely；平台本身并不影响这些原则）。它还假设你的工程团队能够实现定向规则并集成 SDK。难点在于运维纪律，而本指南讲的正是这一点。

使用此技能的时机：任何准备引入或修改标志、审查现有标志，或设计标志相关治理政策的时候。

---

此技能的用途

此技能涵盖标志从创建到退役的运维生命周期。标志类型，以及避免混用的纪律。经得起代码审查的命名规范。创建时就确立、而非事后补上的生命周期要求。能够灵活组合且不易出错的定向规则。与发布风险相匹配的发布策略。按季度节奏管理过期标志。兼顾访问权限与审计的治理机制和权限设置。避免标志成为延迟负担的性能考量。覆盖两个分支的测试模式。回滚纪律。贯穿发布过程的可观测性。

此技能不涵盖实验设计；关于假设撰写、样本量、MDE，以及如何严谨地得出可靠结论，请参阅 experiment-design 技能。它不涵盖统计分析或方差缩减；这些内容属于 experimentation-analytics 技能。它不涵盖特定平台的工具；关于 MCP 命令、身份验证和特定平台配置，请查阅所选平台的文档。此技能定义运维规范，平台负责实现这些规范。

---

五种标志类型

混用标志类型是大多数标志混乱的根源。标志有五种类型；创建时就要确定类型，不要让它偏离原本用途。

发布标志。 代码已部署到生产环境，但处于禁用状态。新功能以关闭状态发布，然后按比例逐步开启，最终达到 100%。生命周期：较短，几天到几周。生命周期管理：发布后清理移除。常见名称前缀：release_。

实验标志。 用户被随机分配到不同变体；系统会衡量转化率。标志控制用户看到哪个变体。生命周期：中等，一到六周。生命周期管理：选定变体后，合并代码路径并移除标志。常见名称前缀：exp_。

运维标志。 一种紧急开关或断路器，允许运维人员在不重新部署的情况下禁用出问题的功能。生命周期：长期，通常为数年。生命周期管理：通常永不移除；保留为备用开关。常见名称前缀：ops_。

权限标志。 按套餐等级、客户群组或区域控制功能访问权限。免费套餐用户看到一组功能，企业套餐用户看到另一组。生命周期：长期。生命周期管理：与计费和访问基础设施一并管理。常见名称前缀：perm_。

配置标志。 让部分客户根据合同配置看到不同的行为，例如白标租户、受监管区域，或为各账户定制的发布计划。生命周期：长期。生命周期管理：由销售和产品协议约束。常见名称前缀：cfg_。

每种类型的生命周期、治理方式和移除预期都不同。将它们混用在一个标志中（这个标志既是紧急开关，又是权限门控，现在还要用于实验），是标志混乱最常见的来源。当标志用途发生变化时，请创建新标志并迁移。不要让现有标志承担过多用途。

---

标志命名规范

标志名称应编码类型、所有者和用途。缺少这些信息，到了第 9 个月，标志列表就会变得难以理解，而且 references/stale-flag-cleanup-playbook.md 中的清理指南也无法判断哪些标志可以安全移除。

本技能推荐的规范是 <type>_<owner>_<semantic_name>_<version_or_date>：

• release_checkout_redesign_2026q2
• exp_billing_pricing_v2
• ops_search_circuit_breaker
• perm_enterprise_audit_log
• cfg_tenant_acme_custom_dashboard

选择 snake_case 或 kebab-case 之一，在整个组织内统一使用。平台中混用两种格式会导致由拼写错误引发的故障，凌晨 3 点就会让人头疼。含糊的名称会逐渐失去作用：new_feature、temp_toggle、test_flag、pricing_update_v3。几个月后，就没人知道哪个 pricing_update 已经发布，哪个已经废弃。

如需更深入的内容，包括类型前缀表、所有者规范，以及为现有命名不当的标志制定的迁移计划，请参阅 references/flag-naming-conventions.md。

---

标记的生命周期

每个标记都有五个生命周期阶段。每个阶段都有明确的进入和退出标准。跳过阶段会导致标记混乱不断累积。

诞生。 创建标记时附上明确的元数据：负责人、类型、目标移除日期（针对发布和实验标记）、发布计划、监控方式。元数据不可缺少；没有它，标记就没有生命周期终点。

成长。 正在构建标记背后的功能。代码中同时存在禁用分支（当前生产环境使用的分支）和启用分支（新分支）。两者都经过测试。标记在生产环境中仍保持关闭。

发布。 开始在生产环境中逐步发布。初始比例较低（1% 或 5%），每一步都要监控，指标稳定后再提高比例。发布门槛记录在 references/flag-rollout-strategies.md 中。

成熟。 标记已达到 100% 的发布比例。新代码路径已成为生产路径。至少继续监控 30 天，以发现发布过程中未显现的问题。

终止。 从代码中移除标记（通过 PR 删除门控逻辑），并从平台中移除。审计记录会记载此次移除。

其中的不对称之处在于：诞生很快（一个 PR 就能创建标记并为新代码添加门控），而终止需要有意识地进行清理。大多数标记混乱都源于未完成的终止。诞生和终止必须一并规划；终止计划是诞生时元数据的一部分。

各阶段的检查清单见 references/flag-lifecycle-checklist.md。

---

定向规则与细分

定向规则是一个布尔表达式，用于决定用户、账户或请求是否采用处理分支。有四种实用的定向维度：

• 用户属性。 user.email_domain == "acme.com"、user.signup_date > "2026-01-01"、user.plan == "enterprise"。
• 账户属性。 account.tier == "enterprise"、account.region == "EU"、account.feature_x_enabled == true。
• 请求属性。 request.country == "US"、request.device_type == "mobile"、request.api_version >= 3。
• 基于时间。 time > "2026-06-01T00:00:00Z"、time < "2026-12-31T23:59:59Z"。

使用 AND、OR 和 NOT 组合。表达式应保持简单。如果规则需要三层嵌套子句，说明你的分类体系有误。可以定义一个细分（具有共同属性的用户命名组）并定向到该细分，或者拆分为多个标记。

最常见的陷阱：根据频繁变化的属性进行定向。如果规则是 user.last_login_date > "2026-04-01"，那么某位用户在 5 月 1 日登录后会看到处理版本；次日该属性值发生变化，用户又会看到对照版本。用户体验会因此反复摇摆。易变属性应放在基于快照计算的细分中，而不是实时定向规则中。

模式目录和反模式见 references/targeting-rule-patterns.md。

---

发布策略

不同的发布适合不同的发布策略。根据风险状况选择策略。

百分比发布。 发布标志的默认策略。从 1% 或 5% 开始。至少观察一个高峰小时的错误率、延迟和主要成功指标。如果没有问题，将比例提高到 10%。继续观察。然后提高到 25%、50%，最后达到 100%。总耗时取决于流量，但典型模式是：1% 持续一天，然后 10% 持续两天，再到 50% 持续两天，最后达到 100%。在不到四小时内完成的生产环境发布通常推进得太快。

群组发布。 先面向内部员工，再面向测试版客户，然后是免费层级，最后是付费用户。每个群组都是一个具名细分群体；标志会依次在这些群组间推进。适用于影响范围比发布速度更重要的高风险发布。

按地域分阶段发布。 一次发布一个区域。适用于对合规敏感的功能（数据驻留、监管披露、特定区域的用户体验）。结合平台的区域定位能力使用，这样就不必手动编写规则。

按时间发布。 在已知时间定时切换。适用于需要在特定时刻触发开关的营销协同发布。注意时区：美东时间午夜并非 UTC 午夜。除非安排了周末值班覆盖，否则避免在节假日进行按时间发布。

“逐步提升并观察”规则：每次提高百分比后，至少监控系统一个高峰小时再继续。高峰小时是任何新故障模式发生率最高的时段；如果系统在高峰时稳定运行一小时，就可以安全地进入下一阶段。如果在非高峰时段推进，并立即继续提高比例，就没有真正测试这项变更。

如需了解完整策略详情，以及结账流程改版的完整示例，请参阅 references/flag-rollout-strategies.md。

---

过期标志管理

每个在线标志都会增加运行时成本：评估开销、需要维护的两条代码路径，以及工程师阅读代码时的认知负担。一个标志没问题。两百个失效标志则会不断累积，成为生产力负担。

大多数平台都支持过期标志报告：列出过去 N 天未评估的标志。默认阈值为：发布标志和实验标志 30 天，运维标志和权限标志 90 天。一个标志 30 天未被评估，说明它要么已在生产环境中退役（定位规则中没有用户），要么在代码中已彻底失效（门控调用已移除，但标志本身一直没有删除）。

清理流程是固定的：

1. 从平台生成过期标志报告。
2. 对每个标志：确认负责人、上次评估时间、类型和建议操作。
3. 在季度会议上分类处理：保留、删除或调查。
4. 每个标志单独提交一个用于移除代码的 PR。每个 PR 各自审查都可行；把十个合并在一起则不行。
5. PR 合并后，从平台删除标志。

清理不会自动发生的原因是：移除标志属于代码变更，需要经过审查、测试和部署，都会带来额外开销。PM 不会因此给予奖励（功能已经发布）。SRE 最终会受够这些噪音。解决办法是将移除工作纳入发布检查清单，而不是作为单独的工作。当创建标志时，就在元数据中记录移除日期。发布工单中安排一个 30 天后的后续子工单，内容为“移除标志 X”。如果发布顺利，这个子工单就会完成。

如需了解完整的季度节奏，包括孤立标志的负责人轮换机制，请参阅 references/stale-flag-cleanup-playbook.md。

---

治理和权限

不同角色需要不同的访问权限。工程团队可以广泛创建标志。产品团队可以在开发和预发布环境中编写定向规则。影响生产环境的定向变更应由更小范围的审批人员负责。

建议的权限级别：

• 查看者。 在所有环境中只有只读权限。包括大多数工程、产品和支持人员。
• 编辑者。 可以在开发和预发布环境中创建和修改标志。包括负责该标志的团队。
• 审批者。 可以将标志变更从预发布环境推送到生产环境。人员范围更小，通常包括团队负责人和当班工程师。
• 管理员。 拥有完全控制权，包括删除标志、修改权限和访问审计日志。人员范围最小，包括平台团队及一名备份人员。

影响生产环境的标志变更应像部署一样经过评审，而不是在聊天中决定。变更请求应说明规则差异、发布计划和中止条件。审批者在评审后应用变更；规则不会因为有人点击按钮就悄无声息地出现在生产环境中。

审计记录：记录每次标志变更的操作者、时间戳、变更前后的规则以及原因。大多数平台都支持此功能；请配置为将记录写入中央日志聚合器，与其他基础设施事件一起保存。

环境晋级：规则先在开发环境中测试，再晋级到预发布环境，最后晋级到生产环境。直接在生产环境中编写规则，会跳过预发布测试和评审关卡。请将其视为一次部署：开发环境 → 预发布环境 → 生产环境，并在每个阶段执行相同的评审和审批流程。

紧急覆盖：凌晨 3 点，谁能触发紧急关闭开关？请记录相关流程，在事故演练中进行测试，并确认覆盖路径确实可用。没人知道在哪里找的紧急关闭开关，就形同虚设。

---

标志依赖和冲突

标志交互会导致两种故障：

依赖。 标志 B 的代码路径要求标志 A 处于开启状态。大多数平台都难以对此建模；SDK 不知道标志之间存在这种关系。应尽可能避免；如果确实需要表达这种关系，请在标志说明中记录，并添加一个单元测试，确保当 A 关闭而 B 开启时测试失败。

冲突。 两个标志针对同一界面，后写入的值生效。结果取决于评估顺序，而评估顺序取决于 SDK 实现，进而取决于平台内部机制。通过共享键审计来检测：任何两个定向规则在同一代码路径上有重叠的标志，都可能存在冲突。平台通常不会标记这种情况；团队必须自行审计。

跨团队冲突是危险的一种情况：Alpha 团队用于结账页面改版的发布标志，与 Bravo 团队在定价页面上的实验发生交互。直到生产环境中的用户看到界面故障，大家才会发现这种交互，因为两个标志都已触发。解决方法是通过 experiment-design 中描述的实验注册表提前协调。在发布前通过规划发现问题，而不是等到凌晨 2 点事故发生后才发现。

对于互斥的实验组（平台会强制确保用户只能进入测试 A 或测试 B，不会同时进入两者），请参阅 experiment-design 技能中有关互斥执行的内容。

---

性能注意事项

标志评估是一次函数调用（开销很小），加上可能发生的一次平台网络调用（开销很大）。性能问题的关键在于，你在后者上花费了多少。

积极使用缓存。大多数服务端 SDK 会按请求、会话或用户缓存标志值；请配置缓存，确保网络调用在每个相关范围内只发生一次，而不是每次检查标志时都发生。一个请求评估 50 个标志时，应在请求开始时访问平台一次，而不是 50 次。

批量评估：大多数平台都支持在一次调用中评估某个用户或上下文的所有标志。请使用此功能。“单独检查 50 个标志”的延迟开销是单次检查开销的 50 倍；“一次批量评估并返回全部 50 个标志”的延迟开销则是一次往返，再加上每次检查时快速查找的开销。

SDK 选择：对于对延迟、安全性和新鲜度有要求的敏感逻辑，通常优先使用服务端 SDK，而不是客户端 SDK。对于用户无论如何都能在 DevTools 中看到标志值的纯 UI 行为，可以使用客户端 SDK。混用两者会导致不一致；如果用户在服务端和客户端获取到不同的标志值，UI 就会出问题。

延迟预算：在典型情况下，每个请求评估 50 个标志增加的耗时不应超过 5 ms。如果耗时更长，说明 SDK 配置不当（没有缓存、没有批量评估、在热点循环中进行评估）。请在扩展规模之前进行审查。

---

测试受标志控制的代码

两个分支都需要测试。禁用分支是现有的生产行为；启用分支是新代码。单元测试应在测试设置中显式覆盖标志，以测试这两个分支。

测试状态转换。用户在会话中途遇到标志值变化时会怎样？在大多数运行良好的系统中，用户会用请求开始时的标志值完成当前请求，然后在下一个请求中看到新值。请明确记录这一假设。如果系统在会话中途切换用户的标志值，通常属于错误。

使用标志覆盖进行集成测试：大多数平台都支持仅用于测试、不影响生产环境的标志覆盖。请将其用于覆盖两个分支的端到端测试。如果没有测试覆盖，集成测试就必须共用生产环境的标志配置，这意味着你无法测试仍在生产环境中关闭的新功能。

常见问题：上线了一个“效果显著”的实验，但只有测试环境配置了正确的定向规则。测试环境通过宽松规则放行了 100％ 的测试用户；生产环境的规则更严格，只放行 20％。你测得的提升无法在生产环境中复现。可通过分阶段发布来发现这一问题：生产环境中首批 1％ 的用户应当与测试结果相符，然后再继续扩大范围。

---

回滚规范

标志可用于快速回滚受其控制的变更，但不能替代代码回滚。如果代码中发布了未受标志控制的错误（例如对现有路径的修复，或同一次部署中的无关变更），切换标志不会有任何效果。应将标志回滚视为多种工具之一，而不是唯一的工具。

如果切换标志确实有效，请记录回滚过程。如果无效，问题出在未受标志控制的代码或标志依赖项中。请据此诊断，不要认定是标志失效。

速度很重要。在生产环境中切换标志需要多快？目标是通过 UI 或 MCP 在 60 秒内完成，通过 API 加身份验证在 5 分钟内完成。如果平台需要 15 分钟才能传播标志变更，这就是实际的事故响应限制，团队应当了解。

进行演练。将标志回滚纳入事故演练。第一次切换紧急开关不该是在凌晨 3 点、收入正在下滑的时候；而应是在大家都从容的演练中。

---

标志的可观测性

将标志评估与其他请求数据一起记录日志。评估时的标志值会作为上下文字段写入请求日志。调查缓慢请求或错误时，日志会显示当时启用的标志值。

监控标志评估速率变化并触发告警。如果某个标志的评估速率突然下降，说明规则配置有误（没有匹配的用户），或 SDK 出现故障。无论哪种情况，团队都应在几分钟内收到通知。

为生产环境的逐步发布构建仪表板。按地区、套餐、设备等维度细分，查看看到实验组与对照组的用户百分比。没有仪表板，逐步发布就是黑箱；有了仪表板，团队无需编写 SQL 查询，就能回答“我们是否真的在各个细分群体中均匀发布？”

连接到错误追踪系统。逐步发布期间错误激增时，仪表板应显示错误是否与标志值相关。实验组分支上的错误激增 = 回滚标志。两个分支上的错误都激增 = 问题无关，回滚标志也无济于事。

---

常见故障（快速排查）

简短的模式目录。详情见 references/。

• “我们已经发布，但 90 percent 的用户仍看到旧版本”意味着发布规则有误。根据实际用户属性审查规则。
• “我们禁用了标志，但错误仍在发生”意味着受影响的代码路径未受标志控制，或存在缓存值，或某个依赖标志仍处于启用状态。
• “我们有 400 个失效标志，移除它们风险太大”意味着一直没有进行清理。现在就开始按季度清理；每个标志提交一个 PR。
• “两个标志针对同一代码路径，我们不知道哪个优先生效”意味着存在冲突。审查共享键，确定其中一个为规范标志，并退役另一个。
• “我们的标志评估器导致延迟激增”意味着缺少批量评估或缓存。审查 SDK 配置。
• “我们需要让财务团队访问功能开关，但他们不应更改生产规则”意味着需要分级授权。财务团队设为查看者，负责团队设为编辑者，团队负责人设为审批者。

---

框架：可持续功能标志管理的 14 项考量

设计或审查功能标志时，请逐项检查以下 14 项考量：

1. 类型明确。 发布、实验、运维、权限或配置。在创建时选定一种类型；不要随意变更。
2. 命名。 带类型前缀、负责人前缀和语义化名称。避免含糊不清。
3. 生命周期规划。 创建时就确定启用和退役时间。将移除日期写入元数据。
4. 定向分类体系。 按用户、账户、请求或时间进行定向。避免使用易变属性。
5. 规则简洁。 仅使用 AND、OR、NOT。嵌套三层子句说明分类体系有误。
6. 发布匹配。 发布策略应与风险状况相匹配。低风险使用百分比，中风险使用群组，合规要求使用地理位置，协调发布使用基于时间的策略。
7. 渐进发布纪律。 每个百分比阶段都要覆盖一个高峰时段。不要在四小时内完成发布。
8. 过期标志清理周期。 按季度清理。每次移除提交一个 PR。将移除纳入发布检查清单。
9. 分级授权。 查看者 / 编辑者 / 审批者 / 管理员。管理员人数应少于审批者，审批者人数应少于编辑者。
10. 环境晋级。 经审核关卡从开发环境晋级到预发布环境，再到生产环境。不得在生产环境中创建生产规则。
11. 冲突审查。 两个标志作用于同一界面 = 冲突。通过共享键审查进行检测；通过实验注册表协调跨团队工作。
12. 性能预算。 批量评估、缓存，以及用于敏感逻辑的服务端 SDK。50 次标志检查的总预算为 5 ms。
13. 分支测试。 测试应覆盖两个代码路径，并记录状态转换行为。
14. 可观测性。 记录每次标志评估。为每次逐步发布构建仪表板。事件期间，将错误与标志值关联分析。

---

如果所需数据不可用

此技能的输出依赖于其自身无法生成的数据、测量结果或工具结果。如果所需输入、工具或数据源不可用或无法验证，合规的输出应是交付内容，并明确说明缺口：需要什么、实际获取或验证了什么，以及输出的哪些部分受到影响。绝不可通过捏造、估算或插值所需数值来完成交付。明确说明缺口就是完整的答复。

---

参考文件

以下参考文件扩展了此技能：

• references/flag-naming-conventions.md：类型前缀、所有者前缀、语义命名模式，以及现有命名不当的标志的迁移计划。
• references/flag-lifecycle-checklist.md：按生命周期阶段组织的从创建到废弃的检查清单。
• references/flag-types-reference.md：详细介绍五种标志类型，包含示例和常见陷阱。
• references/stale-flag-cleanup-playbook.md：季度清理流程和孤立所有权模式。
• references/targeting-rule-patterns.md：定向规则的常见模式和反模式。
• references/flag-rollout-strategies.md：百分比、群组、地理位置、基于时间和组合策略，并附有示例。
• references/governance-and-permissions.md：权限层级、环境晋级、审批工作流和紧急覆盖。

---

结语：何时移除标志

默认情况下，任何标志都应移除。能在代码库中永久保留的标志（运维熔断开关、与计费相关的权限标志、与合同相关的配置标志）是例外，而非常态。大多数发布和实验标志都应在发布决策后 30 天内移除。

保留这些标志的代价确实存在：每个失效标志都意味着要维护两条代码路径、保持两套测试套件通过，并给下一季度读文件的工程师增加一行心智负担。数百个标志累积起来，代价会不断增加。

移除标志这项纪律，体现了你对下个季度将要使用的代码库的用心。这与部署后清理、移除失效导入，以及在事故发生后一周内撰写复盘报告，遵循的是同一项纪律。这些工作没有一项能让今天的功能上线，但它们都能让明天的功能更容易上线。

有关特定平台的模式（哪个平台最适合处理哪种标志类型、MCP 命令的样式，以及常见陷阱所在），请参阅所选平台的文档。有关此技能之上的实验设计层（假设纪律、样本量、决策制定），请参阅 experiment-design 技能。有关此技能之下的分析层（方差缩减、序贯检验数学、贝叶斯替代方法），请参阅 experimentation-analytics 技能。