前端项目编码规范化工具

October 10, 2019团队规范项目配置

前言

风格一致的代码保证了项目的可读性和可维护性，它是开展 Code Review 的前提。选择某一种风格而排除其他风格，并不说明它是最好的编码风格，而是为了实现一致。

编码

Editorconfig

IDE 与编辑器普遍支持，VS Code 与 WebStorm 自动支持，Sublime Test、Vim、ATOM、Note pad++ 插件支持。更多配置查看规则文档，以及使用了 EditorConfig 的开源项目列表。

# .editorconfig
root = true

# 匹配符（[*]、[*.{js,jsx}]、[{package.json,.travis.yml}]）
[*]
charset = utf-8
end_of_line = lf      # 换行符
indent_style = space  # 缩进符号
indent_size = 2       # 缩进大小
trim_trailing_whitespace = true  # 清楚行尾空格
insert_final_newline = true      # 文件尾部增加空行

[*.md]
indent_style = tab

[*.bat]
end_of_line = crlf

Lint

基本配置

关于代码风格的工具特别多，比如 GitHub 官方出品的 Lint 工具列表。

配置文件查找规则：可以了解下 cosmiconfig 如何获取配置文件。

.stylelintrc .eslintrc .tslintrc 中的 rc 是什么意思？看这里。以及 . 表示隐藏文件。

以 Stylelint 举例：

以 stylelint 属性配置在 package.json 中
.stylelintrc JSON 文件
.stylelintrc.yml 或 .stylelintrc.yaml YAML 文件
.stylelintrc.js js 文件

extends：

用于添加 lint 的扩展配置，扩展配置的优点是快速接入，以及中心化维护。依赖包名通常为 {stylelint,eslint,tslint}-config-**。

{
  "extends": "stylelint-config-standard"
}

// 多个扩展时使用数组
{
  "extends": ["stylelint-config-standard"]
}

// 也可以指定配置文件路径（需保留文件后缀名）
{
  "extends": ["../my-config.js"]
}

// "eslint-config-" 前戳可以省略
{
  "extends": "airbnb"
}

plugins：

用于添加插件支持更多的规则。要添加插件首先用 npm 安装，随后在 plugins 中增加插件名，再配置插件规则。在规则名中 / 之前是插件名称，/ 之后是插件的规则，插件的规则描述在项目文档中能找到。

{
  "plugins": ["compat"],
  "rules": {
    "compat/compat": "error"
  }
}

rules：

用于更加细粒度的配置规则，可以修改 extends 中的规则。规则一般为“关闭”、“警告”、“错误”三种级别。

{
  "plugins": ["some-plugin"],
  "rules": {
    "some-rules-0": 0,         // "off"   或 0 - 关闭规则
    "some-rules-1": 1,         // "warn"  或 1 - 将规则作为警告打开（不影响退出代码）
    "some-rules-2": 2,         // "error" 或 2 - 将规则作为错误打开（触发时退出代码为1）
    "some-rules-3": [1, options],
    "some-plugin/rule-0": "warning"
  }
}

rule 中配置的继承规则：

合并

基本配置："eqeqeq": ["error", "allow-null"]
覆盖配置："eqeqeq": "warn"
产生的实际配置："eqeqeq": ["warn", "allow-null"]

替换

基本配置："eqeqeq": ["error", "allow-null"]
覆盖配置："eqeqeq": ["warn"]
产生的实际配置："eqeqeq": ["warn"]

env：

指定环境，以便正确的访问全局属性或对象。

{
  "env": {
    "browser": true,
    "node": true,
    "es6": true,
    "mocha": true,
    "jest": true,
    "jasmine": true
  }
}

内联注释禁用规则：

临时禁用文件中的规则警告

/* eslint-disable */

alert("foo")

/* eslint-enable */

禁用或启用特定规则的警告

/* eslint-disable no-alert, no-console */

alert("foo")
console.log("bar")

/* eslint-enable no-alert, no-console */

禁用特定行上的所有规则

alert("foo") // eslint-disable-line

Stylelint：

查看规则文档。

规则指南：

stylelint-config-recommended
stylelint-config-standard（包含了 stylelint-config-recommended）

配置：

{
  "extends": "stylelint-config-standard",
  "rules": {
    "declaration-empty-line-before": null,
    "function-comma-newline-after": null,
    "function-name-case": null,
    "function-parentheses-newline-inside": null,
    "function-max-empty-lines": null,
    "function-whitespace-after": null,
    "indentation": null,
    "number-leading-zero": null,
    "number-no-trailing-zeros": null,
    "rule-empty-line-before": null,
    "selector-combinator-space-after": null,
    "selector-list-comma-newline-after": null,
    "selector-pseudo-element-colon-notation": null,
    "unit-no-unknown": null,
    "value-list-max-empty-lines": null,
    "font-family-no-missing-generic-family-keyword": null,
    "no-descending-specificity": null
  }
}

Eslint(中文):

风格指南：

下面是用的比较多的三种风格指南，后面链接可以找到对所有规则的描述。也包含了各个风格依赖的插件地址（文档不必都知道，遇到报错可以方便找到对应规则去查）。

eslint:recommended
eslint-config-airbnb
eslint-config-standard
eslint-config-google
eslint-plugin-prettier
- 此插件将 Prettier 工具能修复的相关语法全部关闭，然后在提交时美化格式。
eslint-plugin-compat
- 此插件仅适用于浏览器环境，它很好的检查代码兼容性并给出提示。
- 只有 "compat/compat": "error" 一条规则。

手动生成 .eslintrc 文件：

运行初始化命令，它会你问一些问题，多选类用上下键移动光标敲回车回答，判断类选择 Y 或 N 回答。比如下面这个问答流程。

$ eslint --init
? How would you like to configure ESLint? Answer questions about your style
? Which version of ECMAScript do you use? ES2018
? Are you using ES6 modules? Yes
? Where will your code run? Browser, Node
? Do you use CommonJS? Yes
? Do you use JSX? Yes
? Do you use React? Yes
? What style of indentation do you use? Spaces
? What quotes do you use for strings? Single
? What line endings do you use? Unix
? Do you require semicolons? Yes
? What format do you want your config file to be in? JSON

基本配置：

两个空格代表一个缩进。
使用 unix 换行符。
字符串时使用单引号。
强制使用分号。

module.exports = {
  rules: {
    indent: ["error", 2],
    "linebreak-style": ["error", "unix"],
    quotes: ["error", "single"],
    semi: ["error", "always"],
  },
}

Tslint:

TypeScript 的风格检查工具。

{
  "extends": "tslint:recommended",
  "rules": {
    "max-line-length": {
      "options": [120]
    }
  }
}

内联注释禁用规则

/* tslint:disable */ - 禁用文件其余部分的所有规则
/* tslint:enable */ - 为文件的其余部分启用所有规则
/* tslint:disable:rule1 rule2 rule3... */ 禁用文件其余部分列出的规则
// tslint:disable-line - 禁用当前行的所有规则

辅助工具：

Subliem text:

SublimeLinter-stylelint
SublimeLinter-eslint
SublimeLinter-tslint

Prettier

介绍

Prettier 用于美化代码，支持 ES、JSX、TS、JSON、HTML、CSS、LESS、Markdown 等大部分语法。

// defore
const user = { name: "John Doe", age: 30 }

// after
const user = { name: "John Doe", age: 30 }

// defore
const user = {
  name: "John Doe",
  age: 30,
}

// after
const user = {
  name: "John Doe",
  age: 30,
}

注意

使用时需避免与 Eslint 语法规则产生冲突，解决方法比如使用 eslint-plugin-prettier 共享配置覆盖冲突规则。

默认情况下 Prettier 还会读取 .editorconfig 中的配置，

内联注释禁用规则

JavaScript：

// prettier-ignore
matrix(
  1, 0, 0,
  0, 1, 0,
  0, 0, 1
)

JSX：

<div>
  {/* prettier-ignore */}
  <span     ugly  format=''   />
</div>

HTML:

<!-- prettier-ignore -->
<div         class="x"       >hello world</div            >

Markdown

<!-- prettier-ignore -->
Do   not    format   this

插件支持

Visual Studio Code: prettier-vscode
Sublime Text: JsPrettier
WebStorm: File Watcher 配置

集成风格校验

Lint-stage：

Lint-stage 工具只检查 Git 仓库暂存区文件，可以更加高效校验代码，也适合用在老项目中（它不会检查老旧的不规范的代码）。它的配置写在 package.json 的 lint-staged 属性中。

"lint-staged": {
    "src/**/*.js": "eslint"
  }

Husky：

Husky 让我们更加方便的使用本地 Git hook，在 git commit 之前触发 pre-commit 来执行校验命令。它的配置写在 package.json 的 husky 属性中。

"husky": {
    "hooks": {
      "pre-commit": "npm run lint"
    }
  },

其他配置文件

ignore 文件
- .gitignore
- .stylelintignore
- .eslintignore
lock 文件
- package-lock.json
- yarn.lock
.nvmrc
.npmignore
.npmrc

命名

常见的几种命名方式

驼峰式命名法：分为【大驼峰】（即帕斯卡命名法 UpperCamelCase）与【小驼峰】（lowerCamelCase），及首字母大写与首字母小写的区别。
下划线命名法：分为【全大写】或【全小写】两种。
短横线命名法：全小写，单词之间用短横线分割。
匈牙利命名法：不推荐使用（除特殊情况外），即数据类型为名称前戳。

特殊情况

驼峰命名时遇到全大写单词（如：get MD5、get ID）如何命名？
- 约定为：通用的全大写缩写在这个地方应作为普通单词首字母大写（如：getMd5、getId）。
使用驼峰命名时遇到数字开头（如：get 2k、is 3G）如何命名?
- 约定为：遇到数字开头的名称则不大写，如：get2k、is3G。
会遇到单纯的数子名称开头（如：play 1080、play 720）如何命名?
- 应避免：改为 playFHD 与 playHD。

命名约定：

项目命名：按照 fe-[类型]-[短横线命名语义化名称]。
文件夹与文件命名：组件用大驼峰命名，其他文件一律短横线命名，图片静态文件可使用下划线或短横线小写命名。
CSS Class 命名：传统 CSS Class 一律短横线命名，若是 css in js 则使用小驼峰命名。
JS 命名：
- 常量使用下划线大写命名，力求语义表达完整清楚，不要嫌名字长。
- 类名与构造函数使用大驼峰命名。
- 方法、参数、成员变量、局部变量都统一小驼峰命名。
- 私有属性在名字前面加下划线开头。
属性变量名称使用名词，布尔值以 is, has 开头。
方法名称使用动词，如：get、set、add、del 开头。
前端路由一律短横线命名。URL 中域名不区分大小写，路径交给服务器解析，避免意外情况一律小写。

提交

统一团队Git commit日志标准，便于后续代码review，版本发布以及日志自动化生成等等。

参照：

Angular
vue

指名当前 commit 的类型：

type代表某次提交的类型，比如是修复一个bug还是增加一个新的feature。所有的type类型如下：
feat：新增feature fix: 修复bug
docs: 仅仅修改了文档，比如README, CHANGELOG, CONTRIBUTE等等
style: 仅仅修改了空格、格式缩进、都好等等，不改变代码逻辑
refactor: 代码重构，没有加新功能或者修复bug
perf: 优化相关，比如提升性能、体验
test: 测试用例，包括单元测试、集成测试等
chore: 改变构建流程、或者增加依赖库、工具等
revert: 回滚到上一个版本

作者：腾讯云加社区链接：https://juejin.im/post/58db6ec7570c350058f22fb5 来源：掘金

1576394764102 0dec023b 855d 4cc8 9895 7571190b76ae

1576394766816 3211918b fe63 4033 a6b9 c9c52970600e

组件

不直接修改从 props 与 story 传递过来的数据。
组件中 DOM 避免使用 id 属性，或者 id 名称可由外部配置。
表单类组件：
- 值由 value 接收，数据改变由 onChange 进行监听，支持 Antd Form 规范。
- 支持只读、禁用、正常状态。

文档

中文技术文档的写作规范

参考链接

知命不惧，日日自新。

前端项目编码规范化工具

前言

编码

目录

Editorconfig

Lint

基本配置

extends：

plugins：

rules：

env：

内联注释禁用规则：

Stylelint：

Eslint(中文):

Tslint:

辅助工具：

Prettier

介绍

注意

内联注释禁用规则

插件支持

集成风格校验

Lint-stage：

Husky：

其他配置文件

命名

常见的几种命名方式

特殊情况

命名约定：

提交

组件

文档

参考链接