Spec-First 功能开关：开关逻辑、金丝雀发布与暗发布

功能开关一开始是受控灰度发布的手段，最终却变成了没人敢删的永久性基础设施。这两个状态之间的鸿沟，几乎总是因为缺少规格。当一个开关在创建时没有记录谁能看到它、什么条件下全量发布、什么时候删除，这个开关就变成了一个从未真正完成的决策。本文讲解如何为功能开关编写规格，使每个开关都有生命周期，每次灰度都有退出标准，每个开关在写第一行代码之前就有明确的移除日期。

发布于 2026-03-30 · ✓ 已更新 2026-05-06 · 阅读约 9 分钟 · 作者：Daniel Marsh · 审校：编辑政策

为什么功能开关需要规格

没有规格的功能开关，就是一个被无限期推迟的决策。添加开关的工程师知道它今天控制什么，但三个月后没人知道这个开关为什么存在、谁应该看到该功能、灰度标准是什么，或者这个开关到底应不应该是临时的。开关变成永久的，不是因为谁决定了它应该永久存在，而是因为没人记录它应该在什么时候消失。

之所以会这样，是因为开关被当作实现细节而非产品决策来对待。添加一个开关感觉很轻量——代码里加个布尔判断，配置存储里加一行，后台面板里加个切换按钮。但这种轻量感是骗人的。一个功能开关改变了系统对部分用户的行为，而对另一部分用户保持不变。它为测试创建了组合爆炸的表面积。它引入了一个条件分支，未来的每次代码变更都必须考虑到这个分支。这些不是实现细节。它们是影响范围、测试、可观测性和清理的决策，值得与功能本身同等级别的规格化关注。

最常见的失败模式是那些本应是临时的开关。团队在开关后面发布了功能，灰度到 100%，确认没问题，然后转去做下一个迭代。开关留在代码里。六个月后有四十个开关，一半处于 100% 状态，没有人有信心移除其中任何一个，因为移除标准从未被写下来。这就是开关债务，它和其他形式的技术债务一样会复利累积。

开关生命周期规格

每个功能开关都应该在实现开始前定义生命周期。生命周期有四个阶段：创建、灰度、全量发布和清理。每个阶段都需要记录进入和退出标准。

# 功能开关规格：新结账流程

## 开关名称
new_checkout_flow

## 负责人
结账团队（支付小组）

## 类型
发布开关（临时）

## 创建标准
- 所有环境中开关默认为 OFF
- 在开关管理系统中注册并附带元数据：
  负责人、创建日期、预计移除日期、关联规格
- 预计移除日期：2026-07-01

## 灰度阶段
1. 内部灰度：为 @company.com 邮箱用户开启（1 周）
   - 退出标准：零 P0/P1 Bug，结账完成率 >= 94%
2. 金丝雀：为 5% 的用户开启，按 user_id 哈希固定分配（2 周）
   - 退出标准：p99 延迟 <= 450ms，错误率差异 < 0.1%
3. 逐步灰度：25% -> 50% -> 100%，跨 3 周
   - 止损线：如果错误率 > 0.5%，回退到上一阶段
   - 每个阶段的退出标准：在该百分比下稳定运行 48 小时

## 全量发布标准
- 开关在 100% 状态下运行 >= 1 周且无回滚
- 监控确认转化率和延迟无回归
- 产品负责人签字确认

## 清理
- 全量发布后 2 个迭代内从代码中移除开关
- 从配置存储中删除开关
- 移除所有消费服务中的条件分支
- PR 必须包含移除开关依赖路径的测试更新

类型字段很重要。发布开关是临时的，控制功能灰度发布。运维开关是半永久的，控制熔断器等运维行为。实验开关支持 A/B 测试，有自己的统计标准。权限开关按权限门控功能，设计上就是永久性的。每种类型有不同的生命周期预期，规格应明确标注类型，使清理节奏与意图匹配。

预计移除日期是最重要的一个字段。没有它，没有开关会被移除。有了它，你可以构建自动化工具，在开关超过计划生命周期时发出告警。如果团队在创建时无法承诺移除日期，这本身就说明开关的目的不清楚，现在澄清这个问题可以在后续省下大量清理工作。

受众定向与灰度百分比

指定谁能看到被开关控制的功能，需要比"部分用户"更精确。规格需要定义定向维度、百分比和分配机制。

定向维度决定用户或请求的哪个属性控制开关评估。常见维度包括用户 ID、组织 ID、地理区域、设备类型和账户层级。选择什么维度影响测试和调试。按用户 ID 定向的开关为每个用户产生一致的体验。按请求 ID 定向的开关在每次请求时产生随机体验，这对负载测试有用，但对用户侧功能会造成困惑。

灰度百分比定义目标人群中有多少人能看到新功能。规格应定义每个阶段的百分比以及推进标准。从 5% 到 50% 不是一个排期决策，而是一个基于观测指标的决策。规格应指明哪些指标、什么阈值、谁有权推进或回滚。

粘性分配指同一用户在多次会话中看到相同的变体。这对影响用户工作流、计费或数据持久化的功能至关重要。规格应说明分配是否粘性、粘性键是什么（用户 ID、会话 ID、设备指纹），以及当用户属性变化时会发生什么。如果用户更改了地理区域，他们是保持旧的开关变体还是被重新评估？这个问题听起来无关紧要，直到它在生产环境中导致计费不一致。

一个常见的遗漏是没有在规格中定义开关系统不可用时的行为。如果开关评估服务宕机了，应用程序是默认开启还是关闭？对于装饰性功能，默认关闭是安全的。对于门控支付流程的功能，默认关闭可能让所有用户无法结账。规格应明确写出回退行为，验收标准应包含开关服务不可用的测试用例。

金丝雀部署 vs 功能开关

金丝雀部署和功能开关经常放在一起讨论，但它们在不同层面解决不同问题，混为一谈会导致规格和运维都出现混乱。

金丝雀部署是一种基础设施策略。服务的新版本被部署到一小部分实例上。流量通过负载均衡器配置路由到这些实例，而非应用逻辑。金丝雀对收到的所有请求运行相同代码，应用中没有条件分支。评估标准是基础设施指标：CPU、内存、错误率和延迟百分位。如果金丝雀看起来健康，部署继续。如果不健康，流量切回旧版本。金丝雀部署的发布规格定义实例数量、流量百分比、健康检查端点和自动回滚阈值。

功能开关是一种应用策略。相同部署版本的代码同时提供新旧两种行为，运行时评估决定给定请求走哪条路径。评估标准是产品指标：转化率、漏斗完成率、用户错误率和业务 KPI。功能开关跨部署持续存在，而金丝雀只存在于部署窗口内。

这个区别对规格很重要，因为两种机制有不同的故障模式。金丝雀部署出问题会影响有限百分比的流量、持续有限的时间窗口。功能开关出问题可以在开关存在的任何时间影响任何用户。金丝雀部署的规格聚焦于基础设施安全。功能开关的规格聚焦于产品正确性。

实践中，高风险发布同时使用两者。代码通过金丝雀部署来验证基础设施稳定性。部署完成后，功能开关逐步推进来验证产品行为。规格应将此描述为两阶段发布，并明确哪些指标门控每个阶段。将基础设施指标和产品指标混在一起评估会导致这样的情况：因为产品指标不好而回滚了金丝雀部署（而金丝雀无法控制产品指标），或者因为基础设施指标正常就推进了开关（即使产品行为是错的）。

暗发布：在全量发布前规格化可观测性

暗发布将新代码暴露给生产流量，但不向用户展示结果。新代码路径执行了，结果被记录或与现有路径比较，但用户只看到旧行为。这种技术让团队在功能上线前，用真实流量验证性能、正确性和故障模式。

暗发布需要在规格中单独成节，因为其成功标准与常规灰度不同。在标准开关灰度中，成功意味着用户看到新行为且没出问题。在暗发布中，成功意味着新代码路径在可接受的延迟下产生正确结果，而用户没有看到任何不同。

暗发布的规格应包含：

• 影子执行范围。哪些请求触发新代码路径？所有请求、采样百分比、还是匹配特定条件的请求？100% 影子执行会使每个受影响请求的计算成本翻倍。规格应说明预期资源开销并确认容量充足。
• 比对方法。新路径的结果如何与旧路径比较？逐字段比较、语义等价、还是统计采样？规格应定义什么算匹配、什么算偏差。
• 指标与仪表板。暗发布期间测量什么？至少包含：影子路径的延迟开销、新旧结果之间的偏差率、新路径的错误率、资源消耗。规格应指明这些指标可在哪个具体的仪表板或监控工具中查看。
• 退出标准。暗发布必须产生什么结果，团队才能继续进行可见灰度？偏差率低于 0.01%？p99 延迟开销低于 20ms？这些数字应在规格中写明，而不是在暗发布已经运行之后再决定。

最常见的暗发布失败是在运行前没有定义要寻找什么。影子路径运行了两周，产生了数 GB 的比对日志，但没人分析它们，因为分析标准从未被规格化。在暗发布开始前规格化可观测性，确保团队收集正确的数据，并知道"可以继续"长什么样。

开关债务与清理规格

每个在完成使命后仍留在代码库中的功能开关都是技术债务。与其他形式的债务不同，开关债务有一个具体且可衡量的成本：每个残留的开关增加了需要测试的代码路径数量、可能导致意外行为的配置组合数量，以及工程师遇到不理解上下文的条件分支时的认知负荷。

清理规格是开关生命周期规格的一部分，不是单独的文档。它应包含：

• 移除日期。一个日历日期，在此之前必须从代码库中移除开关及所有相关条件逻辑。对于发布开关，通常是全量发布后两到四周。对于实验开关，是实验分析期结束时。对于运维开关，可能是"永久"但附带定期审查节奏。
• 移除范围。哪些文件、服务和配置存储包含该开关的引用？在创建时就列出这些可以加快清理速度，因为执行移除的工程师不需要搜索整个代码库。
• 测试变更。哪些测试用例是专门为开关行为编写的？当开关被移除时，这些测试需要更新或删除。规格应说明旧路径测试是可以完全删除，还是需要修改来测试现在永久生效的新行为。
• 负责人。谁负责移除开关？如果规格没有指名一个人或团队，清理就不会发生。"团队"不够具体。指名那个会提交清理 PR 的人。

自动化工具有助于强制执行清理。追踪创建日期和预计移除日期的开关注册表可以在开关超过计划生命周期时生成告警。一些团队添加 lint 规则，当代码中仍引用超过过期日期的开关时构建失败。这些都是有用的安全网，但它们只在规格在创建时就设定了过期日期的前提下才有效。工具执行规格，但不能替代规格。

与发布和回滚计划的集成

功能开关规格不是孤立存在的。它与更广泛发布的发布和回滚计划相连。这种连接是双向的：发布计划引用哪些开关控制发布，开关规格引用发布计划的止损阈值和回滚程序。

需要规格化的集成点：

• 回滚触发条件。在什么条件下应关闭开关？开关规格应引用与发布计划相同的止损指标。如果发布计划写的是"p99 延迟超过 500ms 就回滚"，开关规格也应写"p99 延迟超过 500ms 就关闭开关"。不同文档使用不同阈值会在事故中造成混乱。
• 回滚范围。关闭开关是否完全恢复行为，还是会让系统处于部分迁移状态？如果功能开关控制数据库迁移，关闭开关并不会反向迁移数据。规格应记录回滚实际意味着什么，以及除了切换开关之外是否需要额外步骤。
• 部署顺序。如果开关跨多个服务使用，规格应定义各服务采用和移除开关的顺序。在前端之前从后端移除开关会导致前端请求一个不再存在的代码路径。
• 事故手册引用。开关规格应链接到或包含值班工程师的手册条目。凌晨三点的事故中，值班人员需要知道：这个开关做什么、关掉是否安全、关掉之后会怎样？切换操作的幂等性在这里很重要。开关能否关掉再开而没有副作用，还是切换会产生需要清理的状态？

将开关规格与发布计划孤立编写的团队，最终会得到两份在最关键时刻——事故期间——互相矛盾的文档。在实现前就将开关规格与发布计划对齐可以防止这种矛盾。