预研jsframework重构
src中的源码来自:https://gitlab.vmic.xyz/minigame/jsframework/tree/feature_minigame_v1.6.0_base_v1.5.0 版本号:54d0f88e96c5b644b809d81fe5c57fc4eb726089
minigame-jsframework 是vivo小游戏的前端引擎实现。是对原来的jsframework的重构。引入如下新功能:
-
JavaScript 代码规范,自带 linter & 代码自动修正,节省大量时间
无须配置 史上最便捷的统一代码风格的方式,轻松拥有
自动代码格式化 只需运行 standard --fix 从此和脏乱差的代码说再见
提前发现风格及程序问题 减少代码审查过程中反反复复的修改过程,节约时间
-
Commit规范 标准化Git的Commit Message,保证代码提交格式统一
cz-conventional-changelog commitizen 的一个适配器,可以自动生成
CHANGELOG.md
commitlint 会检查提交是否符合规定的格式,对于不符合规范的格式,不允许提交,防止通过其他途径进行不合规范的提交
使用 commitizen 规范后,代码提交时会提示输入相应的字段,如下三个字段比较重要
type 用于说明 commit 的类别,只允许使用下面10个标识
- feat:新功能(feature)
- fix:修补bug
- docs:文档(documentation)
- style: 格式(不影响代码运行的变动,空格,格式,缺少分号等)
- refactor:重构(即不是新增功能,也不是修改bug的代码变动)
- perf: 代码性能优化
- build: 构建工具或外部依赖的更改(npm,webpack,gulp等)
- ci: 更改项目级的配置文件或脚本
- test:增加测试
- chore:除上述之外的修改
如果 type 为 feat 和 fix,则该 commit 将会出现在 changelog 文件中
scope 用于说明 commit 影响的范围,比如数据层、控制层、视图层等等,视项目不同而不同
subject commit 目的的简短描述
-
版本管理工具,根据提交信息生成日志,检测生成并修改版本号,提交相应的修改并自动添加tag
-
拦截git操作的工具,本项目中使用它在提交代码之前,进行代码的
stanard
检查,并自动修复,避免不符合格式的代码被提交。因为只想对已经产生改动的文件,进行检查,避免检查并没有改动的文件,
lint-staged
工具就是为了只检查缓存区的文件 -
统一了打包工具,所有项目使用webpack打包
-
升级了Babel为最新的版本,新引入根据引擎版本号来适配ES6,而不是全部做兼容适配
-
Facebook出品的一款前端单元测试框架,目前对所有native的代码覆盖单元测试
scripts
"scripts": {
"test": "jest",
"c": "git-cz",
"dev": "webpack --config config/webpack.dev.config.js",
"release": "webpack --config config/webpack.release.config.js",
"publish": "cross-env CI=true npm run dev && CI=true npm run release && babel-node tasks/publish.js",
"p": "standard-version",
"p-fix": "standard-version --prerelease fix --release-as patch",
"p-plugin": "standard-version --prerelease plugin --release-as patch",
"p-dev": "standard-version --prerelease dev --release-as minor",
"p-patch": "standard-version --release-as patch",
"p-minor": "standard-version --release-as minor",
"p-major": "standard-version --release-as major"
}
-
test
执行单元测试。由 gitlab ci 调用,每次提交都会跑一遍单元测试 -
c
commit的简写。npm run c
提交代码,按照提示输入必要的提交信息 -
dev
构建开发包npm run dev
用于生成没有混淆的文件,并且会实时检测文件变动,重新生成文件并推送到手机SD卡。方便开发调试 -
release
构建发布包,一般不需要使用,因为构建发布包由 gitlab ci完成了 -
publish
发布版本。由 gitlab ci 在检测到有带 tag 的提交时调用 -
p
发布版本npm run p
会在控制台输出要生成的版本信息,并不会执行实际操作,确认没问题后,npm run p -- --dry-run=false
会生成日志,并修改版本号并打上tag上传到仓库。请参考 standard-version 的文档 -
p-fix
发布问题修复版本。npm run p-fix
用于发布问题修复版本,用于发布 bugfix 分支,修复线上问题。 -
p-plugin
发布特性版本。npm run p-plugin
用于发布特性版本,由于项目的特殊性,一般都是发布特性版本和全量版本这两种,特性版本的版本名称就是这次特性发布的功能 -
p-dev
发布开发版本。npm run p-dev
用于发布开发版本,用于发布 feature 分支,一般用于开发新功能 -
p-patch
发布正式的patch版本。npm run p-patch
用于发布 bugfix 分支 -
p-minor
发布正式的minor版本。npm run p-minor
用于发布 feature 分支 -
p-major
用于发布主版本,暂时没有使用场景
代码拉下来后,先
npm install
安装依赖的模块
当修改代码后,需要提交。提交的内容必须符合@commitlint/config-conventional
规范,你完全可以并且极力推荐使用npm run c
来提交代码,此时只需要根据命令行的提示,逐步填写提交信息。
提交代码时,默认为我们处理如下事情:
-
通过pre-commit钩子,使用standardjs的规范检查待提交的代码,并自动修正格式错误。如果存在无法修正的错误,提交失败,显示报错信息,需要手动修改完后重新提交
-
提交代码,并通过
cz-conventional-changelogg
记录提交信息,用于在发布版本时自动生成CHANGELOG.md
开发时推荐使用
npm run dev
编译开发包本地调试,会自动检测文件变动,生成 dev 版本的文件后,自动推送到手机的SD卡。
gitlab 在每次提交后,会执行
npm run test
跑一遍单元测试
npm run p
发布时自动化处理了很多事情:
- 生成并修改版本号
- 根据版本和提交信息生成
CHANGELOG.md
- 打上版本 tag ,并把1&&2中的改动提交
gitlab在每次检测到带 tag 的提交后,会执行
npm run publish
生成发布包,上传发布包到服务器,并自动生成 gitlab releases,最终发布版本
根据业务情况,选择是发布 major minor 还是 patch,请参考 https://github.com/conventional-changelog/standard-version#release-as-a-target-type-imperatively-like-npm-version
-
patch 是问题修复
npm run p-patch
-
minor 是特性版本
npm run p-minor
-
major 是主版本升级
npm run p-major
【重要】为了防止误发布,stanard-version的默认配置为dry-run
模式,所以所有的发布操作都只会在控制台中输出发布信息,确认版本号等信息无误后,使用npm run p -- --dry-run=false
来真正执行发布操作
- 有一个、且仅有一个主分支,所有提供给客户端使用的正式版本,都在这个主分支上发布。
- 特性分支合并到主分支时可能会有冲突,因为在特性分支会有自己的版本号和changlog,合并的时候版本号使用mater即可,changlog使用两者合并的
如图所示 Master只发布正式版本,譬如 v1.1.0
如果线上包有bug,从 Master 拉出分支修复bug
分支命名规范为 bugfix/xxx
修复完后:
发布 fix 的 prepatch 版本。测试通过后,再合并到 Master,发布正式版本的 patch 版本。
// 在bugfix分支上发布 fix 版本。
npm run p-fix
// 合并到master分支后
npm run p-patch
流程如下图所示:
对于一个独立的新功能开发,从 Master 拉出分支开发新功能
分支命名规范为 feature/xxx
开发完成后:
发布 dev 的 preminor 版本。测试通过后,再合并到 Master,发布正式版本的 minor 版本。
// 在feature分支上发布 dev preminor 版本
npm run p-dev
// 合并到master分支后
npm run p-minor
流程如下图所示:
对于bugfix和feature分支而言,合并到 Master后,便可废弃了。对于feature引入的bug,循环走bugfix的流程修复。最终线上包只对应 Master分支,其它分支都是临时分支
架构设计请参考src 目录下的相应的 文档,链接如下:
builtin: 请参考./src/builtin/README.md
native: 请参考./src/native/README.md
工程依托 gitlab 提供 的 CICD 服务,会检测提交操作做相应的自动化处理。
如下图所示,为当前项目部署的 CICD 服务
https://gitlab.vmic.xyz/minigame/minigame-jsframework/pipelines
gitlab CICD 的配置文件请参考根目录
.gitlab-ci.yml
文件,使用方法请参考 gitlab 官方文档
目前实现的功能有:
-
每次提交会跑整套的单元测试
-
每次发版本时,会跑单元测试,单元测试通过后,会打包js文件,加系统签名,然后调用服务端提供的上传接口,上传到内容库(为热更新提供 js 包),最后使用 gitlib releases 服务,创建版本记录。如下图所示
https://gitlab.vmic.xyz/minigame/minigame-jsframework/releases
所有版本有记录可查,所有发布的包可直接提供给客户端同学使用,不需每次由前端同学打包
本项目采用jest框架实现单元测试
工程引入 jest 框架在每次提交后,会由 gitlab 的 CI 操作自动跑一遍单元测试。
- 配置jest 依赖jest和babel-jest,eslint需要设置个全局变量jest,本项目使用standard的,配置如下:
"standard": {
"parser": "babel-eslint",
"ignore": [],
"env": [
"jest"
]
},
- 开发时,在package的命令里面,可以在jest命令后加个
--watch
命令,保存会自动运行测试用例,--coverage
可以生成测试覆盖率报告。 - 目录结构是在
src/native/api
下的__test__
目录下的。 - 由于全局有一些变量是引擎端注入的,所以需要模拟这些变量,是在
src/jest.setup.js
实现的,在jest.config.js的setupFiles变量里面配置加载的。
请参考工作流中,关于发布版本的操作说明。
对于发布版本的操作,在 .gitlab-ci.yml
中脚本中会指定当遇到 tag 后执行的脚本。实现逻辑在 tasks/publish.js
中
-
它首先获取当前版本的版本号,然后从环境变量中取出 gitlab api 需要的环境变量,包括上传 zip 包到服务端的token 和 创建release的 token。这些变量在 gitlab 工程中配置,如下图所示:
配置链接:https://gitlab.vmic.xyz/minigame/minigame-jsframework/settings/ci_cd
- CI_PRIVATE_TOKEN 为调用 gitlab api 需要的 token,用于创建 gitlab releases
- CI_UPLOAD_TOKEN_ONLINE 为调用线上环境服务器上传文件的接口需要的 token,用于上传 zip 提供给热更新使用
- CI_UPLOAD_TOKEN_TEST 为调用测试环境服务器上传文件的接口需要的 token, 用于上传 dev 的 zip 包,保存在 gitlab releases 中,供开发调试时集成使用
CI_PRIVATE_TOKEN
不需要变动。CI_UPLOAD_TOKEN_ONLINE
和CI_UPLOAD_TOKEN_TEST
会失效,如果 publish 的任务失败提示是 token 过期时,请及时更新 token,需要登陆运营管理后台,然后取到认证的 token (在 cookie 中,如下图)由于这个token是会验证电脑ip的,所以获取token的电脑才能正常执行CICD,也就是说本地部署CICD服务然后再使用这台机器去获取token运营管理后台地址 http://game-test.vmic.xyz/#/index
-
然后读取
CHANGELOG.md
中自上个版本依赖的修改日志记录。上传编译好的jsframework.zip
和jsframework-dev.zip
的 zip 包,上传成功后,获取到 zip 包的 url 下载地址。 -
最后连同刚才读取的修改日志记录,一起调用 gitlab 的 api 创建一个 发布版本,效果如下图所示:
其中
jsframework-dev.zip
为开发版本,js 文件未压缩,日志全开,主要提供给 客户端开发本地集成联调使用
-
无需上传tag,可支持本地运行上传
-
修改本地tasks/config.js 中
CI_UPLOAD_TOKEN_TEST
以及CI_UPLOAD_TOKEN_ONLINE
为本地方舟测试服务器token -
运行
npm run publish
,即可完成打包上传