前端代码风格统一规范(项目依赖版)

目标及介绍

利用项目集成插件的方式来实现

使用项目插件的方式集成到项目中
确保多人协作或者同一团队产出的代码规范统一,看上去像出自一人(很理想化,哈哈)

目前的主流方式:eslint+commitlint+prettier+editorConfig

eslint

js/ts规范检查工具

commitlint

规范 commit msg,配合 husky 一起使用,配合 lint-staged 则更加完美
husky:githooks 工具,在 Git 提交前搞一些事情
lint-staged:只检查 staged 文件(也就是被 git add 的文件),提高执行效率

prettier

代码格式化工具

editorConfig

帮助维护跨多个编辑器和 IDE 的同一个项目的多个开发人员的一致编码风格
需要安装 EditorConfig for VS Code 插件以确保项目中的 .editorConfig 配置能正常读取

向头部大厂的前端开发攻城狮看齐

站在巨人的肩膀上,做到快乐编程,前面提到的所有的依赖和配置都不用安装和编写了

阿里巴巴前端规约

github:https://github.com/alibaba/f2e-spec
一个插件包含(eslintstylelintcommitlintmarkdownlint

只需要两步简单操作即可完成项目接入

step one

  • 安装f2elint
1
yarn add f2elint -D

step two

  • 在命令行执行下面的命令

这一次只需要在第一次初始化时执行即可,后续不必重复执行

1
yarn f2elint init
  • 根据命令行提示进项选择(react js 编写为例)

image.png

  • 后续所有的提示都输入y然后按回车

image.png

  • 遇到配置冲突时,输入y然后按回车,覆盖原来的配置,采用新的配置

image.png

  • 项目进入安装依赖阶段时,等待其安装执行完成
  • 您将发现你的项目出现了上面提到的一堆配置文件

image.png

  • 同时package.json文件的script标签内多处两条可执行的命令

image.png

  • 同时在package.json文件的script同级别已经增加了huskygithooks

image.png

  • 这个时候,你就可以快乐的玩耍了
  • 删除之前项目中可能存在的冗余依赖和配置(没有的请忽略)下面的统统删除
1
yarn remove @commitlint/cli @commitlint/config-conventional eslint yorkie husky lint-staged prettier stylelint

image.png

image.png

  • 执行f2elint-scan命令(扫描当前项目代码,会将当前项目的问题暴露出来)
1
yarn f2elint-scan

image.png

  • 执行f2elint-fix命令(扫描当前项目代码,并自动修复扫描到问题)
1
yarn f2elint-fix

image.png

可以在 vscode 或者使用 git diff 命令来查看他修复的文件和代码

这里单独提出来f2elint 的 commitlint 规范说一下,避免出现累死提交不了代码的情况

下面的配置信息就是f2elint 默认的 commit msg 配置文件

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
module.exports = {
parserPreset: "conventional-changelog-conventionalcommits",
rules: {
"body-leading-blank": [1, "always"],
"body-max-line-length": [2, "always", 100],
"footer-leading-blank": [1, "always"],
"footer-max-line-length": [2, "always", 100],
"header-max-length": [2, "always", 100],
"scope-case": [2, "always", "lower-case"],
"subject-case": [0],
"subject-empty": [2, "never"],
"subject-full-stop": [2, "never", "."],
"type-case": [2, "always", "lower-case"],
"type-empty": [2, "never"],
"type-enum": [
2,
"always",
[
"feat", // (新功能)
"fix", // (错误修复)
"docs", // (仅文档更改)
"style", // (不影响代码含义的更改 (空格,格式,缺少分号等))
"test", // (添加缺失的测试或更正现有的测试)
"refactor", // (代码更改既不能修复错误,也不能添加功能)
"chore", // (其他不会修改 src 或测试文件的更改)
"revert", //(还原先前的提交)
],
],
},
};

上面 GIT COMMIT 提交配置的解释

格式:<type>(<scope>): <subject>
举例:feat(core): add unit test

  • COMMIT 内容:列举本次改动的动机、内容与之前的对比,一行最多 100 个字符就要换行
  • COMMIT 要求:增加的 feat 内容,尽量做到注释清晰,相应的单测覆盖要尽可能覆盖,所有的破坏性改动都应该有所说明

允许的类型 <type>有:

  • feat, (新功能)
  • fix, (错误修复)
  • docs, (仅文档更改)
  • style, (不影响代码含义的更改 (空格,格式,缺少分号等))
  • test, (添加缺失的测试或更正现有的测试)
  • refactor, (代码更改既不能修复错误,也不能添加功能)
  • chore, (其他不会修改 src 或测试文件的更改)
  • revert, (还原先前的提交)

允许的类型 <scope>有:

  • 范围可以是指定提交更改位置的任何内容

执行落地

  • f2elint 中的默认规则,均可通过之前介绍的配置文件进行修改
  • 使用 f2elint 时,其适用范围将不仅仅限于 react/vue node.js 项目
  • 按照上面的步骤来,将很快将规范接入到现有项目中,实现前端项目的编码规范的统一,非常简单。同时由于背靠头部互联网科技企业的前端团队,保证了技术的前沿性。希望前端小伙伴们能进行实际的项目实践并及时进行交流

如何修改f2elint的默认配置(找到对应配置文件即可)

以 commitlint 举例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// commitlint.config.js
// 下面配置将覆盖f2elint commitlint 原有的type配置
module.exports = {
extends: ["ali"],
rules: {
"type-enum": [
2,
"always",
[
"build",
"ci",
"chore",
"docs",
"feat",
"fix",
"perf",
"refactor",
"revert",
"style",
"test",
],
],
},
};

editorconfig 配置

官方文档:http://editorconfig.org

  • 在项目根目录找到文件.editorConfig文件

eslint 配置

官方文档:https://cn.eslint.org/

  • 在项目根目录找到文件.eslintrc.js

规则说明

“off” 或 0 - 关闭规则
“warn” 或 1 - 开启规则,使用警告级别的错误:warn (不会导致程序退出,只给出提示)
“error” 或 2 - 开启规则,使用错误级别的错误:error (会导致停止运行)

prettier 配置

官方文档:https://prettier.io/

  • 在项目根目录找到文件.prettierrc.js文件

husky 配置

官方文档:https://typicode.github.io/husky

  • 在项目根目录找到文件package.json文件

stylelint 配置

官方文档:https://stylelint.io

  • 在项目根目录找到文件.stylelintrc.js文件

commitlint 配置

官方文档:https://commitlint.js.org

  • 在项目根目录找到文件commitlint.config.js文件

实践中踩的坑

  • 发现 提交代码时,husky commit msg 没有正常工作
  • 解决办法

删除本地仓库,从新从远程 clone
手动删除项目package.jsonyorkie 类似的依赖
执行 yarn install
执行 rm -rf .git/hooks ,删除.git 下的 hooks 文件夹
执行 node ./node_modules/husky/lib/installer/bin.js install 重新构建 hooks
👌 解决问题

额外拓展说明

根据规范的 commit msg 生成更新日志和自动迭代版本请参考这篇文章 镜像构建请查看《依据 commit msg 发布时自动生成更新日志》

项目中的依赖项版本控制建议(波浪号更保险)

指定版本:比如 1.2.2,遵循“大版本.次要版本.小版本”的格式规定,安装时只安装指定版本。
波浪号(tilde)+指定版本:比如~1.2.2,表示安装 1.2.x 的最新版本(不低于 1.2.2),但是不安装 1.3.x,也就是说安装时不改变大版本号和次要版本号。
插入号(caret)+指定版本:比如 ˆ1.2.2,表示安装 1.x.x 的最新版本(不低于 1.2.2),但是不安装 2.x.x,也就是说安装时不改变大版本号。需要注意的是,如果大版本号为 0,则插入号的行为与波浪号相同,这是因为此时处于开发阶段,即使是次要版本号变动,也可能带来程序的不兼容。
latest:安装最新版本。

前端开发 IDE 推荐

vscode,别用其他花里胡哨的玩意了就它就行了

vscode 插件推荐(请每位成员确保已进行安装)

ESLint

image.png

Prettier

image.png

stylelint

image.png

EditorConfigs

image.png

建议设置 vscode 保存自动格式化

菜单->首选项->设置->搜索框输入 save->Format On Save 打钩
在你保存时,就能帮组你格式化代码

image.png

关于 js 代码编写规范主流文档(爱彼迎的)

建议阅读学习,可提高代码质量。书写出更加健壮的 js 代码
github:https://github.com/airbnb/javascript