Selenium 设计决策记录ADR机制解析跨语言绑定的统一决策架构与治理流程【免费下载链接】seleniumA browser automation framework and ecosystem.项目地址: https://gitcode.com/GitHub_Trending/se/selenium导读Selenium 以同一套 API 向 Java、Python、Ruby、.NET、JavaScript 五种语言绑定交付功能任何涉及用户可见行为、API 形态与跨绑定语义的改动都必须一次决策、处处一致地落地。本篇文章基于仓库中的 设计决策目录说明系统讲解 Selenium 如何用一套编号化、不可变、按 PR 号归档的 ADRArchitecture Decision Records架构决策记录体系管理这类跨语言决策包括记录触发的边界、单条记录的组织粒度、从提议到落地的完整流程、TLC 共识审批机制以及决策与实现分离、记录不可变的核心规则。读完本文你既能直接上手为仓库提交一份新的决策记录也能理解现有记录如 BiDi 边界、Web 扩展安装背后为什么这样定的完整论证结构。相关路径docs/decisions/README.md本文主体、docs/decisions/0000-template.md记录模板、docs/decisions/17670-bidi-implementation-boundaries.md 与 docs/decisions/17817-driver-extension-install.md两个已接受的实例。一、为什么 Selenium 需要一份决策日志Selenium 不是一个单体程序而是由多个仓库子目录各自维护语言绑定构成的浏览器自动化生态java/src/org、py/selenium/webdriver、rb/lib/selenium、dotnet/src/webdriver 以及 javascript/selenium-webdriver分别对应 Java、Python、Ruby、.NET 与 JavaScript。正是这种多语言同构交付带来了 README 中点名的根本问题关于用户可见行为、API 形态、跨绑定语义的决定必须在单一处作出并记录然后在所有绑定中一致地实现。如果这类决定散落在各语言各自的 PR 讨论里就会出现 API 命名不一、错误行为分叉、默认超时参差的情况——而这恰恰是浏览器自动化框架最不能接受的。于是docs/decisions目录被定位为这些决定的权威记录canonical record当代码评审中出现相关问题评审者给出的答复应当是链接到这里的某一文件而非一段口头的临时约定。每条决策一个文件编号即提出该决策的 PR 号文件内容在通过后长期有效、作为跨绑定实现与后续决策的共同基础。二、什么议题需要决策记录什么不需要README 对记录范围给出了一条明确的准入清单与豁免清单。需要记录必须跨绑定保持一致、且一旦定下影响面大的议题用户可见行为中应跨绑定一致的部分API 命名与形态、错误类型与错误消息、默认超时、capability能力项的处理方式WebDriver Classic / BiDi 的语义以及协议如何或刻意如何不暴露给用户弃用deprecation与向后兼容承诺任何被 TLC技术领导委员会打上A-needs-decision标签并被解决的议题。不需要记录属于单绑定内部或可低成本回退的议题单一绑定内部的实现取舍例如 Java 维护者自行挑选某个数据结构——它不影响其他语言不需要一次决策四处同步构建工具与基础设施选择如 Bazel 规则调整、CI 脚本改动任何可以低成本轻易反悔的事情。README 给出的判断准则是拿不准时反问自己这个问题将来会不会再次被提出如果答案是肯定的就值得留一份记录如果只是一次性的、可回退的选择则不必要也不应该进入决策日志。这一准则把 ADR 的精力集中在会被反复引用、需要长期稳定的决定上避免日志退化为低价值的变更清单。三、记录粒度一条记录 一个内聚决策决策记录不是一个功能一份也不是能拆就拆。README 明确主张一条记录应捕捉一个内聚的决策one coherent decision——这通常意味着一簇共享同一背景与同一理由、作为一个整体被定下的相关子选择。把这些子选择打包在同一条记录里不是缺陷例如一条关于点击行为的记录可以连同滚动到可见scroll into view、命中测试hit-testing、指针移动pointer movement一起定案因为它们本质上是同一个设计、同一套理由。因此拆分与否的判据不是这个部分能不能单独被采纳——几乎任何部分都可以——而是看该子选择是否拥有不依赖其他部分的独立理由会被单独争论、单独决定或日后可以在不扰动其余部分的前提下被单独推翻。如果强行拆分会导致读者为理解其中某一条不得不打开多条记录那么它们就应该留在同一条记录里。这条粒度规则保证了每条 ADR 的自包含性与可检索性也直接支撑了后文决策必须能独立成立的硬性规则。四、决策记录的标准结构从模板看一次完整的论证实际落笔的记录并非自由格式。仓库中 0000-template.md 给出了标准的节骨架逐节说明如下。标题与元信息标题以 PR 号开头 以陈述事实的方式命名例如# NNNN. Clicks scroll elements into view before interacting点击前先把元素滚动到可见模板明确反对Click behavior这类含糊标题——标题本身就是决策结论的浓缩Status状态Proposed | Accepted | Rejected | Superseded by NNNN四选一状态行是记录中唯一允许事后变动的字段见后文不可变规则Discussion讨论指向该记录所属 PR 的链接此前相关 issue/线程则放入 Context 一节的背景资料。Context背景回答我们要解决什么问题、哪些力量在拉扯——W3C 规范措辞、用户预期、各绑定之间当前行为的分歧、实现约束等。模板建议把此前讨论issue、TLC 备忘作为背景链接出来但要总结而非罗列因为这一节必须做到不点开任何链接也能读懂。模板特别提示当各绑定当前行为确有分歧时用一张绑定现状表让差异具体化这是该决策时刻的 as-is 状态属于持久化的决策理由而不是事后的收敛追踪收敛追踪应放接受后的 tracking issue见流程第 4 步。表格固定为五行绑定列BindingCurrent behaviorJavaPythonRuby.NETJavaScriptDecision决策以语言中立的术语陈述决策这是全篇的规范部分normative part规定每个绑定必须做什么以及哪些明确留给各语言的惯用表达。记录what与why不记录how——实现方式属于后续采纳它的各绑定 PR。模板允许用代码草图钉死被决定的 API 形态但禁止用代码来规定实现。例如 17670 号记录 的 Decision 节就给出了一段示意性 Ruby 代码来界定允许/不允许的边界详见下文实例。Considered options备选方案列出被否决的替代方案及各自被否的理由。模板强调这些选项是对同一问题的互斥答案而不是一份可任意挑选的功能菜单。若一条记录打包了相关子选择可为其各自列出选项能否独立被采纳本身不构成拆分理由呼应 README 的粒度指引。这一段在评审中会随备选方案被质疑或新增而持续修订——合并后的记录而非 PR 线程才是为何未选某方案的权威陈述。Consequences后果记录决策带来的影响什么变容易、什么变难、用户会观察到什么本决策触发的弃用及其时间线本决策使得哪些后续决策成为必要。模板特别注明各绑定的收敛进度不在这里追踪——记录被接受后应单独开一个 ADR tracking issue 并链接到记录的 PR 上从而避免让一条本应不可变的文件因收敛进展而反复变更。Appendix附录可选存放决策所依赖的、需要长期保留的支撑材料基准测试数据、规范摘录、其他工具行为调研等。若无则删除本节临时性证据属于 PR 线程而非记录本体。五、完整生命周期Propose → Discuss → Decide → ImplementREADME 把一条 ADR 从产生到落地的旅程拆成清晰的四步17670 号 与 17817 号 两条已接受记录都是按此流程走完的实例。第 1 步 Propose提议任何人不限于核心成员都可以提议。操作路径是复制 0000-template.md 为short-title.md填入内容并把状态标为Status: Proposed开一个 PRGitHub 分配 PR 号后在合并前把文件改名为NNNN-short-title.mdNNNN 即该 PR 号篇幅控制在约一页——如果争论已在此前的 issue 里发生过记录可以写短些并链接过去。一个容易被忽略的实操细节ADR 应使用专用的 PR 模板而 GitHub 没有 PR 模板选择器唯一方式是在 compare URL 后追加?expand1templateadr.md查询参数来强制套用。README 还要求 PR 正文只承载评审物流信息——决策与理由属于记录文件本身不属于 PR 描述。第 2 步 Discuss讨论PR 线程就是讨论记录。需要同步讨论的决策会被提交到 TLC 会议会议结论再回流到 PR 中。对备选方案的分歧通过在评审期间修订文档来解决使最终合并的记录准确反映争论的全过程——这正解释了上一节为何强调合并后的记录是权威版本。TLC 自行排定会议议程提案按议程时间推进。第 3 步 Decide决策当满足下述审批条件、且讨论已充分走完流程后由Selenium Project Lead负责合并记录并把状态更新为Accepted——合并且更新状态即为接受。三条可能结局提案被接受 → 状态AcceptedTLC 审议后否决 → 照样合并但状态为Rejected被否决也是一种需要留档的决策理由值得后人查阅提案在 TLC 审议前被撤回或放弃 → 关闭 PR编号作废由此产生下文编号有缺口属正常的规则。第 4 步 Implement落实记录被接受后实现阶段要开一个 ADRtracking issue使用仓库中的 ADR Implementation Tracking issue 模板每个绑定一个复选框各绑定实现 PR 落地时逐个勾选并链接同时把该 issue 链接回记录本身的 PR。tracking 之所以放在 issue 而非已提交的记录文件里是因为要避免各绑定陆续收敛的过程去反复改动一份本应不可变的文件——issue 的更新不需要 TLC 评审而记录的修改需要。这条设计再次体现了 Selenium 对记录稳定与实现渐进之间张力的刻意管理。六、审批规则以共识为门槛的 TLC 评审ADR 的接受不是某个人拍板而是有明确的参与机制与共识门槛响应方式TLC 成员通过 GitHub review 回应提案——可以是 approve赞成、no objection式评论 review已阅、听从其他成员判断或 request-changes明确指出要解决什么才算通过共识标准TLC 过半数成员已作出回应且无人持有未解决的异议记录方可被接受最低观察期接受前记录必须至少公开一周并且在 TLC 会议上作为一个议程项出现过——目的是保证没有任何人是在决策作出之后才得知此事实质性修改若发生实质编辑作者需重新请求各成员 review异议僵局修订无法化解的异议包括支持另一被考虑的选项交由 TLC 会议讨论若仍无法达成共识由 Selenium Project Lead 裁定哪一立场胜出记录随之更新且被推翻的异议要以摘要形式保留而不是被抹除。这套规则把速度与知情权可追溯做了明确折中一周观察期 会议议程项保障了集体知情lead 的最终裁定权保障了流程不会无限期卡死而被推翻异议的存档则保留了未来重新审视的可能。七、四条硬性规则自包含、管决策不管实现、不可变、编号即 PRREADME 末尾的四条规则是整套机制的宪法级约束决策必须能独立成立stand alone读者不点开任何链接也能读到决策、理由与被否备选被链接的材料只是背景不是必读内容。这与模板中Context 必须脱离链接也能读懂合并后的记录是权威陈述一脉相承。记录钉死决策与理由而非实现它说明每个绑定必须做什么、为什么至于每个绑定如何构建属于采纳它的 PR 与代码。这一原则保证了记录不会因单绑定实现细节的演进而过期。已接受的决策不可变immutable状态行除外改变一个决策意味着写一条新记录取代旧记录——旧记录状态更新为Superseded by NNNN。换言之决策日志是一条只追加的链不存在修改历史。编号即提案的 PR 号该编号在评审、issue 中被引用并直接链回讨论现场因此编号有缺口作废或被关闭的提案是正常现象不应被补号。这四条规则的组合效果是决策日志既是一份稳定的规范来源每条记录独立可引又是一条完整可回溯的历史链从编号直达 PR 讨论。八、仓库实例两条 Accepted 记录的完整论证为理解上述模板与流程在真实决策中的样子最直接的做法是阅读仓库里两份已接受的记录。实例一17670 号记录——BiDi 实现边界议题是各绑定在用 WebDriver BiDi 实现与扩展 Selenium API那么受支持 API 的终点、内部 BiDi 实现的起点划在哪里Context 节先摆出现状表Java 的HasBiDi.getBiDi()把裸 BiDi 连接暴露在 driver 上、Python 的driver.network/driver.script命名正确却返回低层bidi命名空间模块、Ruby/.NET/JavaScript 各自有driver.bidi/AsBiDiAsync()/driver.getBidi()——所有绑定都把 BiDi 实现细节从 driver 对象上漏了出来且均提供可改名为协议中立名称的enableBiDi/enable_bidi会话开关。Decision 节给出三条规范① 受支持 API 协议中立绝不出现 BiDi 类型、绝不向用户交出 BiDi 对象② BiDi 实现内部化且不受弃用策略管辖忠实实现 BiDi 规范理论上可从 CDDL 生成但因规范非自有、虽稳定却不做保证③低层访问靠组合composition而非挂到 driver 上——BiDi::Protocol::Network.new(driver)合法driver.bidi.network不合法因为凡是从 driver 可达的成员都会被用户下意识视为受支持 API。记录还特意澄清给表面打上Beta标记并不能满足第 ② 条——Beta 表示正在走向受支持与内部恰好相反。Considered options 列出四个互斥方案及否决理由全协议作为公开 API否决实现层在追一部活规范稳定性无法承诺另建受支持的中层级API否决用户将构建在 BiDi 形态概念上重蹈 CDP 覆辙且两套受支持表面令用户无所适从把内部实现作为 driver 成员暴露否决driver 成员隐含受支持语义最终接受仅内部实现机制 组合式访问。该决策在源码中有清晰的镜像Python 侧 py/selenium/webdriver/common/_bidi含 domain、serialization、transport 三模块与 Ruby 侧 rb/lib/selenium/webdriver/common/network.rb 体现的就是协议层内部模块 高层中立封装的分离形态。实例二17817 号记录——Driver 直接安装 Web 扩展议题是 Web 扩展的安装入口应该放在哪。Context 指出三重张力Firefox 可经 WebDriver-Classic 端点在会话中途装扩展但各绑定都把它挂在浏览器专属类型上而非 driver 上Java 的FirefoxDriver.installExtension、Python 的install_addon、Ruby 的HasAddons等Chromium 原本走 session 创建时的 capabilities 路径但品牌 Chrome 自 Chrome 137 起不再支持该路径Chrome for Testing 与无品牌 Chromium 仍支持于是会话开始后再安装成为硬性需求而 WebDriver BiDi 已规范了扩展的安装/卸载多数绑定已有相应 BiDi 模块。Decision 给出三条① 在driver 实例本身上新增installWebExtension/uninstallWebExtension两个统一方法不接受浏览器专属类型或 BiDi 模块安装接受 archive/目录/base64 及厂商专属选项Firefox 上为permanent与allowPrivateBrowsing必须兼容 Grid 环境返回包装了 id 的WebExtension对象卸载则接受该对象而非裸 id② 向后兼容——Firefox 上未启用 BiDi 时回退到 WebDriver-Classic 端点既有 classic 安装方法与参数随之弃用③ 目标无法满足请求时必须抛错而非静默降级例如 Chromium 无 BiDi 时调用installWebExtension应报错。该决策的源码与测试依据同样可在仓库中核对Python 侧 Firefox 的 legacy 方法 py/selenium/webdriver/firefox/webdriver.pyinstall_addon/uninstall_addon即记录中将被弃用、以统一方法取代的对象而 py/test/selenium/webdriver/firefox/ff_installs_addons_tests.py 与 py/test/selenium/webdriver/common/bidi/webextension_tests.py 分别覆盖 classic 与 BiDi 两种实现路径Ruby 侧则有 rb/lib/selenium/webdriver/bidi/protocol/web_extension.rb 对应的协议模块。值得注意的是记录 Consequences 节点出一个分布式实现约束远端可能运行在与客户端不同的主机上如 Grid node实现不能传递客户端本地文件路径必须以远端可解析的形式交付扩展——内联内容或先上传到远端再引用所获得的位置。这正是记录留 what/why、实现细节归各绑定 PR原则下仍须在记录里钉死的跨绑定语义约束。九、实战小结提交一份 ADR 的检查清单综合 README、模板与两份实例向该仓库提出一份新的设计决策时可对照以下清单自查触发判定改动是否跨绑定可见API 形态、错误、默认超时、capability、Classic/BiDi 暴露方式、弃用承诺若是必须走 ADR若属单绑定内部或构建基础设施不进日志粒度相关子选择是否共享同一背景与理由若读者需翻多条记录才能理解其一则应合并为一条落笔以 0000-template.md 为骨架标题用NNNN陈述事实式Context 写清分歧现状必要时含五绑定现状表Decision 用语言中立语句钉死规范Considered options 互斥且附否决理由Consequences 含弃用与后续影响状态标Proposed编号暂用短标题提交开 PRcompare URL 追加?expand1templateadr.md选用 ADR 模板取得 PR 号后在合并前改名为NNNN-short-title.md篇幅约一页PR 正文只谈评审物流等待共识公开至少一周、进入 TLC 会议议程过半 TLC 成员回应且无未解决异议期间异议通过修订文档消解重大僵局交由 Project Lead 裁定落地接受后开 ADR tracking issue每绑定一复选框并链接回记录 PR实现工作按各绑定推进——记录文件本身从此保持不可变仅在产生后续决策需要取代它时更新状态为Superseded by NNNN。遵循这套机制Selenium 得以让五种语言在API 命名、错误语义、默认行为、协议边界上保持一致同时保留每条决策的完整论证史——这套编号即 PR、合并即接受、记录不可变、理由可追溯的 ADR 实践本身也值得其他多语言/多模块开源项目借鉴。【免费下载链接】seleniumA browser automation framework and ecosystem.项目地址: https://gitcode.com/GitHub_Trending/se/selenium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考