目录
在URL边界切换前端框架,每次页面加载只运行一个框架。将替代页面的开发与向用户开放的变更分开,确保每次发布都有明确的回滚步骤。
要点#
- 每个文档只运行一个框架,新旧路由组之间使用整页加载的导航。
- 替代页面在向用户启用之前合并到main。
- 保持URL、API契约和持久化数据的兼容性,确保两种实现都能运行。
- 要求现有端到端测试以相同的操作和预期结果通过,行为变更须在实现前达成一致。
选择边界#
这种方法适用于由浏览器渲染、托管服务为应用各路由返回同一HTML入口的单页应用。两种实现都必须能够使用现有后端运行。对于服务端渲染的应用,请在服务端做出路由决策。仅靠下面的浏览器入口代码并不够。
选择可以接受整页加载的路由组,例如公开页面与需要身份验证的仪表盘、面向客户的页面与管理界面。将频繁操作限制在同一组内。跨越边界会丢失内存中的状态,因此在采用前,应先处理好未保存表单的问题。
即使各个页面分别实现,迁移仍按路由组分阶段推进。在开发新版仪表盘期间,现有仪表盘可以全部继续使用React。即使工作暂停,用户仍能继续使用已启用的实现,但维护两套代码仍需持续投入时间。
只启动一个框架#
在浏览器入口中,在启动任何框架之前,只选择一次要使用的实现。例如,公开页面可以使用Foldkit,而/dashboard及其子路径继续使用React。
const isDashboard = (path: string) =>
path === "/dashboard" || path.startsWith("/dashboard/");
const start = isDashboard(window.location.pathname)
? () => import("./dashboard-react/entry")
: () => import("./public-foldkit/entry");
void start().catch(showStartupError);各入口模块分别启动各自的框架。跨越边界的链接使用整页加载的导航,各实现内部则使用客户端路由。测试双向跳转、直接访问和浏览器“后退”。路由测试还应包含/dashboardx,确认它不会匹配/dashboard/。
动态导入使打包工具能够拆分入口代码。但在断言未使用的框架完全不会被下载之前,请检查生产构建产物和网络请求。共享导入、预加载配置和构建配置都可能影响结果。启动失败时,也需要提供可见的错误提示和恢复操作。
分离开发与发布#
每个路由组按4个阶段推进。
1. 准备: 记录当前行为、包体积和现有端到端测试结果,并就有意引入的差异达成一致。 2. 开发: 通过小型拉取请求合并替代页面,同时保持当前启用的入口仍启动旧实现。 3. 切换: 通过独立的入口变更启用新版,并执行相同的验收检查。 4. 删除: 经过约定的观察期后,删除旧实现及其依赖。
将每次评审的范围控制在便于理解的大小。所展示的taimei迁移计划使用了22个Issue,并将每个拉取请求最多涉及10个文件作为目标。这些只是规划示例,不能证明安全性。每个已完成的Issue也不代表相同的工作量。
删除旧实现之前,应确保只需恢复此前的入口选择并部署,就能完成回滚。测试这一流程并测量耗时。切换的改动较小,可以限制发布时的变更范围,但无法保证替代页面没有缺陷。
让兼容性可衡量#
保留现有端到端测试的操作和断言。标记结构变化可能需要调整定位器,但为了让迁移通过测试而放宽断言,会失去行为得到保留的依据。在编码前记录预期差异,未记录的差异按缺陷处理。
明确检查以下4个方面。
- 现有URL、深层链接和未知路由的处理。
- 身份验证、授权和API请求的兼容性。
- 共用样式、键盘操作和无障碍行为。
- 生产环境JavaScript的体积及关键用户流程的耗时。
回滚也需要数据兼容性。如果新前端写入的存储格式无法被旧前端读取,仅恢复入口并不够。应保持持久化格式兼容,或提供经过测试的转换方式。仅凭CSS类一致,无法证明外观或无障碍体验等同。
按需添加功能开关#
功能开关有助于按客户群体开放,或在不部署的情况下回滚。使用Cookie或根据用户适当生成的服务端响应,在启动任何框架之前读取开关。值缺失或无效时,选择现有实现。浏览器可读取的开关控制的是显示,服务端授权仍须独立维护。
准确定义回滚何时生效。即使修改服务端的开放对象列表,已经运行的标签页也不会更新。如果启动后通过/api/me更新Cookie,更新后的选择只会在下次加载文档时应用。要立即恢复,需要明确的更新或重新加载机制;如果开关存储在分布式系统中,生效也可能存在延迟。
对开关的两个取值都执行端到端测试。避免在存入共享缓存的HTML中嵌入客户专属开关,并在回滚支持结束后,将开关与旧代码一并删除。如果需要在同一页面内切换,请重新考虑边界。此时就需要进行本方法刻意避开的集成工作。
下一步#
选择一个风险较低的路由组,制定发布检查清单。其中应包括需要保留的用户流程、允许的差异、数据兼容性,以及已测量恢复耗时的回滚步骤。
来源: https://zenn.dev/yasuakiomokawa/articles/de83bb4c4ea928
目录
