阅读 2279

Monorepo实战

前言

由于网上很多关于monorepo的文章分享跟着做都会有很多报错, 所以想记录下来...

维护多个仓库的公共代码是一件头疼的事情,每次对公共代码的改动都要全量仓库同步,最后决定用 monorepo 改造一番。

Monorepo

Monorepo(monolithic repository) 单体仓库是管理项目代码的一个方式,指在一个项目仓库 (repo) 中管理多个模块/包 (package),不同于常见的每个模块建一个 repo。

目前不少大型开源项目采用了这种方式,如 BabelReactVue 等。monorepo 管理代码只要搭建一套脚手架,就能管理(构建、测试、发布)多个 package。

在项目的第一级目录的内容以脚手架为主,主要内容都在 packages 目录中、分多个 package 进行管理。目录结构大致如下:

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

此时会有一个问题,虽然拆分子 npm 包管理项目简单了很多,但是当仓库内容有关联时,调试变得困难。所以理想的开发环境应该是只关心业务代码,可以直接跨业务复用而不关心复用方式,调试时所有代码都在源码中。

目前最常见的 monorepo 解决方案是 lerna 和 yarn 的 workspaces 特性。用 yarn 处理依赖问题,lerna处理发布问题。

Lerna

Lerna是npm模块的管理工具,为项目提供了集中管理package的目录模式,如统一的 repo 依赖安装、package scripts和发版等特性。

安装

建议全局安装

npm i -g lerna
复制代码

初始化项目

lerna init
复制代码

初始化后,会生成 packages 空目录和 package.json 和 lerna.json 配置文件,配置文件如下:

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

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

创建npm包

执行命令后可修改包信息,这里创建 @monorepo/components 和 @monorepo/utils

lerna create @monorepo/components
复制代码

安装依赖

lerna和yarn workspace安装依赖的方法都鸡肋

lerna add lodash // 为所有 package 增加 lodash 模块 

// 为 @monorepo/utils 增加 lodash 模块(lodash可替换为内部模块,如@monorepo/components)
lerna add lodash --scope @monorepo/utils  
复制代码

lerna add的鸡肋之处是一次只能安装一个包...

依赖包管理

一般情况下 package 的依赖都是在各自的 node_modules 目录下,这不仅增加了包的安装和管理成本,还可能会出现同一个依赖有多个的情况。所以可把所有 package 的依赖包都提升到工程根目录。

lerna 和 yarn workspace都可以把依赖包提升到 repo 根目录管理。lerna 在安装依赖时(lerna bootstrap)提供了--hoist选项,但其鸡肋的地方在于,由于 lerna 直接以字符串对比 dependency 的版本号,同一个依赖在版本号完全相同时才会提升到根目录下,举个栗子:

A 依赖了 @babel/core@^7.10.0
B 依赖了 @babel/core@^7.11.4
复制代码

lerna 会在 A 的 node_modules 目录下安装 7.11.4 版本的 babel/core,并在 A 目录下生成了一份 package-lock.json,这无疑加大了维护成本和包的体积。

而yarn workspace在这种情况下只会在根目录有一份yarn-lock.json,也不会重复在子目录下安装依赖。

yarn workspace

搭建环境

主要是为安装依赖的配置调整。

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

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

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

package.json & lerna.json 如下:

//lerna.json
{
  "packages": ["packages/*"],
  "npmClient": "yarn",
  "useWorkspaces": true, // 使用yarn workspaces
  "version": "0.0.0"
}

//package.json
{
  "name": "root",
  "private": true,
  "workspaces": [ //指定workspace路径
    "packages/*"
  ],
  "devDependencies": {
    "lerna": "^3.22.1"
  }
}
复制代码

清理环境

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

lerna clean # 清理所有packages的node_modules目录,不能删除根目录的node_modules
yarn workspaces run clean # 执行所有package的clean操作(应是需自行写脚本)
复制代码

看过的资料都说lerna clean可以删除根目录的依赖,实际感觉是不行,官网原话是

lerna clean does not remove modules from the root node_modules directory, even if you have the --hoist option enabled.

安装/删除依赖

一般分为三种场景

  • 给某个 package 安装/删除依赖
  • 给 root 安装/删除依赖,一般的公用的开发工具都是安装在 root 里,如 typescript
  • 给所有 package 安装/删除依赖

关于最后一种情况,网上均显示 yarn workspaces add/remove lodash 可以给所有包安装/删除依赖,然而用就是报错 - error Invalid subcommand. Try "info, run",yarn 2.0 只能用 yarn workspaces foreach,运行前要装 workspace-tools 插件,但还没有时间尝试过...所以这里只说前两种情况。

安装/删除依赖对应场景依次如下:

yarn workspace packageA add/remove packageB [packageC -D -W] //为 packageA 安装/删除 packageB、C 依赖
yarn add/remove typescript -W -D // 给 root 安装/删除 typescript
复制代码

⚠️注意:当使用 yarn workspace packageA add xxx 安装时,将会再次安装 packageA 的所有依赖且安装在到 packageA 目录下。要安装到根目录加配置 -W

对于安装local dependency,yarn的实现暂时有bug,第一次安装需要指明版本号,否则会安装失败如下:

如果ui-button没有发布到npm则 yarn workspace ui-form add ui-button 会安装失败,但是 yarn workspace ui-form add ui-button@1.0.0会成功 ,可见详情

安装完依赖文件结构如下:

提交规范

在构建和发布之前还需要做一些关于代码提交的配置

commitizen && cz-lerna-changelog

commitizen 是用来格式化 git commit message 的工具,它提供了一种问询式的方式去获取所需的提交信息。

cz-lerna-changelog 是专门为 Lerna 项目量身定制的提交规范,在问询的过程,会有类似影响哪些 package 的选择。如下: 我们使用 commitizen 和 cz-lerna-changelog 来规范提交,为后面自动生成日志作好准备。 因为这是整个工程的开发依赖,所以在根目录安装:

yarn add commitizen cz-lerna-changelog -D -W
复制代码

安装完成后,在 package.json 中增加 config 字段,把 cz-lerna-changelog 配置给 commitizen。同时因为commitizen不是全局安全的,所以需要添加 scripts 脚本来执行 git-cz

{
  "name": "monorepo",
  "private": true,
  "workspaces": [
    "packages/*"
  ],
  "scripts": {
    "commit": "git-cz"
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-lerna-changelog"
    }
  },
  "devDependencies": {
    "commitizen": "^4.2.1",
    "cz-lerna-changelog": "^2.0.3",
    "lerna": "^3.22.1"
  }
}
复制代码

之后在常规的开发中就可以使用 yarn run commit 来根据提示一步一步输入,来完成代码的提交。

commitlint && husky

以下配置是强制开发者遵循上述规范,可暂时跳过,因为提交起来略久……

上面我们使用了 commitizen 来规范提交,但很难靠开发自觉使用 yarn run commit 。万一忘记了,或者直接使用 git commit 提交怎么办?所以在提交时校验提交信息,如果不符合要求就不让提交,并提示。校验的工作由 commitlint 来完成,校验的时机则由 husky 来指定。husky 继承了 Git 下所有的钩子,在触发钩子的时候,husky 可以阻止不合法的 commit,push 等等。

安装 commitlint 以及要遵守的规范:

yarn add -D -W husky @commitlint/cli @commitlint/config-conventional
复制代码

在工程根目录为 commitlint 增加配置文件 commitlint.config.js 为commitlint 指定相应的规范

module.exports = { 
	extends: ['@commitlint/config-conventional'] 
}
复制代码

在 package.json 中增加如下配置

"husky": { 
 		"hooks": { 
    		"commit-msg": "commitlint -E HUSKY_GIT_PARAMS" 
     }
 }
复制代码

"commit-msg"是git提交时校验提交信息的钩子,当触发时便会使用 commitlint 来校验。安装配置完成后,想通过 git commit 或者其它第三方工具提交时,只要提交信息不符合规范就无法提交。从而约束开发者使用 yarn run commit 来提交。

eslint && lint-staged

原本想先跳过eslint的规范的……然而如果项目已经有eslint,而npm包没有,调试都会报错,原以为一个.eslintlrc文件和装eslint插件就能解决问题,然而并没有这么简单,累了……后期补上解决问题的过程

除了规范提交信息,代码本身肯定也少了靠规范来统一风格。

yarn add -D -W standard lint-staged
复制代码

eslint就是完整的一套 JavaScript 代码规范,自带 linter & 代码自动修正。自动格式化代码并修正,提前发现风格以及程序问题, 同时也支持javascript的代码规范校验,eslintrc.json:

module.exports = {
  env: {
    browser: true,
    es2020: true
  },
  extends: ["eslint:recommended", "plugin:vue/essential"],
  parserOptions: {
    parser: "babel-eslint"
  },
  plugins: ["vue"],
  rules: {
    "prettier/prettier": [
      "off",
      {
        quotes: 0
      }
    ]
  }
}
复制代码

lint-staged staged 是 Git 里的概念,表示暂存区,lint-staged 表示只检查并矫正暂存区中的文件。一来提高校验效率,二来可以为老的项目带去巨大的方便。

package.json配置

{
  "name": "monorepo",
  "private": true,
  "workspaces": [
    "packages/*"
  ],
  "scripts": {
    "c": "git-cz"
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-lerna-changelog"
    }
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.(vue|js)": [
      //"eslint --fix",
      "prettier --write"
    ]
  },
  "devDependencies": {
    "commitizen": "^4.2.1",
    "cz-lerna-changelog": "^2.0.3",
    "lerna": "^3.22.1",
    "lint-staged": "^10.2.13",
    "standard": "^14.3.4"
  }
}
复制代码

安装完成后,在 package.json 增加 lint-staged 配置 "prettier --write",校验时机定在pre-commit,在husky的配置中增加pre-commit的钩子用来执行 lint 校验。

eslint --fix 校验并自动修复慎用,分分钟提交不了……

使用 Lerna 构建和发布

项目构建

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

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

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

可在根目录的package.json下配置

"scripts": {
    "build": "lerna run --stream --sort build"
  },
复制代码

版本升级及发包

历经重重困难终于到了发布最后一步了

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

  • 条件验证: 如验证测试是否通过,是否存在未提交的代码,是否在主分支上进行版本发布操作
  • version_bump:发版的时候需要更新版本号,这时候如何更新版本号就是个问题,一般大家都会遵循 semVer语义
  • 生成changelog: 为了方便查看每个package每个版本解决了哪些功能,我们需要给每个package都生成一份changelog方便用户查看各个版本的功能变化。
  • 生成git tag:为了方便后续回滚问题及问题排查通常需要给每个版本创建一个git tag
  • git 发布版本:每次发版我们都需要单独生成一个commit记录来标记milestone
  • 发布npm包:发布完git后我们还需要将更新的版本发布到npm上,以便外部用户使用

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

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

只发布某个package

lerna官方不支持仅发布某个package,github.com/lerna/lerna…

由于 lerna 会自动的监测 git 提交记录里是否包含指定 package 的文件修改记录,来确定版本更新,这要求设置好合理的 ignore 规则(否则会造成频繁的,无意义的某个版本更新),好处是其可以自动的帮助 package 之间更新版本

例如如果 ui-form 依赖了 ui-button,如果 ui-button 发生了版本变动,会自动的将 ui-form 的对 ui-button 版本依赖更新为 ui-button 的最新版本。 如果 ui-form 发生了版本变动,对 ui-button 并不会造成影响。

经测试 version_bump 是依赖于文件检测和 subject 结合,并不依赖于 scope,scope 的作用是用来生成 changelog 的吧,即如果是修改了 ui-form 的文件,但是 commit 记录写的是 fix(ui-button),lerna 是会生成 ui-form 的版本更新,并不会去更新 ui-button 的版本。

发布自动生成日志

有了之前的规范提交,自动生成日志便水到渠成了。leran publish 时主要做了以下事情:

lerna version 更新版本

  • 找出从上一个版本发布以来有过变更的 package
  • 提示开发者确定要发布的版本号
  • 将所有更新过的的 package 中的package.json的version字段更新
  • 将依赖更新过的 package 的 包中的依赖版本号更新
  • 更新 lerna.json 中的 version 字段
  • 提交上述修改,并打一个 tag
  • 推送到 git 仓库

lerna publish

版本自动更新可使用--conventional-commits 参数会自动的根据conventional commit规范和git commit message记录帮忙确定更新的版本号:

// lerna.json
{
  "packages": ["packages/*"],
  "npmClient": "yarn",
  "useWorkspaces": true,
  "command": {
    "version": {
      "conventionalCommits": true # 生成changelog文件以及根据commit来进行版本变动
    }
  },
  "ignoreChanges": ["**/*.md"], # md文件更新,不触发版本变动
  "version": "0.0.0"
}
复制代码

包内的 package.json 还需 publishConfig 配置

"publishConfig": {
   "access": "publish" // 如果该模块需要发布,对于scope模块,需要设置为publish,否则需要权限验证
  }
复制代码

最后执行命令发布

lerna publish [from-git]
复制代码

如果第一次没发成功但是却显示成功了,则要加from-git才能重新发,发布也还有一些坑……

完善的测试用例

monorepo项目:测试有两种方式

  • 使用统一的 jest 测试配置这样方便全局的跑 jest 即可,好处是可以方便统计所有代码的测试覆盖率,坏处是如果 package 比较异构(如小程序,前端,node 服务端等),统一的测试配置不太好编写
  • 每个 package 单独支持test命令,使用 yarn workspace run test,坏处是不好统一收集所有代码的测试覆盖率

此处附上 typescript 的测试例子,初始化配置 jest.config.js:

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

最后附上 github 地址:github.com/moon-bonny/…

readme 还未来得及完善……

相关文章

vue组件打包篇

未完待续……

后续有时间再出踩坑篇

本文部分内容转载于:mp.weixin.qq.com/s/NlOn7er0i…

文章分类
前端
文章标签