阅读 211

lerna+yarn workspace+monorepo项目实践

这是我参与8月更文挑战的第3天,活动详情查看:8月更文挑战

1. monorepo管理

对于维护过多个package(功能相近)的同学来说,都会遇到一个选择题,这些package是放在一个仓库里维护还是放在多个仓库里单独维护。Multirepo 是比较传统的做法,即每一个 package 都单独用一个仓库来进行管理。Monorepo 是管理项目代码的一个方式,指在一个项目仓库 (repo) 中管理多个模块/包 (package),不同于常见的每个模块建一个 repo。

目前有不少大型开源项目采用了这种方式,如 Babel,React, Meteor, Ember, Angular,Jest, Umijs, Vue, 还有 create-react-app, react-router 等。几乎我们熟知的仓库,都无一例外的采用了monorepo 的方式,可以看到这些项目的第一级目录的内容以脚手架为主,主要内容都在 packages目录中、分多个 package 进行管理。

目录结构如下:

├── packages
 | ├── pkg1
 |  | ├── package.json
 | ├── pkg2
 |  | ├── package.json
├── package.json
复制代码


monorepo 最主要的好处是统一的工作流和Code Sharing。比如我想看一个 pacakge 的代码、了解某段逻辑,不需要找它的 repo,直接就在当前 repo;当某个需求要修改多个 pacakge 时,不需要分别到各自的 repo 进行修改、测试、发版或者 npm link,直接在当前 repo 修改,统一测试、统一发版。只要搭建一套脚手架,就能管理(构建、测试、发布)多个 package。

一图胜千言:


当然到底哪一种管理方式更好,仁者见仁,智者见智。前者允许多元化发展(各项目可以有自己的构建工具、依赖管理策略、单元测试方法),后者希望集中管理,减少项目间的差异带来的沟通成本。

虽然拆分子仓库、拆分子 npm 包是进行项目隔离的天然方案,但当仓库内容出现关联时,没有任何一种调试方式比源码放在一起更高效。

结合shop-service门户的实际场景和业务需要,天然的 MonoRepo ! 一个理想的开发环境可以抽象成这样:

“只关心业务代码,可以直接跨业务复用而不关心复用方式,调试时所有代码都在源码中。”

在前端开发环境中,多 Git Repo,多 npm 则是这个理想的阻力,它们导致复用要关心版本号,调试需要 npm link。而这些是 MonoRepo 最大的优势。

上图中提到的利用相关工具就是今天的主角 Lerna ! Lerna是业界知名度最高的 Monorepo 管理工具,功能完整。

2.lerna

Lerna 是一个管理多个 npm 模块的工具,是 Babel 自己用来维护自己的 Monorepo 并开源出的一个项目。优化维护多包的工作流,解决多个包互相依赖,且发布需要手动维护多个包的问题。

2.1 安装

推荐全局安装,因为会经常用到 lerna 命令

npm i -g lerna
复制代码

2.2 初始化项目

lerna init
复制代码

其中 package.json & lerna.json 如下:

// package.json
{
"name": "root",
"private": true, // 私有的,不会被发布,是管理整个项目,与要发布到npm的解耦
"devDependencies": {
"lerna": "^3.15.0"
}
}

// lerna.json
{
"packages": [
"packages/*"
],
"version": "0.0.0"
}
复制代码

2.3 创建npm包

增加两个 packages

lerna create @mo-demo/cli
lerna create @mo-demo/cli-shared-utils
复制代码

2.4 增加模块依赖

分别给相应的 package 增加依赖模块

lerna add chalk // 为所有 package 增加 chalk 模块
lerna add semver --scope @mo-demo/cli-shared-utils // 为 @mo-demo/cli-shared-utils 增加 semver 模块
lerna add @mo-demo/cli-shared-utils --scope @mo-demo/cli // 增加内部模块之间的依赖
复制代码

2.5 发布

lerna publish
复制代码

2.6 依赖包管理

上述1-5步已经包含了 Lerna 整个生命周期的过程了,但当我们维护这个项目时,新拉下来仓库的代码后,需要为各个 package 安装依赖包。

我们在第4步 lerna add 时也发现了,为某个 package 安装的包被放到了这个 package 目录下的 node_modules 目录下。这样对于多个 package 都依赖的包,会被多个 package 安装多次,并且每个 package 下都维护 node_modules ,也不清爽。于是我们使用 --hoist 来把每个 package 下的依赖包都提升到工程根目录,来降低安装以及管理的成本。

lerna bootstrap --hoist

为了省去每次都输入 --hoist 参数的麻烦,可以在 lerna.json 配置:

{
  "packages": [
    "packages/*"
  ],
  "command": {
    "bootstrap": {
      "hoist": true
    }
  },
  "version": "0.0.1-alpha.0"
}
复制代码

配置好后,对于之前依赖包已经被安装到各个 package 下的情况,我们只需要清理一下安装的依赖即可:

lerna clean
复制代码

然后执行 lerna bootstrap 即可看到 package 的依赖都被安装到根目录下的 node_modules 中了。

3.lerna+monorepo实践

lerna不负责构建,测试等任务,它提出了一种集中管理package的目录模式,提供了一套自动化管理程序,让开发者不必再深耕到具体的组件里维护内容,在项目根目录就可以全局掌控,基于 npm scripts,使用者可以很好地完成组件构建,代码格式化等操作。接下来我们就来看看,如果基于 Lerna,并结合其它工具来搭建 Monorepo 项目的最佳实践。

目前最常见的 monorepo 解决方案是 Lerna 和 yarn 的 workspaces 特性,基于lerna和yarn workspace的monorepo工作流。由于yarn和lerna在功能上有较多的重叠,我们采用yarn官方推荐的做法,用yarn来处理依赖问题,用lerna来处理发布问题。能用yarn做的就用yarn做吧

3.1 yarn workspace

3.1.1 搭建环境
普通项目:clone下来后通过yarn install,即可搭建完项目,有时需要配合postinstall hooks,来进行自动编译,或者其他设置。

monorepo: 各个库之间存在依赖,如A依赖于B,因此我们通常需要将B link到A的node_module里,一旦仓库很多的话,手动的管理这些link操作负担很大,因此需要自动化的link操作,按照拓扑排序将各个依赖进行link

解决方式:通过使用workspace,yarn install会自动的帮忙解决安装和link问题

yarn install # 等价于 lerna bootstrap --npm-client yarn --use-workspaces
复制代码

3.1.2 清理环境
在依赖乱掉或者工程混乱的情况下,清理依赖

普通项目: 直接删除node_modules以及编译后的产物。

monorepo: 不仅需要删除root的node_modules的编译产物还需要删除各个package里的node_modules以及编译产物

解决方式:使用lerna clean来删除所有的node_modules,使用yarn workspaces run clean来执行所有package的清理工作

lerna clean # 清理所有的node_modules
yarn workspaces run clean # 执行所有package的clean操作

3.1.3 安装|删除依赖
普通项目: 通过yarn add和yarn remove即可简单姐解决依赖库的安装和删除问题

monorepo: 一般分为三种场景

给某个package安装依赖:

yarn workspace packageB add packageA 
复制代码

将packageA作为packageB的依赖进行安装

给所有的package安装依赖: 使用yarn workspaces add lodash 给所有的package安装依赖

给root 安装依赖:一般的公用的开发工具都是安装在root里,如typescript,我们使用yarn add -W -D typescript来给root安装依赖

对应的三种场景删除依赖如下

yarn workspace packageB remove packageA
yarn workspaces remove lodash
yarn remove -W -D typescript
复制代码

3.1.4 项目构建

普通项目:建立一个build的npm script,使用yarn build即可完成项目构建

monorepo:区别于普通项目之处在于各个package之间存在相互依赖,如packageB只有在packageA构建完之后才能进行构建,否则就会出错,这实际上要求我们以一种拓扑排序的规则进行构建。

我们可以自己构建拓扑排序规则,很不幸的是yarn的workspace暂时并未支持按照拓扑排序规则执行命令,虽然该 rfc已经被accepted,但是尚未实现, 幸运的是lerna支持按照拓扑排序规则执行命令, --sort参数可以控制以拓扑排序规则执行命令

lerna run --stream --sort build
复制代码

3.1.5 版本升级及发包
项目测试完成后,就涉及到版本发布,版本发布一般涉及到如下一些步骤

条件验证: 如验证测试是否通过,是否存在未提交的代码,是否在主分支上进行版本发布操作

version_bump:发版的时候需要更新版本号,这时候如何更新版本号就是个问题,一般大家都会遵循 semVer语义,

生成changelog: 为了方便查看每个package每个版本解决了哪些功能,我们需要给每个package都生成一份changelog方便用户查看各个版本的功能变化。

生成git tag:为了方便后续回滚问题及问题排查通常需要给每个版本创建一个git tag

git 发布版本:每次发版我们都需要单独生成一个commit记录来标记milestone

发布npm包:发布完git后我们还需要将更新的版本发布到npm上,以便外部用户使用

我们发现手动的执行这些操作是很麻烦的且及其容易出错,幸运的是lerna可以帮助我们解决这些问题

yarn官方并不打算支持发布流程,只是想做好包管理工具,因此这部分还是需要通过lerna支持

lerna提供了publish和version来支持版本的升级和发布, publish的功能可以即包含version的工作,也可以单纯的只做发布操作。

3.3 发布自动生成日志

有了之前的规范提交,自动生成日志便水到渠成了。再详细看下 lerna publish 时做了哪些事情:

3.3.1

lerna version 更新版本 找出从上一个版本发布以来有过变更的 package

提示开发者确定要发布的版本号

将所有更新过的的 package 中的package.json的version字段更新

将依赖更新过的 package 的 包中的依赖版本号更新

更新 lerna.json 中的 version 字段

提交上述修改,并打一个 tag

推送到 git 仓库

 

3.3.2 使用 npm publish 将新版本推送到 npm

CHANGELOG 很明显是和 version 一一对应的,所以需要在 lerna version 中想办法,查看 lerna version 命令的详细说明后,会看到一个配置参数 --conventional-commits。没错,只要我们按规范提交后,在 lerna version 的过程中会便会自动生成当前这个版本的 CHANGELOG。为了方便,不用每次输入参数,可以配置在 lerna.json中,如下:

{
"packages": [
"packages/*"
],
"command": {
"bootstrap": {
"hoist": true
},
"version": {
"conventionalCommits": true
}
},
"ignoreChanges": [
"**/*.md"
],
"version": "0.0.1-alpha.1"
}
复制代码

lerna version 会检测从上一个版本发布以来的变动,但有一些文件的提交,我们不希望触发版本的变动,譬如 .md 文件的修改,并没有实际引起 package 逻辑的变化,不应该触发版本的变更。可以通过 ignoreChanges 配置排除。如上。

实际 lerna version很少直接使用,因为它包含在 lerna publish 中了,直接使用 lerna publish就好了。

3.4 完善的测试用例

monorepo项目:测试有两种方式

使用统一的jest测试配置这样方便全局的跑jest即可,好处是可以方便统计所有代码的测试覆盖率,坏处是如果package比较异构(如小程序,前端,node 服务端等),统一的测试配置不太好编写

每个package单独支持test命令,使用yarn workspace run test,坏处是不好统一收集所有代码的测试覆盖率

如果采用jest编写测试用例,支持typescript的话,需要初始化配置jest.config.js:

module.exports = {
preset: 'ts-jest',
moduleFileExtensions: ['ts'],
testEnvironment: 'node'
}
复制代码

4 实践总结

到这里,基本上已经构建了基于lerna和yarn workspace的monorepo项目的最佳实践了,该有的功能都有:

完善的工作流

typescript支持

风格统一的编码

完整的单元测试

一键式的发布机制

完美的更新日志

文章分类
前端
文章标签