Minigame-jsframework NPM

minigame-jsframework

预研jsframework重构
src中的源码来自：https://gitlab.vmic.xyz/minigame/jsframework/tree/feature_minigame_v1.6.0_base_v1.5.0 版本号：54d0f88e96c5b644b809d81fe5c57fc4eb726089

简介

minigame-jsframework 是vivo小游戏的前端引擎实现。是对原来的jsframework的重构。引入如下新功能：

standard
JavaScript 代码规范，自带 linter & 代码自动修正，节省大量时间
无须配置 史上最便捷的统一代码风格的方式，轻松拥有
自动代码格式化 只需运行 standard --fix 从此和脏乱差的代码说再见
提前发现风格及程序问题 减少代码审查过程中反反复复的修改过程，节约时间

commitizen
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 目的的简短描述

standard-version
版本管理工具，根据提交信息生成日志，检测生成并修改版本号，提交相应的修改并自动添加tag
husky
拦截git操作的工具，本项目中使用它在提交代码之前，进行代码的 stanard 检查，并自动修复，避免不符合格式的代码被提交。
lint-staged
因为只想对已经产生改动的文件，进行检查，避免检查并没有改动的文件，lint-staged 工具就是为了只检查缓存区的文件
webpack
统一了打包工具，所有项目使用webpack打包
Babel
升级了Babel为最新的版本，新引入根据引擎版本号来适配ES6，而不是全部做兼容适配
Jest
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来真正执行发布操作

分支管理

主分支 Master

有一个、且仅有一个主分支，所有提供给客户端使用的正式版本，都在这个主分支上发布。
特性分支合并到主分支时可能会有冲突，因为在特性分支会有自己的版本号和changlog，合并的时候版本号使用mater即可，changlog使用两者合并的

npm.io

如图所示 Master只发布正式版本，譬如 v1.1.0

问题修复分支 Bugfix

如果线上包有bug，从 Master 拉出分支修复bug

分支命名规范为 bugfix/xxx

修复完后：

发布 fix 的 prepatch 版本。测试通过后，再合并到 Master，发布正式版本的 patch 版本。

// 在bugfix分支上发布 fix 版本。
npm run p-fix

// 合并到master分支后
npm run p-patch

流程如下图所示：

npm.io

新功能分支 Feature

对于一个独立的新功能开发，从 Master 拉出分支开发新功能

分支命名规范为 feature/xxx

开发完成后：

发布 dev 的 preminor 版本。测试通过后，再合并到 Master，发布正式版本的 minor 版本。

// 在feature分支上发布 dev preminor 版本
npm run p-dev

// 合并到master分支后
npm run p-minor

流程如下图所示：

npm.io

对于bugfix和feature分支而言，合并到 Master后，便可废弃了。对于feature引入的bug,循环走bugfix的流程修复。最终线上包只对应 Master分支，其它分支都是临时分支

架构设计

架构设计请参考src 目录下的相应的文档，链接如下：

builtin: 请参考./src/builtin/README.md

native: 请参考./src/native/README.md

工程化

gitlab CICD

工程依托 gitlab 提供的 CICD 服务，会检测提交操作做相应的自动化处理。

npm.io

如下图所示，为当前项目部署的 CICD 服务

https://gitlab.vmic.xyz/minigame/minigame-jsframework/pipelines

npm.io

gitlab CICD 的配置文件请参考根目录.gitlab-ci.yml文件，使用方法请参考 gitlab 官方文档

目前实现的功能有：

每次提交会跑整套的单元测试
每次发版本时，会跑单元测试，单元测试通过后，会打包js文件，加系统签名，然后调用服务端提供的上传接口，上传到内容库（为热更新提供 js 包），最后使用 gitlib releases 服务，创建版本记录。如下图所示

https://gitlab.vmic.xyz/minigame/minigame-jsframework/releases

npm.io

所有版本有记录可查，所有发布的包可直接提供给客户端同学使用，不需每次由前端同学打包

单元测试

本项目采用jest框架实现单元测试

工程引入 jest 框架在每次提交后，会由 gitlab 的 CI 操作自动跑一遍单元测试。 1. 配置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 文件未压缩，日志全开，主要提供给客户端开发本地集成联调使用