代码规范

一个项目中，应该保持代码规范的一致性。

1. 工具

ESLint：检查 JS 和 TS 的语法和样式，可以修正部分样式。
Stylelint：检查 CSS、Less、Sass 等样式文件的语法和样式，可以修正部分样式。
Prettier：可以检查和修正大部分前端文件的样式，包括 JS、TS、CSS、Less、Sass、HTML、Markdown，但不会检查语法。在代码样式的修正方面，Prettier 比 ESLint 和 Stylelint 要强大得多。

2. 安装

2.1. 安装 ESLint 和相关配置

推荐使用 React 官方团队编写的配置 eslint-config-react-app。

# 安装 ESLint
yarn add -D eslint@^7.5.0
# 安装 TS（可选）
yarn add -D typescript@^4.0.0
# 安装 eslint-config-react-app 配置及其相关依赖
yarn add -D eslint-config-react-app@^6.0.0 @typescript-eslint/eslint-plugin@^4.0.0 @typescript-eslint/parser@^4.0.0 babel-eslint@^10.0.0 eslint-plugin-flowtype@^5.2.0 eslint-plugin-import@^2.22.0 eslint-plugin-jsx-a11y@^6.3.1 eslint-plugin-react@^7.20.3 eslint-plugin-react-hooks@^4.0.8

2.2. 安装 Stylelint 和相关配置

# 安装 Stylelint
yarn add -D stylelint@^13.12.0
# 安装 stylelint-config-standard，用于常规的语法和样式检查
yarn add -D stylelint-config-standard@^20.0.0
# 安装 stylelint-config-css-modules，用于 CSS Modules
yarn add -D stylelint-config-css-modules@^2.2.0
# 安装 stylelint-config-rational-order，用于 CSS 属性的排序
yarn add -D stylelint-config-rational-order@^0.1.2

2.3. 安装 Prettier 和相关配置

# 安装 Prettier
yarn add -D prettier@^2.2.1
# 安装 eslint-config-prettier，用于禁用 ESLint 的样式检查
yarn add -D eslint-config-prettier@^8.1.0
# 安装 stylelint-config-prettier，用于禁用 Stylelint 的样式检查
yarn add -D stylelint-config-prettier@^8.0.2

2.4. 安装 VS Code 插件

在 VS Code 的扩展商店中分别搜索 "ESLint"、"Stylelint" 和 "Prettier"，并按下面图片选中的插件进行安装。

VS Code 安装 ESLint 插件

3. 配置文件

代码规范工具的配置文件包括两个部分，一个是定义规则，另一个是忽略文件（例如忽略 /build 和 /public 文件）。

3.1. ESLint 配置文件

添加 .eslintrc.json 文件：

{
  "extends": ["react-app", "prettier"]
  // 定义全局变量（不推荐使用）示例：
  // "globals": {
  //   "$": "readonly"
  // },
  // 禁用规则（不推荐使用）示例：
  // "rules": {
  //   "jsx-a11y/anchor-is-valid": "off"
  // }
}

添加 .eslintignore 文件：
```
/build
/public
```

3.2. Stylelint 配置文件

添加 .stylelintrc.json 文件：

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-css-modules",
    "stylelint-config-rational-order",
    "stylelint-config-prettier"
  ]
  // 禁用规则（不推荐使用）示例：
  // "rules": {
  //   "no-empty-source": null
  // }
}

添加 .stylelintignore 文件：
```
/build
/public
```

3.3. Prettier 配置文件

添加 .prettierrc 文件：
```
{}
```
通常情况下，此文件包含一个空对象即可，如果你需要自定义样式，可以参考 Prettier 配置项。需要注意的是，最好不要修改 parser 配置，会引起意想不到的问题。
添加 .prettierignore 文件：
```
/build
/public
```

3.4. TS 配置文件（可选）

添加 tsconfig.json 文件：

{
  "include": ["src"],
  "compilerOptions": {
    "target": "ES5",
    "module": "ES6",
    "lib": ["DOM", "ES2020"],
    "moduleResolution": "Node",
    "skipLibCheck": true,
    "jsx": "react",
    "strict": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true
    // 可以通过下面的配置添加项目别名
    // "baseUrl": ".",
    // "paths": {
    //   "@": ["src"]
    // }
  }
}

3.5. Package.json 配置文件

在 pacakge.json 文件中添加 lint 命令：

{
  "scripts": {
    "lint": "tsc -p tsconfig.json --noEmit && eslint . --ext .jsx,.js,.ts,.tsx --fix && stylelint \"**/*.less\" --syntax=less --fix && prettier --write . --loglevel warn"
  }
}

如果你未使用 TS，可以把 tsc 的检查删掉。

3.6. VS Code 配置文件

VS Code 的配置文件有全局和工作区之分：

打开全局配置文件：键盘输入 cmd + shift + p（Windows 下是 ctrl + shift + p），搜索 setting 并打开设置。
增加工作区配置文件：在项目根目录下添加 .vscode/settings.json 文件。

无论是全局配置还是工作区配置，都可以参考下面的配置项：

{
  // 关闭 TS 检查 JS 文件
  "javascript.validate.enable": false,

  // 保存文件时修正代码样式
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    // 开启 ESLint 修复
    "source.fixAll.eslint": true,
    // 开启 Stylelint 修复
    "source.fixAll.stylelint": true
  },
  // 设置默认的格式器为 Prettier
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // 开启 ESLint 验证
  "eslint.format.enable": true,

  // 设置 stylelint 的配置路径
  "stylelint.configFile": ".stylelintrc.json",
  // 设置 stylelint 需要检查的文件类型
  "stylelint.validate": [
    "css",
    "less",
    "sass",
    "scss"
  ],

  // 强制项目下有 Prettier 配置才开启样式修复
  "prettier.requireConfig": true,
  // 禁止 Prettier 使用 .editorconfig 配置，否则在没有 Prettier 的项目中也会格式化
  "prettier.useEditorConfig": false,

  // 在文件末尾插入新行
  "files.insertFinalNewline": true,
  // 删除每行末尾多余的空白
  "files.trimTrailingWhitespace": true,
  // 删除文件末尾多余的空行
  "files.trimFinalNewlines": true,
  // 强制每行结尾符为 "\n"
  "files.eol": "\n"
}

4. 代码忽略

推荐在具体的代码中忽略检测规则，而不是在配置文件中禁用。

4.1. ESLint 代码忽略

// 忽略一行
alert("foo"); // eslint-disable-line

// 忽略下一行
// eslint-disable-next-line
alert("foo");

// 忽略代码块
/* eslint-disable */
alert("foo");
/* eslint-enable */

// 忽略指定的规则
alert("foo"); // eslint-disable-line no-alert, quotes, semi

4.2. Stylelint 代码忽略

/* 忽略一行 */
a {
  color: pink !important; /* stylelint-disable-line */
}

/* 忽略下一行 */
/* stylelint-disable-next-line */
a {
}

/* 忽略代码块 */
/* stylelint-disable */
a {
}
/* stylelint-enable */

/* 忽略指定的规则 */
/* stylelint-disable-next-line no-duplicate-selectors, block-no-empty */
a {
}

4.3. Prettier 代码忽略

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

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

5. 项目示例

https://git.uyunsoft.cn/liws/code-spec-demo

Current Tags

1.0.2 ... latest (3 years ago)
1.0.0-next.71 ... next (3 years ago)

6 Versions

1.0.2 ... 3 years ago
2.0.6 ... 3 years ago
1.0.0 ... 3 years ago
1.0.0-next.71 ... 3 years ago
1.0.0-next.55 ... 3 years ago
1.0.0-next.45 ... 3 years ago