Open worldzhao opened 2 years ago
五月份分享了 应用级 Monorepo 优化方案 ,主要阐述了之前 monorepo (Yarn + Lerna)存在的问题以及解决方案,但在该分享里,并没有涉及到 pacakge 发布相关的内容(在那段时期主要是以应用 app 开发为主),偶有 pacakge 开发也是依赖关系较为简单的场景(单包开发/发布),使用 npm publish 就能搞定。
npm publish
随着后续的发展(主要是团队内另一个仓库的迁入),package 开发场景占了相当重的比例(仓库代码行数达到了百万级,项目数超过 100),但多包发布体验并不是很好,主要集中在以下 3 个方面:
本次分享便是为了解决以上问题,在实际中摸索出 Monorepo 多包发布场景的较佳实践。
在进行讨论之前,先要了解 Workspace protocol (workspace:),这里以 pnpm 为例,下述例子摘自 Workspace | pnpm
默认情况下,如果工作区中可用的包版本与声明的范围相匹配,pnpm 将从工作区链接包。比如 monorepo 中存在 foo@1.0.0,而 monorepo 内另一个项目 bar 依赖 "foo: ^1.0.0",那么 bar 就会使用工作区中的 foo,倘若 bar 依赖 "foo: 2.0.0",那么 pnpm 将会从远端下载 foo@2.0.0 供 bar 使用,这就引入了一些不确定性。
foo@1.0.0
"foo: ^1.0.0"
"foo: 2.0.0"
foo@2.0.0
使用 workspace 协议时,pnpm 将拒绝解析为本地工作区包以外的任何内容。因此,如果设置 "foo": "workspace:2.0.0",这次安装将失败,因为工作区中不存在 "foo@2.0.0"。
"foo": "workspace:2.0.0"
"foo@2.0.0"
相较于传统单仓库单包一个一个的去手动进行发布行为,monorepo 的优势之一就是可以方便地进行多包发布。
在 Rush monorepo 中,rush change 是发包流程的起点,其产物 <branchname>-<timestamp>.json(后文用 changefile.json 代替)会被 rush version 以及 rush publish 消费。
rush change
<branchname>-<timestamp>.json
rush version
rush publish
changefile.json 生成流程如下:
git diff
common/changes
注意:截图中的变更类型( type 字段)为 none,不是 major/minor/patch 中的任何一种, none 意味着 "将这些变更滚入下一个补丁(patch)、次要变更(minor)或主要变更(major)",因此理论上,如果一个项目只存在类型为 "none "的变更文件,它既不会消耗文件,也不会提升版本。
type: none 的特性使得我们可以将已开发完毕但不需要跟随下一次发布周期的 package 提前合入 master,直到该 pacakge 出现 type 不为 none 的 changefile.json。
type: none
rush version 或 rush publish --apply 则会基于生成的 changefile.json 进行版本号的更新(即 bump version,遵循 semver 规范,被发布 package 的上层 package 的版本号可能会被更新,下一小节会详细描述)。
rush publish --apply
rush publish --publish 则会基于 changefile.json 进行对应 package 的发布。
rush publish --publish
Rush 的发布流程与另一个流行的 Monorepo 场景发包工具 Changesets 基本一致 ,遇到单纯的 PNPM Monorepo 也许可以基于 Changesets 复用本文方案 🥳 。
前面有提到在更新版本号时,除了更新当前需要被发布的 package 的版本号,也可能更新其上层 package 的版本号,这取决于上层 package 在 package.json 中如何引用当前 package 的。
如下所示,@modern-js/plugin-tailwindcss(上层 package) 通过 "workspace:^1.0.0" 的形式引入 @modern-js/utils(底层 package)。
@modern-js/plugin-tailwindcss
"workspace:^1.0.0"
@modern-js/utils
package.json(@modern-js/plugin-tailwindcss)
{ "name": "@modern-js/plugin-tailwindcss", "version": "1.0.0", "dependencies": { "@modern-js/utils": "workspace:^1.0.0" } }
package.json(@modern-js/utils)
{ "name": "@modern-js/utils", "version": "1.0.0" }
若 @modern-js/utils 更新至 1.0.1 ,Rush 在更新版本号时不会更新 @modern-js/plugin-tailwindcss 的版本号。因为 ^1.0.0 兼容 1.0.1,从语义的角度出发,@modern-js/plugin-tailwindcss 不需要更新版本号,直接安装 @modern-js/plugin-tailwindcss@1.0.0 是可以获取到 @modern-js/utils@1.0.1的
1.0.1
^1.0.0
@modern-js/plugin-tailwindcss@1.0.0
@modern-js/utils@1.0.1
若 @modern-js/utils 更新至 2.0.0 ,Rush 在更新版本号时会更新 @modern-js/plugin-tailwindcss 的版本号至 1.0.1。因为 ^1.0.0 不兼容 2.0.0,更新 @modern-js/plugin-tailwindcss 版本至 1.0.1 才可引用到最新的 @modern-js/utils@2.0.0,此时 @modern-js/plugin-tailwindcss 的 package.json 内容如下:
2.0.0
@modern-js/utils@2.0.0
{ "name": "@modern-js/plugin-tailwindcss", "version": "1.0.1", "dependencies": { // 引用版本号也发生了变化 "@modern-js/utils": "workspace:^2.0.0" } }
更新了版本号,还需要发布至 npm。此时需要 rush publish 增加 --include-all 参数,配置该参数后 rush publish 检查到仓库中存在 shouldPublish: true 的 package 的版本新于 npm 版本时,会将该 package 发布。
--include-all
shouldPublish: true
这样就完成了基于语义化的级联发布。
最开始基于 Rush 改造项目时,monorepo 内的项目之间始终使用 "workspace: *" 互相引用,即使用 monorepo 内最新版本。
"workspace: *"
这就导致了两个问题:
*
所以,monorepo 内项目之间的引用需要遵循以下规范。
workspace:
"workspace: ^x.x.x"
随着 monorepo 内项目数日益增长,项目之间若全部使用 workspace: 引用,那么一个 package 更新时,需要其所有内部接入方被动进行回归测试
通过 CI 提高 master 分支准入标准当然没问题,但是业务场景往往过于复杂,还是需要测试同学的介入,除非团队成员代码质量以及测试质量极高。 或者使用 feature flag 机制进行控制,但人工控制往往成本较大,需要成熟的基建方案配合。
通过 CI 提高 master 分支准入标准当然没问题,但是业务场景往往过于复杂,还是需要测试同学的介入,除非团队成员代码质量以及测试质量极高。
或者使用 feature flag 机制进行控制,但人工控制往往成本较大,需要成熟的基建方案配合。
而对于业务关联并不紧密的项目,他们仅仅是在物理层面存在于同一个 monorepo 内罢了,并不需要关注对方最新版本,并不需要使用 workspace:。
举个例子:把 babel/react/modernjs 等套件放到同一个 monorepo 管理,各套件内部使用 workspace: 享受 monorepo 工程优势合情合理,项目之间依赖则直接使用 npm 稳定版本更合适。
当然开源项目的业务边界都很明显,而具体到我们的业务仓库(一个团队一个仓库),里面可能放着许多八竿子打不着的模块,这个时候使用 workspace: 便是自讨苦吃了。
那么如何判断是否需要使用 workspace: ?
举个例子,假设我是包 bar 的 owner,现在要引用一个包 foo,需要通过以下判断:
foo 更新,bar 一定会更新并进行测试且迭代上线节奏一致,那么使用 workspace:,否则一律使用 npm 远端版本。
需要注意的是:
type: major/minor/patch
可以看到,发布流程中的前三个步骤都是一致的:
但这套方案刚刚落地时,使用的是「全量安装 monorepo 依赖并全量构建 packages 」这种简单粗暴的方式。
monorepo 需要解决的是规模性问题:项目越来越大,依赖安装越来越慢,构建越来越慢,跑测试用例越来越慢。 「按需」就成为了关键词,pnpm 作为包管理器已经非常优秀,甚至可以按需安装依赖,但对于大型 monorepo 需要的能力还是有所欠缺的,所以我们引入了 Rush 解决 monorepo 下的工程化问题。 所以目标很明确:在 monorepo 规模越来越大的情况下,整个项目的复杂度始终维持在一个稳定的水准。 —— 应用级 Monorepo 优化方案
monorepo 需要解决的是规模性问题:项目越来越大,依赖安装越来越慢,构建越来越慢,跑测试用例越来越慢。
「按需」就成为了关键词,pnpm 作为包管理器已经非常优秀,甚至可以按需安装依赖,但对于大型 monorepo 需要的能力还是有所欠缺的,所以我们引入了 Rush 解决 monorepo 下的工程化问题。
所以目标很明确:在 monorepo 规模越来越大的情况下,整个项目的复杂度始终维持在一个稳定的水准。 —— 应用级 Monorepo 优化方案
在优化之前,发布一次接近 12min,哪怕只要发布一个包,并且这个包里只有一句 console.log("hello world"),而且随着项目的增多,12min 可能只是起点。所以「按需」又回到了我们的视线。
console.log("hello world")
Rush 在发布流程中会改变需要发布的项目的版本号,只要将这个过程提前,预先获取改变了版本号的项目,就能得到 install 与 build 命令的目标参数。
于是通过翻阅 @microsoft/rush-lib 的 rush version 相关源码,得到了以下代码:
@microsoft/rush-lib
function getVersionUpdatedPackages(params: { rushConfiguration: RushConfiguration; prereleaseName?: string; }) { const { prereleaseName, rushConfiguration } = params; const changeManager: ChangeManager = new ChangeManager(rushConfiguration); if (prereleaseName) { const prereleaseToken = new PrereleaseToken(prereleaseName); changeManager.load(rushConfiguration.changesFolder, prereleaseToken); } else { changeManager.load(rushConfiguration.changesFolder); } // 改变 package.json 版本号(内存中,实际文件不做改动) changeManager.apply(false); return rushConfiguration.projects.reduce((accu, project) => { const packagePath: string = path.join( project.projectFolder, FileConstants.PackageJson, ); // 实际 package.json 的版本号 const oldVersion = (JsonFile.load(packagePath) as IPackageJson).version; // 内存中 package.json 的版本号 const newVersion = project.packageJsonEditor.version; // 不一致则为我们的目标项目 if (oldVersion !== newVersion) { accu.push({ name: project.packageName, oldVersion, newVersion }); } return accu; }, [] as UpdatedPackage[]); }
更新:可以通过 pnpm overrides 配置项解决该问题。
源自接入方 lockfile 造成的困扰。该命令可以为未变更的 package 生成 changefile.json,使其可以被发布。
rush change 命令默认会比对当前分支与 master 分支的差异,找出产生变更的项目,通过交互式命令行让开发者生成对应的 changefile.json 文件。
前面「级联发布」中有提到,Rush 可以根据 semver 规范更新相关包的版本并进行发布,在 "workspace: ^x.x.x" 的引用方式下,除非底层包进行 major 更新,否则上层包是不会更新发布的。
问题就在于此,上层包没有被发布,底层包又被接入方的 lockfile 锁住了,我们(被迫)需要一种方案能够发布实际上不需要发布的包(这里是 @jupiter/block-tools),这就是 rush change-extra 诞生的原因。
更需要一种能够深度更新指定依赖的方式,但目前没有找到包管理器维度的解决方案 更新:可以通过 pnpm overrides 配置项解决该问题。
本文通过 Rush 基本的发包操作入手,介绍了在实际开发过程中会遇到的一些问题并给出了整体落地的方案,同时基于「按需」的思路优化线上发布速度。
这里的流水线是基于哪个工具做的
我们公司内部的一个发布平台,用 gitlab 的 CI 也可以
前言
五月份分享了 应用级 Monorepo 优化方案 ,主要阐述了之前 monorepo (Yarn + Lerna)存在的问题以及解决方案,但在该分享里,并没有涉及到 pacakge 发布相关的内容(在那段时期主要是以应用 app 开发为主),偶有 pacakge 开发也是依赖关系较为简单的场景(单包开发/发布),使用
npm publish
就能搞定。随着后续的发展(主要是团队内另一个仓库的迁入),package 开发场景占了相当重的比例(仓库代码行数达到了百万级,项目数超过 100),但多包发布体验并不是很好,主要集中在以下 3 个方面:
本次分享便是为了解决以上问题,在实际中摸索出 Monorepo 多包发布场景的较佳实践。
Workspace protocol (workspace:)
在进行讨论之前,先要了解 Workspace protocol (workspace:),这里以 pnpm 为例,下述例子摘自 Workspace | pnpm
默认情况下,如果工作区中可用的包版本与声明的范围相匹配,pnpm 将从工作区链接包。比如 monorepo 中存在
foo@1.0.0
,而 monorepo 内另一个项目 bar 依赖"foo: ^1.0.0"
,那么 bar 就会使用工作区中的 foo,倘若 bar 依赖"foo: 2.0.0"
,那么 pnpm 将会从远端下载foo@2.0.0
供 bar 使用,这就引入了一些不确定性。使用 workspace 协议时,pnpm 将拒绝解析为本地工作区包以外的任何内容。因此,如果设置
"foo": "workspace:2.0.0"
,这次安装将失败,因为工作区中不存在"foo@2.0.0"
。多包发布
基础操作
相较于传统单仓库单包一个一个的去手动进行发布行为,monorepo 的优势之一就是可以方便地进行多包发布。
rush change
在 Rush monorepo 中,
rush change
是发包流程的起点,其产物<branchname>-<timestamp>.json
(后文用 changefile.json 代替)会被rush version
以及rush publish
消费。changefile.json 生成流程如下:
git diff
命令);common/changes
目录下生成对应 package 的 changefile.json。type: none
的特性使得我们可以将已开发完毕但不需要跟随下一次发布周期的 package 提前合入 master,直到该 pacakge 出现 type 不为 none 的 changefile.json。rush version 与 rush publish
rush version
或rush publish --apply
则会基于生成的 changefile.json 进行版本号的更新(即 bump version,遵循 semver 规范,被发布 package 的上层 package 的版本号可能会被更新,下一小节会详细描述)。rush publish --publish
则会基于 changefile.json 进行对应 package 的发布。Rush 的发布流程与另一个流行的 Monorepo 场景发包工具 Changesets 基本一致 ,遇到单纯的 PNPM Monorepo 也许可以基于 Changesets 复用本文方案 🥳 。
级联发布
前面有提到在更新版本号时,除了更新当前需要被发布的 package 的版本号,也可能更新其上层 package 的版本号,这取决于上层 package 在 package.json 中如何引用当前 package 的。
如下所示,
@modern-js/plugin-tailwindcss
(上层 package) 通过"workspace:^1.0.0"
的形式引入@modern-js/utils
(底层 package)。package.json(@modern-js/plugin-tailwindcss)
package.json(@modern-js/utils)
若
@modern-js/utils
更新至1.0.1
,Rush 在更新版本号时不会更新@modern-js/plugin-tailwindcss
的版本号。因为^1.0.0
兼容1.0.1
,从语义的角度出发,@modern-js/plugin-tailwindcss
不需要更新版本号,直接安装@modern-js/plugin-tailwindcss@1.0.0
是可以获取到@modern-js/utils@1.0.1
的若
@modern-js/utils
更新至2.0.0
,Rush 在更新版本号时会更新@modern-js/plugin-tailwindcss
的版本号至1.0.1
。因为^1.0.0
不兼容2.0.0
,更新@modern-js/plugin-tailwindcss
版本至1.0.1
才可引用到最新的@modern-js/utils@2.0.0
,此时@modern-js/plugin-tailwindcss
的 package.json 内容如下:更新了版本号,还需要发布至 npm。此时需要
rush publish
增加--include-all
参数,配置该参数后rush publish
检查到仓库中存在shouldPublish: true
的 package 的版本新于 npm 版本时,会将该 package 发布。这样就完成了基于语义化的级联发布。
意料之外的发布
最开始基于 Rush 改造项目时,monorepo 内的项目之间始终使用
"workspace: *"
互相引用,即使用 monorepo 内最新版本。这就导致了两个问题:
"workspace: *"
,所以底层包更新,上层包必然发布(为了保证*
的语义)所以,monorepo 内项目之间的引用需要遵循以下规范。
引用规范
workspace:
引用 monorepo 内的最新版本workspace:
,那么请使用"workspace: ^x.x.x"
代替"workspace: *"
,避免无意义的发布(当然也要考虑实际依赖关系,如果 packageA 与 packageB 始终需要一起发布,就应当使用"workspace: *"
)随着 monorepo 内项目数日益增长,项目之间若全部使用
workspace:
引用,那么一个 package 更新时,需要其所有内部接入方被动进行回归测试而对于业务关联并不紧密的项目,他们仅仅是在物理层面存在于同一个 monorepo 内罢了,并不需要关注对方最新版本,并不需要使用
workspace:
。举个例子:把 babel/react/modernjs 等套件放到同一个 monorepo 管理,各套件内部使用
workspace:
享受 monorepo 工程优势合情合理,项目之间依赖则直接使用 npm 稳定版本更合适。当然开源项目的业务边界都很明显,而具体到我们的业务仓库(一个团队一个仓库),里面可能放着许多八竿子打不着的模块,这个时候使用
workspace:
便是自讨苦吃了。那么如何判断是否需要使用
workspace:
?举个例子,假设我是包 bar 的 owner,现在要引用一个包 foo,需要通过以下判断:
foo 更新,bar 一定会更新并进行测试且迭代上线节奏一致,那么使用
workspace:
,否则一律使用 npm 远端版本。工作流
需要注意的是:
type: none
的 changefile.json,这是为了避免其他 package 发布时带上处于开发过程中的包type: major/minor/patch
的 changefile.json 在测试分支进行测试包发布,所以测试阶段则不进行合入,待验收完毕后合入进行正式版本发布。流水线详解
测试版本
正式版本
发布加速
可以看到,发布流程中的前三个步骤都是一致的:
但这套方案刚刚落地时,使用的是「全量安装 monorepo 依赖并全量构建 packages 」这种简单粗暴的方式。
在优化之前,发布一次接近 12min,哪怕只要发布一个包,并且这个包里只有一句
console.log("hello world")
,而且随着项目的增多,12min 可能只是起点。所以「按需」又回到了我们的视线。Rush 在发布流程中会改变需要发布的项目的版本号,只要将这个过程提前,预先获取改变了版本号的项目,就能得到 install 与 build 命令的目标参数。
于是通过翻阅
@microsoft/rush-lib
的rush version
相关源码,得到了以下代码:辅助命令
rush change-extra
源自接入方 lockfile 造成的困扰。该命令可以为未变更的 package 生成 changefile.json,使其可以被发布。
rush change
命令默认会比对当前分支与 master 分支的差异,找出产生变更的项目,通过交互式命令行让开发者生成对应的 changefile.json 文件。前面「级联发布」中有提到,Rush 可以根据 semver 规范更新相关包的版本并进行发布,在
"workspace: ^x.x.x"
的引用方式下,除非底层包进行 major 更新,否则上层包是不会更新发布的。问题就在于此,上层包没有被发布,底层包又被接入方的 lockfile 锁住了,我们(被迫)需要一种方案能够发布实际上不需要发布的包(这里是 @jupiter/block-tools),这就是 rush change-extra 诞生的原因。
结语
本文通过 Rush 基本的发包操作入手,介绍了在实际开发过程中会遇到的一些问题并给出了整体落地的方案,同时基于「按需」的思路优化线上发布速度。