项目搭建系列：项目规范配置(2023年更新补充)

copyer_xyf
449 阅读15分钟

不同程序员不同的代码风格，彰显自己的与众不同。但是呢，如果是团队工作，就需要统一的代码规范。

EditorConfig

EditorConfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs. The EditorConfig project consists of a file format for defining coding styles and a collection of text editor plugins that enable editors to read the file format and adhere to defined styles. EditorConfig files are easily readable and they work nicely with version control systems.

EditorConfig有助于为跨各种编辑器和ide从事同一项目的多个开发人员维护一致的编码风格。EditorConfig项目由用于定义编码样式的文件格式和一组文本编辑器插件组成，这些插件使编辑器能够读取文件格式并遵循定义的样式。EditorConfig文件易于阅读，它们与版本控制系统配合得很好。

有些编辑器默认支持editorConfig，如webstorm；而有些编辑器则需要安装editorConfig插件，如VS Code等。

editorconfig.png 当打开一个文件时，EditorConfig插件会在打开文件的目录和其每一级父目录查找.editorconfig文件，直到有一个配置文件root=true。（查找的顺序，从上到下）

.editorconfig配置

# https://editorconfig.org
# 最顶层的配置文件，发现设为true时，才会停止查找.editorconfig文件
root = true

[*] # 所有文件配置
charset = utf-8  # 设置文件字符集为utf-8

end_of_line = lf  # 设置为"lf"、"cr"或"crlf"来控制换行的表示方式。
insert_final_newline = true # 文件最后新增一行
# 用一个整数定义的列数来设置缩进的宽度，如果indent_style为tab，则此属性默认为tab_width
indent_size = 2

# 设置缩进风格(tab是硬缩进，space为软缩进)
indent_style = space

# tab_width    用一个整数来设置tab缩进的列数。默认是indent_size

# 支持一行最大的字符长度
max_line_length = 80

# 设为true表示会去除换行行首的任意空白字符。（去掉'空行'的空格）
trim_trailing_whitespace = true

[*.md] # 针对.md文件
max_line_length = 0
trim_trailing_whitespace = false

[COMMIT_EDITMSG]
max_line_length = 0

Prettier

代码格式化。

Prettier之后，它能去掉原始的代码风格，确保团队的代码使用统一相同的格式。

VSCode插件

prettier.png 如果安装了prettier 插件，那么就会带默认的格式化。

vscode内部配置prettier

// setting.json
​
// 设置编辑器的默认格式化工具为prettier
"editor.defaultFormatter": "esbenp.prettier-vscode",
// 为javascript语言指定格式化工具为prettier
"[javascript]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode"
},

ctrl + s 就会自动格式化。

上面，就只是针对vscode编辑器（本身支持），那么使用webstorm呢，那么还能格式化吗？

那么就需要使用第三方包

配置prettier

npm install prettier -D // 开发时依赖，打包的时候，不需要打包

在根目录下创建 json文件 或则 js文件

// .prettierrc      json文件
{
  "useTabs": false, 
  "tabWidth": 2
}

// .prettierrc.js    js文件 （可以写备注，比较习惯）
module.exports = {
  trailingComma: "es5", // 在对象或数组最后一个元素后面是否加逗号（在ES5中加尾逗号）
  useTabs: false, //使用空格代替tab缩进
  tabWidth: 2, // 缩进长度
  semi: false, // 句末使用分号
  singleQuote: true, // 单引号（JSX会忽略这个配置）
  jsxSingleQuote: true, // jsx中使用单引号
  arrowParens: 'always', //单参数箭头函数参数周围使用圆括号-eg: (x) => x
}

忽略prettier的配置文件

.prettierigonre文件

/node_modules/**
/dist/*
​
**/*.svg
**/*.sh
​
/public/*

命令格式化

如果项目的每个文件夹，都需要要格式化一波的话，那么就不可能每个文件去ctrl + s保存一下，这时候就需要使用命令行了

 // package.json
"scripts": {
   "prettier": "prettier --write ."
 },

npm run prettier 就会针对项目的所有文件（除了忽略文件）进行格式化。

Eslint

ESLint 是一个语法规则和代码风格的检查工具，可以用来保证写出语法正确、风格统一的代码。

VSCode插件

eslint.png

针对vscode，也推荐安装eslint插件。

npm install eslint -D

然后执行 eslint --init 命令

1：你想eslint做什么事

eslint1.png

2：你的项目使用什么模块类型

eslint2.png

3：你的项目是什么框架？ react 还是 vue

eslint3.png

4：支持的环境

eslint4.png

5：用什么文件类型管理。推荐JavaScript(可以写备注)

eslint5.png

注意： 第五步，如果是使用yarn创建的项目，最好是自己去安装，如果选择Yes ,是通过npm去安装的，就会生成 package-lock.json , 与项目中的 yarn.lock在某些情况下，是会产生冲突的。（针对 npm create @eslint/config 就不在乎这一步了）。

执行完上面的命令， 就会生成一个 .eslintrc.js文件：

module.exports = {
  // 项目配置文件查找，如果找到 root 为true，就停止查找
  "root": true,
  // env 启用的环境
  "env": {
    "es2021": true,
    "browser": true,
    "node": true
  },
  // 继承的规则 （ 字符串 或则 字符数组[后面的配置继承前面的配置] ）
  "extends": [
    "eslint:recommended", // 启用一系列核心规则 eslint规则页面展示
    "plugin:react/recommended", // eslint-plugin-react的规则配置
    "plugin:@typescript-eslint/recommended" // ts规则配置
  ],
  // 指定让 ESLint 使用自定义的解析器 @typescript-eslint/parser
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    // 想使用额外的语言特性
    "ecmaFeatures": {
      "jsx": true //启用jsx
    },
    // emcaVersion用来指定你想要使用的 ECMAScript 版本
    "ecmaVersion": 13,
    // 设置为 "script" (默认)或"module"（如果你的代码是 ECMAScript 模块)
    "sourceType": "module"
  },
  // plugins与上面的继承的配置，一一对应（不知道是不是这样理解的）
  "plugins": [
    "react",
    "@typescript-eslint"
  ],
  // 这里主要就是我们规则的配置对象
  "rules": {
  }
};

plugins: 插件。插件是一个npm 包，通常输出规则，可以提供处理器。

parser: 解析器。 eslint的默认解析器： Espree

以下解析器与 ESLint 兼容： 1、Esprima 2、Babel-ESLint: 一个对Babel解析器的包装，使其能够与 ESLint 兼容。

3、@typescript-eslint/parser : 将 TypeScript 转换成与 estree 兼容的形式，以便在ESLint中使用。

parserOptions 解析器的配置。

rules 我们平时配置规则的对象。

规则配置：

"off" 或 0 - 关闭规则

"warn" 或 1 - 开启规则，使用警告级别的错误：warn (不会导致程序退出)

"error" 或 2 - 开启规则，使用错误级别的错误：error (当被触发的时候，程序会退出)

"rules": {
    eqeqeq: "off", 
    curly: "error"
}
// 等价于
"rules": {
    eqeqeq: 0, 
    curly: 2,
    quotes: ["error", "double"] // 也可以是个数组，数组第一个：表示规则的严重程度（数字或字符串）
}

当然这些规则，一般是在平时的积累中熟悉的，只有自己去慢慢的熟悉。在开发项目过程中，慢慢完善。

eslint与prettier的规则冲突

npm install eslint-config-prettier eslint-plugin-prettier -D // 开发时依赖

// .eslintrc.js
module.exports = {
    "extends": [  // 后面的相同规则覆盖前面的
        "eslint:recommended", // 启用一系列核心规则 eslint规则页面展示
        "plugin:react/recommended", // eslint-plugin-react的规则配置
        "plugin:@typescript-eslint/recommended", // ts规则配置
        "plugin:prettier/recommended" // 推荐使用prettier的规则（处理兼容的）
  ],
  // extends 里面不能有空格
}

eslint 与 prettier的兼容处理

eslint 和 prettier的区别

eslint 是语法和格式的检查工具。（在代码过冲中，会报警告和错误）

prettier 仅仅是格式化检查，不关心语法的（格式化插件）

eslint的命令行修复

"lint": "eslint --fix --ext .js,.ts,tsx,jsx src"
// --fix 自动修复
// --ext 其他的文件后缀名（默认js）
// src   检查src目录下的文件

npm run lint 就会自行修复项目中的部分eslint语法错误

eslint的规则配置大全

eslint.bootcss.com/docs/rules/

Git Husky

在项目中，我们已经使用了eslint的一些列规范，来约束我们的代码格式。但是呢？并不能保证我们每个人的代码都是符合规范的（比如：没有对一些文件进行ctrl + s格式化 ），然后就进行了commit的操作，那么就导致了仓库中的代码就是不会符合规则的。

那么如何解决呢？

那么我们需要在执行 git commit 命令的时候对其进行校验，如果不符合eslint规范，那么自动通过规范进行修复；（执行 eslint --fix类似操作）

Husky工具

husky是一个git hook工具，可以帮助我们触发git提交的各个阶段：pre-commit、commit-msg、pre-push

npm：

npx husky-init && npm install // 这里是一个组合命令
// 相当于
npm install husky
// package.json
"script": {
   "prepare": "husky install",
}
// 执行
npx husky add .husky/pre-commit "npm run lint"
// lint 就是eslint 自动修正规范的命令

yarn:

// 先配置package.json
"script": {
    // prepare脚本会在yarn add之后自动执行,生成 .husky文件夹（根目录）
   "prepare": "husky install",
}

// 安装 husky
yarn add husky

// 执行
npx husky add .husky/pre-commit "npm run lint"

执行上面npx husky add .husky/pre-commit "npm run lint" 会在 .husky文件夹下创建一个pre-commit文件

// pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
​
npm run lint 或则 yarn lint

该文件就是用来拦截commit，在执行commit之前，调用npm run lint脚本，格式化代码之后，提交。

Git的提交规范

在团队合作的项目开发中，git 是我们首选的工具。

git add .
git commmt -m '提交信息'
git push

在上面的步骤中，commit的命令的提交信息 是比较重要的。因为在版本回退的时候就非常的有作用了。

所以需要对提交信息 做出相应的规范。

这篇文章，详细的讲述了git commit的提交规范。

zhuanlan.zhihu.com/p/182553920

Git commit 提交规范

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

type(必填): 提交信息的类型。

scope(选填)： 提交影响的范围

subject(必填)： 本次的详细描述

Type的类型

ype作用
feat新增特性 (feature)
fix修复 Bug(bug fix)
docs修改文档 (documentation)
style代码格式修改(white-space, formatting, missing semi colons, etc)
refactor代码重构(refactor)
perf改善性能(A code change that improves performance)
test测试(when adding missing tests)
build变更项目构建或外部依赖（例如 scopes: webpack、gulp、npm 等）
ci更改持续集成软件的配置文件和 package 中的 scripts 命令，例如 scopes: Travis, Circle 等
chore变更构建流程或辅助工具(比如更改测试环境)
revert代码回退

Git commit提交的方式

方式一：手动填写

git commit -m 'feat(login): 修改了登录接口'

在平时的开发过程中，我就是喜欢这种，只要记住了格式就OK了。

方式二： 工具提交（commitizen）

Commitizen 是一个帮助我们编写规范 commit message 的工具；

1、安装：

yarn add commitizen cz-conventional-changelog -D

2、在package.json中配置

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

3、使用 命令 npx cz

第一步： 选择 commit type

git1.png

第二步：影响的范围

git2.png

第三步：commit 描述信息（不能超过87字符）

git3.png

第四步：长描述（一般不写）

git4.png

第五步：是否是重大的变动（默认为NO）

git5.png

第六步：是否影响某个open issue（一般针对开源项目）

git6.png

上面的一些列操作之后，就会生成一个commit信息（是不是感觉比较的麻烦）

Git commit的信息验证

虽然有了上面的一些Git commit提交规则，但是呢，并不能防止，还是有些人随意的提交。

git commit -m '哈哈哈'

这个提交记录还是在git提交信息队列里面，那么提交规则就没有什么意义了。那么，怎么验证提交信息是否按照提交规则来的呢？

使用 commitlint 来验证提交的规则，是否符合规范。

安装：

yarn add @commitlint/config-conventional @commitlint/cli -D

使用：

在根目录创建commitlint.config.js文件，配置commitlint

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

使用husky生成commit-msg文件，验证提交信息

npx husky add .husky/commit-msg "npx --no-install commitlint --edit $1"

配置好之后，就能验证提交信息的规则了。

完整的项目目录结构

react项目示例

path.png

总结

一步一步操作下来，感觉项目的配置规则还是挺多的，慢慢的学会了，以后就简单了。 如果有错误的，请指教。

2023年4月2日补充

eslint 和 prettier 的2023年补充学习

2023年4月1日，重新搭建项目，发现针对 eslint 和 prettier 的使用还是模模糊糊，只知道存在这两个东西，重新学习一下。

两者对比

两者都是服务于团队，实现项目的统一化。

  • eslint

    • 针对代码质量进行检查
    • 针对代码风格进行检查

  • prettier

    • 针对代码风格进行检查

团队目标

  • 代码的质量统一
  • 代码的风格统一

有了 eslint, 为什么还需要 prettier？

eslint 从名字就可看出，只是针对 javascript / typescript 文件，如果需要支持其他的文件，就需要安装插件配置。

选择 prettier 的优势：

  1. eslint 配置比较麻烦，并且 lint 的速度也比较慢；prettier的配置相对于 eslint 来说简单很多。
  1. prettier 支持多种格式，html、css、js、vue、less、jsx 等等。

vscode 使用 eslint

  1. 在 vscode 安装 eslint 插件，并且启用。
// vscode ===> setting.json
{
  "eslint.enable": true // 开启 eslint 检查
}
  1. 在项目中或者全局中安装 eslint 模块，并且也需要安装配置项的依赖插件。
  2. 配置规则文件：.eslintrc.js 或者 .eslintrc.json，或者在 package.json 中的 eslintConfig 配置。

方法一：eslint 格式化

方法二：执行 lint 命令 pnpm run lint

都会去自动读取配置文件，进行检查，发现不满足要求的地方，就是使用波浪线(红色，黄色)进行标记。

上面三步都配置好了，eslint 也就可以正常工作了，但是呢？

当发现了异常，只会给开发者看，需要开发者手动去解决，不会主动去修改，那么怎么实现保存时，自动格式化呢？

"editor.codeActionsOnSave": {
  // 使用eslint来fix，包括格式化会自动fix和代码质量检查会给出错误提示
  "source.fixAll.eslint": true,
  - "source.fixAll": true // 表示所有提供的代码格式工具进行代码格式化，就是不仅仅只是eslint格式化，还是其他的也会进行格式化（不建议配置）
}

配置了，保存的时候也就会自动格式化了。

vscode 使用 prettier

  1. 不需要在项目中安装 prettier 模块，只需要安装 vscode 提供的 prettier 插件即可。（插件名称：prettier-code formmater）。
  2. 配置，启用 prettier 。
// 在vscode中安装Prettier插件并启用，两种形式
  // - 同时需要设置Prettier为对应的代码默认格式化，
      {
        "editor.defaultFormatter": "esbenp.prettier-vscode" // 默认的代码格式化工具
      }
  // - 或者将其设置为指定语言的代码格式化。
      "[javascript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
      },
      "[typescript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
      },

当配置了，prettier 也就会生效了，但是呢？也还是不会在保存的时候自动格式化，那么该怎么配置呢？

分为两种情况，针对 prettier.requireConfig 配置：

  • 如果为 prettier.requireConfig: true，表明需要配置文件，即在根目录文件夹下存在配置文件 .prettierrc 或者 .editorconfig，读取配置进行格式化；如果没有配置文件，就会报错。
  • 如果为 prettier.requireConfig: false，表明不需要配置文件，即根目录下不需要配置文件，使用默认的格式化规则。但是哈，如果存在配置文件，也会自动的去读取。
{
  "editor.formatOnSave": true, // 开启保存文件自动格式化代码
  "editor.defaultFormatter": "esbenp.prettier-vscode", // 默认的代码格式化工具
  "prettier.requireConfig": true // 需要Prettier的配置文件
}

优先级：.prettierrc > .editorconfig > vscode 默认规则。

不是覆盖而是合并，冲突再采用优先级的规则。

.prettierrc和.editorconfig同时存在时，二者内容会进行合并，若配置项有冲突，这.prettierrc的优先级更高。

eslint 和 prettier的冲突解决

eslint 和 prettier 都能进行代码格式化，当一些规则存在冲突的时候，自动格式化，就不知道采用哪种规则，那么如果解决呢？

针对 prettier 的优劣势：

  • 优势：可以对多种语言进行格式化，不仅限于 javascript
  • 劣势：不能对代码的质量进行检查

所以，eslint 和 prettier 相互配合，更加利于项目开发。

针对两者的冲突，实现的方案：

  • 针对属性级别：相同的规则，采用规则一致化（也就是针对相同的规则，直接采用 prettier）
  • 针对文件级别：同一种语言（后缀名文件），只采用一种格式化（要么是 eslint, 要么是 prettier ）

针对属性级别

当使用 eslint 代码格式化时，针对可能存在相同冲突的规则，关闭 eslint 的相关规则，采用 prettier 的规则。

实现该功能：

pnpm install eslint-config-prettier eslint-plugin-prettier -D

// .eslintrc.js
module.exports = {
  "extends": [
    "plugin:prettier/recommended" // 推荐使用 prettier 的规则（处理兼容的，放在最后一排）
  ],
}

针对文件级别

上面的方案，eslint 和 prettier 都参与了格式化，只是针对相同属性的规则，采用 prettier 的规则。

那么就可以针对某种文件类型，只采用一种格式化，比如关闭 prettier 的格式化，采用 eslint 的格式化。

// setting.json
{
    "editor.formatOnSave": true, 
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    //针对共用的语言如JS、TS和JSX关闭文件保存自动格式化功能，通过eslint来做这件事 
    // 关闭 prettier 的格式化，针对 js / ts / jsx 
    "[javascript]": { 
        "editor.formatOnSave": false 
    }, 
    "[javascriptreact]": {
        "editor.formatOnSave": false
    },
    "[typescript]": {
        "editor.formatOnSave": false
    },
    // 关闭 prettier 的格式化，采用 eslint 的格式化
    "editor.codeActionsOnSave": { //告诉ESLint插件在保存时运行 
        "source.fixAll.eslint": true 
    }
}

eslint 的变动

创建 .eslintrc.js 文件，有所变动，采用的是 npm create @eslint/config 命令。

react + vite + eslint 的生成

// .eslintrc.cjs  大部分的配置上有简单的解释
module.exports = {
  "env": {
    "browser": true,
    "es2021": true,
    "node": true // 这里需要有，不然 module.exports 有红色波浪线
  },
  "extends": [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:@typescript-eslint/recommended",
    // react17后，不需要引入React了
    + "plugin:react/jsx-runtime",
    "plugin:prettier/recommended" // 推荐使用 prettier 的规则（处理兼容的，放在最后一排）
  ],
  "overrides": [
  ],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module"
  },
  "plugins": [
    "react",
    "@typescript-eslint"
  ],
  
  // 针对使用 npm lint, 会报出一个警告，针对 eslint-plugin-prettier
  + settings: {
  +  react: {
  +    version: "detect",
  +  },
  + },
    
  "rules": {
    "indent": ["error", 2],
    'jsx-quotes': ["error", "prefer-double"]
  }
}
​

学习资料

juejin.cn/post/715689…

juejin.cn/post/721357…

juejin.cn/post/711829…

avatar
文章
阅读
粉丝