用途:本指南说明如何在 workerd 中新增一个 autogate。autogate 用于在不依赖二进制发布的情况下逐步放量高风险代码改动,可通过内部工具临时开关,稳定后再移除。它与兼容性标志(compat flag)是两套独立机制,autogate 不会变成 compat flag。需要逐步放量、需要回滚开关、稳定后移除时用 autogate;永久改变用户可见行为、绑定兼容日期、需用户显式选择时用 compat flag。
主要步骤:一、在 src/workerd/util/autogate.h 的 AutogateKey 枚举中、NumOfKeys 之前新增枚举值,命名用 SCREAMING_SNAKE_CASE,并加注释说明该门控的作用。二、在 src/workerd/util/autogate.c++ 的 KJ_STRINGIFY switch 中、NumOfKeys 分支之前新增 case,返回 kebab-case 字符串,该字符串会以 workerd-autogate- 前缀出现在运行时配置中,枚举名与字符串名应保持一致。三、在行为改变处用 util::Autogate::isEnabled(util::AutogateKey::MY_NEW_FEATURE) 守卫代码,保留旧路径以便回滚。
测试方式:A. 每个 wd_test() 和 kj_test() 会自动生成 @all-autogates 变体,启用全部门控,可用 just stream-test //src/workerd/api/tests:my-test@all-autogates 运行。B. 在 C++ 测试中调用 util::Autogate::initAutogateNamesForTest({"my-new-feature"_kj}) 启用指定门控,测试结束调用 util::Autogate::deinitAutogate()。C. 设置环境变量 WORKERD_ALL_AUTOGATES=1 在无显式配置时启用全部门控。
构建与验证:just build;just stream-test //path/to:my-test@ 验证旧行为(门控关闭);just stream-test //path/to:my-test@all-autogates 验证新行为(门控开启)。
移除:在用户明确确认功能稳定且已完全放量后,删除 autogate.h 中的枚举值、autogate.c++ 中 KJ_STRINGIFY 的 case,以及所有 Autogate::isEnabled() 检查,只保留新代码路径。
涉及文件:src/workerd/util/autogate.h 加枚举值与注释;src/workerd/util/autogate.c++ 加 KJ_STRINGIFY case;功能文件用 Autogate::isEnabled() 守卫。限制:资料未提供其他平台、收费或效果信息。