Draft.js 周会纪要解读：用 Feature Flag 与测试驱动实现大规模增量重构

Draft.js 周会纪要解读：用 Feature Flag 与测试驱动实现大规模增量重构

【免费下载链接】draft-jsA React framework for building text editors.项目地址: https://gitcode.com/gh_mirrors/dr/draft-js

本文基于仓库 meta/meeting-notes/2017-09-01-weekly-meeting.md 中记录的 2017-09-01 周会内容，围绕 Draft.js 团队当时发起的一个"为期一个月的内部改进项目（Hack-a-month）"展开。它真实记录了 Facebook 团队在面对"大重构很可怕"这一普遍难题时的方法论：借鉴 React 的增量升级路径、以"修 Bug 必加测试"为纪律、把新特性藏在 Feature Flag 之后灰度放量，并把 Flow 类型覆盖缺口整理成对新手友好的 good-first-bug 议题。读完本文，你将理解这套可复用的开源编辑器演进策略，并能在当前仓库的源码中找到对应的落地实现（gkx 门控、Jest 测试体系、Flow 配置等）。

一、会议背景：一次为期一个月的内部改进项目

2017 年 9 月 1 日的 Draft.js 周会首先介绍了正在推进的"为期一个月的改进项目（Hack-a-month）"，目标是为 Draft.js 支持更丰富的特性（richer features）。该项目标注为"internal only"（仅限内部），对应前几周会议的铺垫——2017-08-11-weekly-meeting.md 中已提到"计划引入更多内部维护者参与为期 1 个月的 Draft.js 项目"，2017-08-18-weekly-meeting.md 也再次确认了该计划。可见这是一个持续酝酿、集中人力推进的重大方向。

会议随即抛出了一个核心难题：

Big refactors are scary - how to approach this?

"大重构很可怕——我们该如何下手？"这是几乎所有长期维护的开源项目都会遇到的经典问题，Draft.js 团队的答案对今天仍在维护复杂前端编辑器的团队依然有参考价值。会议记录的后续条目，正是围绕"如何让大重构不那么可怕"展开的一套完整策略。

二、借鉴 React：走增量升级路径，而非一次性重写

会议记录中，团队明确表示要从 React 的实践中学习：

• 增量升级路径（incremental upgrade path）：不做"推倒重来"式的重写，而是让用户可以在新老行为之间平滑迁移。这对一个被 Facebook 内部大量产品依赖、同时拥有庞大外部社区的库至关重要。
• 良好的测试套件是重构的底气：React 之所以敢做持续的重构，是因为它有足够好的测试。团队提炼出的纪律是——"当你修复一个 Bug 时，就为它补上一个测试"（when you fix a bug, add a test）。这样每修一个问题，测试防线就加固一分，重构的回归风险就降低一分。

这一纪律在当前仓库中可以得到印证：package.json 中配置了完整的质量防线：

"scripts": { "lint": "eslint .", "flow": "flow src", "test": "cross-env NODE_ENV=test jest", "test-ci": "cross-env NODE_ENV=test npm run lint && npm run flow && npm run test" }

其中test-ci把 lint、Flow 类型检查、Jest 单测串成一条 CI 流水线，从机制上保证"新增代码必须通过全部质量关卡"。仓库 src/model/immutable/tests下大量*-test.js与__snapshots__/快照文件（如ContentState-test.js、EditorState-test.js、SelectionState-test.js），就是"修 Bug 加测试"这一习惯留下的实证。

三、测试的现实困难：DOM Selection 状态几乎不可测

会议坦诚地指出了这套方法论在 Draft.js 上的特殊痛点：

• Draft 的某些部分几乎不可能测试（some parts are almost impossible to test）；
• 明确点名DOM Selection 状态很难测试（DOM Selection state is hard to test）。

这是内容可编辑（contentEditable）编辑器特有的难题：编辑器的核心状态（光标选区、IME 组合输入、浏览器原生 DOM 行为）依赖浏览器私有实现，很难在单元测试里稳定复现。仓库中确实保留了专门攻克这一问题的测试基础设施，例如 src/component/selection/tests下的getDraftEditorSelection-test.js、setDraftEditorSelection-test.js，以及为测试构造浏览器 mock 的getSampleSelectionMocksForTesting.js；src/component/handlers/composition/tests/DraftEditorCompostionHandler-test.js 则专门覆盖了跨浏览器的组合输入逻辑。这些文件表明团队确实在为"不可测"的部分想办法，用精心构造的 mock 把浏览器差异隔离在测试之外。

四、Feature Flag：把新特性先"藏"在门控后面

针对"有些部分测不了、新行为又不敢直接上线"的矛盾，会议给出的关键答案是：

Put things behind a feature flag initially

先把新特性放在 Feature Flag（特性开关）后面。这样代码可以合入主干、随版本发布，但默认关闭，只有显式开启后才走新路径——既保证内部与外部用户不受影响，又能在真实流量中逐步验证。

这一策略在当前仓库中留下了非常具体的实现，即gkx门控模块（GateKeeper 的缩写，Facebook 内部特性开关体系）。核心实现在 src/stubs/gkx.js：

module.exports = function (name: string) { if (typeof window !== 'undefined' && window.__DRAFT_GKX) { return !!window.__DRAFT_GKX[name]; } return false; };

也就是说：运行时读取全局window.__DRAFT_GKX对象上的开关，默认全部关闭（返回false）。仓库中实际使用的开关包括：

最有代表性的门控切换是draft_tree_data_support。它不是简单的布尔分支，而是在模块加载时就根据开关选择整条实现路径：

const experimentalTreeDataSupport = gkx('draft_tree_data_support'); module.exports = experimentalTreeDataSupport ? require('DraftEditorContentsExperimental.react') : require('DraftEditorContents-core.react');

——见 src/stubs/DraftEditorContents.react.js。与之配套，仓库中还维护着一整套"探索性（exploration）"实现：src/component/contents/exploration（含DraftEditorBlockNode.react.js、DraftEditorContentsExperimental.react.js及其测试）、src/model/modifier/exploration/NestedRichTextEditorUtil.js 和 src/model/modifier/exploration/DraftTreeOperations.js。这套"实验实现 + 老实现并存、开关切换"的结构，正是周会上"每加一个特性就配一个测试、先用 flag 保护起来"策略的源码级落地。

五、灰度放量：从"二分人群"到"出了事有人报"

会议记录的另一个重要经验，来自团队此前把 Draft.js 接入 Facebook 评论系统的历程：

• 先做大量实验、花了很长时间（did many experiments, took forever）：新架构的落地急不得；
• 二分人群（bifurcate）：一部分用户用新实现、一部分用户用旧实现，互相对照，便于发现差异与回归；
• 盯紧错误上报（obsessively look through flytrap）：Flytrap 是 Facebook 内部的错误监控系统，团队"痴迷地"翻阅崩溃报告，一旦出问题，用户会主动上报（when things broke, people reported it）；
• 直到不再频繁出错，才正式发布（eventually it was not breaking so badly, could ship it）。

这实际上是一条标准的灰度发布（canary rollout）路径：小流量验证 → 监控反馈 → 逐步放量 → 全量上线。它与 Feature Flag 天然互补——flag 决定"代码层面走哪条路"，二分人群决定"哪些用户走新路"。

此外，会议还提到会引入QA 承包商（QA contractors）做人工验收，作为自动化测试的补充，专门覆盖那些"自动化难以触达"的浏览器交互场景。

六、Flow 类型覆盖缺口：变成 good-first-bug

会议的第三个主题转向了社区贡献者的引入：

Gaps in flow coverage could be good-first-bug issues

Flow 类型覆盖的缺口，可以整理成适合新手的 good-first-bug 议题。这既是完善类型安全的手段，也是吸引社区新贡献者的低门槛入口。

当前仓库确实在 Flow 类型检查上投入很重：根目录下有 src/.flowconfig 配置文件，包含：

• Haste 模块系统配置：module.system=haste及配套的name_reducers规则，让模块按 basename 互相引用；
• [strict]严格模式：开启deprecated-type、sketchy-null、unclear-type、unsafe-getters-setters等严格检查项，并注释说明哪些暂不能开启（如 immutable.js 会触发untyped-import错误、fbjs 的invariant非严格类型化导致nonstrict-import无法启用）；
• 版本锁定：[version] ^0.130.0，配合 package.json 中 devDependencies 的"flow-bin": "^0.130.0"。

这些"因为第三方依赖而不能开启的严格项"，正是周会所说"Flow 覆盖缺口"的具体形态——它们不是不想做，而是被上游依赖限制，需要逐一评估和补齐。

社区贡献的配套机制：good first issue 标签

会议的行动项（Action Items）非常明确：

1. 制作一些 good-first-bug 议题；
2. 议题面向Flow 类型覆盖与单元测试两类工作；
3. 讨论是否应该建立flow-typed目录（为第三方模块维护类型定义）。

这与仓库 CONTRIBUTING.md 中定义的 Issue 分类体系完全呼应——其中就有专门的good first issue标签："适合刚接触项目的新人参与的贡献候选"。把"类型覆盖缺口""单测缺失"这种边界清晰、改动局部化的工作整理成标签议题，正是大型开源项目常用的新手引导手段：贡献门槛低、验收标准明确（补齐类型/补上测试即可），同时实实在在提升了项目的代码质量防线。

七、行动项小结与可复用启示

本次周会最终沉淀的行动项可以归纳为：

从这份会议纪要中，可以提炼出一套可复用的开源编辑器大规模演进方法论：

1. 用 Feature Flag 承载大重构：新实现与老实现并存，默认关闭、按需开启（src/stubs/gkx.js 的__DRAFT_GKX机制）；
2. 用测试为重构兜底：修一个 Bug 补一个测试，靠 Jest 快照与精心构造的 mock 覆盖"几乎不可测"的 DOM Selection 场景；
3. 用灰度放量控制风险：二分人群 + 紧盯错误上报，直到新路径"不再严重出错"再全量发布；
4. 用低门槛议题引入社区力量：把 Flow 覆盖缺口与单测缺失整理成 good-first-bug，让新人从风险最小的改动开始贡献。

这一整套思路，最终在仓库中沉淀为可见的工程形态：gkx门控的树形数据结构实验（draft_tree_data_support）、src/component/contents/exploration 目录下的实验实现、严格的 Flow 配置与全套 Jest 测试。对于任何正在面对"大重构很可怕"这一问题的团队，这份 2017 年的会议记录至今仍是一份值得对照实践的策略蓝本。

【免费下载链接】draft-jsA React framework for building text editors.项目地址: https://gitcode.com/gh_mirrors/dr/draft-js