AI前端工程工具链

# # AI前端工程工具链

为了提高整体开发效率，需要定制一些vue/electron/官网等脚手架工具。首先要将一些代码规范考虑在内，需要保持git仓库的代码就像是一个人写出来的。根据团队习惯，考虑后使用组合工具：

规范提交代码（必需）：eslint + stylelint + prettier + husky + lint-staged。
规范commit日志（必需）：commitlint + commitizen + cz-conventional-changelog + conventional-changelog-cli
规范提交流程（github项目）：release-it + gh-pages。
辅助代码分析（可选）：jsinspect + jscpd

# # 1. 规范提交代码

针对写出符合团队代码规范的js、css代码

eslint: 对js做规则约束。强制校验
stylelint: 对css做规则约束
prettier: 代码格式化。强制格式化
husky + lint-staged (opens new window) (opens new window)：本地git钩子工具

# # 1.1 eslint (opens new window) (opens new window)

# # 1.1.1 安装

    npm install --save-dev eslint eslint-plugin-vue babel-eslint

1
2

# # 1.1.2 `.eslintrc.js`配置

    module.exports = {
        root: true,
        // 指定代码的运行环境。不同的运行环境，全局变量不一样
        env: {
          browser: true,
          node: true
        },
        parserOptions: {
        // ESLint 默认使用Espree作为其解析器,安装了 babel-eslint 用来代替默认的解析器
          parser: 'babel-eslint'
        },
        // 使得不需要自行定义大量的规则
        extends: [
          // consider switching to `plugin:vue/strongly-recommended` or `plugin:vue/recommended` for stricter rules.
          'plugin:vue/essential'
        ],
        // 插件
        plugins: [
          'vue'
        ],
        // add your custom rules here
        rules: {
          // allow async-await
          'generator-star-spacing': 'off',
          // allow debugger during development
          'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
          'indent': [2, 4, { 'SwitchCase': 1 }],
          ...
        }
      }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# # 1.1.3 提交前强制校验

将约束命令放置在提交代码前检查，这就要使用husky (opens new window) (opens new window) + lint-staged (opens new window) (opens new window)工具，工具能在提交代码precommit时调用钩子命令。

    npm install husky lint-staged -D

1
2

    "scripts": {
        "lint": "eslint --ext .js,.vue --ignore-path .gitignore .",
    },
    "gitHooks": {
      "pre-commit": "lint-staged"
    },
    "lint-staged": {
      "*.{js,vue,ts}": [
        "npm run lint"
      ]
    },

1
2
3
4
5
6
7
8
9
10
11
12

TIP

如果是vue-cli3项目创建的项目，以上配置都自动生成了，直接执行vue-cli-service lint即可。

1
2
3

# # 1.2 prettier (opens new window) (opens new window)

# # 1.2.1 安装

    npm install --save-dev prettier

1
2

# # 1.2.2. `.prettierrc.js`配置

以下感谢团队伙伴@Birttany的配置说明

    module.exports = {
        printWidth: 100, // 设置prettier单行输出（不折行）的（最大）长度
    
        tabWidth: 4, // 设置工具每一个水平缩进的空格数
    
        useTabs: false, // 使用tab（制表位）缩进而非空格
    
        semi: false, // 在语句末尾添加分号
    
        singleQuote: true, // 使用单引号而非双引号
    
        trailingComma: 'none', // 在任何可能的多行中输入尾逗号
    
        bracketSpacing: true, // 在对象字面量声明所使用的的花括号后（{）和前（}）输出空格
    
        arrowParens: 'avoid', // 为单行箭头函数的参数添加圆括号，参数个数为1时可以省略圆括号
    
        parser: 'babylon', // 指定使用哪一种解析器
    
        jsxBracketSameLine: true, // 在多行JSX元素最后一行的末尾添加 > 而使 > 单独一行（不适用于自闭和元素）
    
        rangeStart: 0, // 只格式化某个文件的一部分
    
        rangeEnd: Infinity, // 只格式化某个文件的一部分
    
        filepath: 'none', // 指定文件的输入路径，这将被用于解析器参照
    
        requirePragma: false, // (v1.7.0+) Prettier可以严格按照按照文件顶部的一些特殊的注释格式化代码，这些注释称为“require pragma”(必须杂注)
    
        insertPragma: false, //  (v1.8.0+) Prettier可以在文件的顶部插入一个 @format的特殊注释，以表明改文件已经被Prettier格式化过了。
    
        proseWrap: 'preserve' // (v1.8.2+)
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# # 1.2.3 提交前强制格式化

在提交git时需要对整个项目执行format格式化，使得代码强制统一。格式化之后再用eslint检查语法错误，无误后把格式化后的代码用git add .添加进入。如果有错误直接中断提交。

    "scripts": {
        "lint": "eslint --ext .js,.vue --ignore-path .gitignore .",
    },
    "gitHooks": {
      "pre-commit": "lint-staged"
    },
    "lint-staged": {
      "*.{js,vue,ts}": [
        "prettier --write",
        "npm run lint"
      ]
    },

1
2
3
4
5
6
7
8
9
10
11
12
13

# # 1.3 stylelint

参见另一篇博客 (opens new window) (opens new window)

# # 2. 规范commit日志(必需)

在多人协作的项目中，如果Git的提交说明精准，在后期协作以及Bug处理时会变得有据可查，项目的开发可以根据规范的提交说明快速生成开发日志，从而方便开发者或用户追踪项目的开发信息和功能特性。

规范的Git提交说明:

提供更多的历史信息，方便快速浏览
可以过滤某些commit，便于筛选代码review
可以追踪commit生成更新日志
可以关联issues

Git提交说明结构:

Git提交说明可分为三个部分：Header、Body和Footer。

    <Header>
    
    <Body>
    
    <Footer>

1
2
3
4
5
6

Header部分包括三个字段type（必需）、scope（可选）和subject（必需）。

    <type>(<scope>): <subject>

1
2

type用于说明 commit 的提交性质。(Angular规范)

feat 新增一个功能
fix 修复一个Bug
docs 文档变更
style 代码格式（不影响功能，例如空格、分号等格式修正）
refactor 代码重构
perf 改善性能
test 测试
build 变更项目构建或外部依赖（例如scopes: webpack、gulp、npm等）
ci 更改持续集成软件的配置文件和package中的scripts命令，例如scopes: Travis, Circle等
chore 变更构建流程或辅助工具
revert 代码回退

# # 2.1 commitlint (opens new window) (opens new window)

约定commit message提交的格式。

# # 2.1.1 安装

    npm install --save-dev @commitlint/config-conventional @commitlint/cli

1
2

# # 2.1.2 配置

在根目录执行以下命令作为commitlint的配置

    echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

1
2

# # 2.1.2 提交前校验

    "husky": {
      "hooks": {
        "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
      }
    }

1
2
3
4
5
6

# # 2.2 commitizen cz-conventional-changelog

commitlint约定了提交的格式，但每次书写都需要记住那些约定，增加记忆负担。所以使用cz工具让提交commit过程更加可视化。

commitizen/cz-cli是一个可以实现规范的提交说明的工具，提供选择的提交信息类别，快速生成提交说明。

# # 2.2.1 安装

    npm i commitizen cz-conventional-changelog -D

1
2

# # 2.2.2 配置

使用cz-conventional-changelog适配器（介于AngularJS规范），约定提交代码时的选项。

    "config": {
      "commitizen": {
        "path": "./node_modules/cz-conventional-changelog"
      }
    }

1
2
3
4
5
6

# # 2.2.3 命令执行

以后git commit都使用npm run commit（即git-cz）代替

    "scripts": {
        "commit": "git add -A && git-cz"
    },

1
2
3
4

commitlint + commitizen cz-conventional-changelog + conventional-changelog-cli

# # 2.3 conventional-changelog-cli (opens new window) (opens new window)

自动根据commit生成changelog。

良好的changelog可以让用户一眼知道组件库的版本迭代演进，也是长期维护项目的必备内容。

# # 2.3.1 安装

    npm install conventional-changelog-cli -D

1
2

# # 2.3.2 命令执行

    "scripts": {
        "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
    },

1
2
3
4

TIP

每次发布组件包版本后，即可使用npm run changelog命令，自动根据git commit生成日志。

1
2
3

# # 3. 规范提交流程（可选）

针对github + npm项目，可以简化流程。内部非开源项目可跳过该内容。

gh-pages（发布demo到github）
release-it/standard-version (opens new window) (opens new window)（自动提交github代码 + 自动修改lib库版本 + 推送npm服务器）

# # 3.1 安装

    npm i gh-pages release-it -D

1
2

# # 3.2 命令执行

    "scripts": {
        "release": "release-it",
        "release:docs": "npm run build:docs && gh-pages -d docs/.vuepress/dist
    },

1
2
3
4
5

# # 4. 辅助代码分析（可选）

敏捷开发过程中，代码复查是至关重要的一环，团队需要使用工具辅助代码分析。经比较和实践后，使用工具：jsinspect + jscpd

jsinspect: 对js或jsx代码做重复检测。
jscpd: 对代码重复率进行报告总结，辅助代码复查

# # 4.1 jsinspect (opens new window) (opens new window)

# # 4.1.1 安装

    npm install jsinspect --save-dev

1
2

# # 4.1.2 提交前强制校验

    "scripts": {
        "inspect": "jsinspect -t 50 ./src",
    }

1
2
3
4

# # 4.2 jscpd (opens new window) (opens new window)

# # 4.2.1 安装

    npm install jscpd --save-dev

1
2

# # 4.2.2 代码复查辅助命令

    "scripts": {
        "codereview": "jscpd ./src"
    }

1
2
3
4

# # 总结

eslint + husky + lint-staged + prettier作为基础工具。
commitlint约束提交规范,commitizen让工具通过select选项，进行git commit, conventional-changelog-cli自动根据git commit生成changelog文件。
release-it核心是可以把包自动发送到npm上，gh-pages把指定目录发布到github gh-pages分支上。

配置好以上工具，开发组件库时常用三个命令：

平时开发提交commit： npm run commit "commit": "git add -A && git-cz",
发布npm包: npm publish "prepublish": "npm run build && release-it && npm run changelog",
发布docs: npm run docs "release:docs": "npm run build:docs && gh-pages -d docs/.vuepress/dist",

以下示例个实际github项目配置: lq782655835/yi-ui (opens new window) (opens new window)

    "scripts": {
        "commit": "git add -A && git-cz",
        "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
        "release": "release-it",
        "lint": "vue-cli-service lint"
    },
    "husky": {
        "hooks": {
            "pre-commit": "lint-staged",
            "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
        }
    },
    "lint-staged": {
        "packages/**/*.{vue,ts,tsx,js,jsx,json}": [
            "prettier --write",
            "npm run lint"
        ]
    },
    "config": {
        "commitizen": {
            "path": "./node_modules/cz-conventional-changelog"
        }
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

编辑

← AI前端Vue规范 AI JavaScript 风格指南→

AI前端工程工具链

# # AI前端工程工具链

# # 1. 规范提交代码

# # 1.1 eslint (opens new window) (opens new window)

# # 1.1.1 安装

# # 1.1.2 .eslintrc.js配置

# # 1.1.3 提交前强制校验

# # 1.2 prettier (opens new window) (opens new window)

# # 1.2.1 安装

# # 1.2.2. .prettierrc.js配置

# # 1.2.3 提交前强制格式化

# # 1.3 stylelint

# # 2. 规范commit日志(必需)

# # 2.1 commitlint (opens new window) (opens new window)

# # 2.1.1 安装

# # 2.1.2 配置

# # 2.1.2 提交前校验

# # 2.2 commitizen cz-conventional-changelog

# # 2.2.1 安装

# # 2.2.2 配置

# # 2.2.3 命令执行

# # 2.3 conventional-changelog-cli (opens new window) (opens new window)

# # 2.3.1 安装

# # 2.3.2 命令执行

# # 3. 规范提交流程（可选）

# # 3.1 安装

# # 3.2 命令执行

# # 4. 辅助代码分析（可选）

# # 4.1 jsinspect (opens new window) (opens new window)

# # 4.1.1 安装

# # 4.1.2 提交前强制校验

# # 4.2 jscpd (opens new window) (opens new window)

# # 4.2.1 安装

# # 4.2.2 代码复查辅助命令

# # 总结

# # 1.1.2 `.eslintrc.js`配置

# # 1.2.2. `.prettierrc.js`配置