搭建项目规范代码风格和提高代码质量，不妨看看我怎么做

TheSnifter
110 阅读7分钟

前言

每个新的项目，都得经历从0到1的搭建过程，而一开始的代码规范配置尤为重要，这要求后续每个开发者都得按照这个规范进行代码编写，这篇文章教会你如何从项目工程化的角度，规范项目代码。

涉及技术

说到代码规范，肯定离不开 ESLint 和 Prettier，除此之外本篇文章还会手把手教你如何使用 husky 和 lint-staged 在代码提交过程中使用 ESLint 和 Prettier 进行代码校验和格式化。

ESLint

ESLint是一个静态代码分析工具，用来检查JavaScript代码中的问题，分析源代码来发现潜在的错误或风格问题，通过使用ESLint,开发团队可以维护更一致、更高质量的代码库。 主要作用:

  1. 识别并报告代码中的模式或问题
  2. 强制执行一致的代码风格
  3. 避免潜在的错误
  4. 提高代码质量

Prettier

Prettier 是一个 代码格式化工具，专注于自动统一代码风格，支持多种语言（如 JavaScript、TypeScript、CSS、HTML、JSON 等）。它的目标是消除代码风格争议，让开发者专注于代码逻辑而非格式问题。 主要作用:

  1. 支持多种语言和框架
  2. 自动格式化,保持一致的代码风格
  3. 可集成到编辑器和CI流程中
  4. 高度可配置,但默认配置已足够优秀
  5. 解决团队代码风格争议,提高协作效率

安装ESLint和Prettier以及相关配置

# 安装插件
npm install eslint prettier --save-dev
# 初始化 ESLint
npx eslint --init

ESLint校验规则文件为.eslintrc.js，位置与package.json相同层级，可以在文件中自定义检测的规则，如何某些文件不需要进行ESLint语法检查，则可以在同层级目录下新建一个忽略文件，在文件中添加不需要检查的文件路径，忽略文件名为 .eslintignore。

Prettier提交代码格式化文件 .prettierrc.js 配置，跟.eslintrc.js同层级，具体配置可以根据项目开发团队的需求进行调整。具体有哪些配置项也可以在官方文档中查看配置 文档链接

运行格式化

# 格式化单个文件：
npx prettier --write your-file.js
# 格式化整个项目：
 npx prettier --write .

当安装了这两个插件之后，两者的代码风格可能存在差异，当使用 Prettier 格式化代码之后，ESLint检验可能不通过，可以通过ESLint的配置来解决两者的冲突。

结合使用：

  1. 使用 eslint-config-prettier 关闭 ESLint 中与 Prettier 冲突的规则。
  2. 使用 eslint-plugin-prettier 将 Prettier 作为 ESLint 的规则运行。
{
  "extends": ["eslint:recommended", "plugin:prettier/recommended"],
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error"
  }
}

lint-staged

上面我们讲述了ESLint 和 Prettier，并且讲述了他们的使用，但是在实际开发中，我们不会一个文件一个文件去执行格式化，也不会一次性整个项目进行格式化，我们想要的只是针对我们本次修改的文件进行语法检查和格式化，这个时候我们可以借助 lint-staged 来实现我们的需求。

lint-staged 是一个用于在 Git 暂存区（staged files）上运行指定脚本的工具，通常用于在提交代码前对修改的文件进行 代码检查 或 格式化。它的主要作用是确保提交到代码库的代码符合团队的规范，避免将不符合规范的代码推送到远程仓库。

如何使用

# 安装依赖
npm install husky lint-staged --save-dev

在 package.json 中配置：

"scripts": {
  "lint-staged": "lint-staged"
},
"lint-staged": {
    // 可以自定义需要检查的文件格式
    "*.{json,md,html,js,jsx,ts,tsx,vue}": [
      "prettier --write"
    ],
    "*.{js,vue}": [
      "eslint --quiet --fix"
    ]
  }

当我们将代码通过 git add . 添加至暂存区后，可以通过执行 npm run lint-staged 命令，对暂存区的代码进行格式化和语法检查。

husky

虽然上面我们使用了 lint-staged 对暂存区的代码进行统一校验和格式化，但是还是不够智能，需要我们手动执行命令。为解决这个问题，我们可以借助 husky 插件来帮我们简化这个操作。

husky 的作用是通过 Git 钩子，在 Git 操作的不同阶段运行自定义脚本。它可以在代码提交前运行脚本，例如运行代码风格检查工具（如 ESLint 或 Prettier）或运行单元测试等。这样，每次提交代码时，husky 会自动运行这些脚本，并在有问题的情况下阻止提交，从而确保提交的代码符合团队的规范和标准。

# 安装依赖
npm install husky --save-dev
# 启用git hooks
npx husky install
# 初始化 husky 的设置
npx husky init 或 npx husky-init

当执行完初始化的工作后，我们就会看到项目结构下多出来一个文件夹

image.png

pre-commit 文件可以编写执行脚本，这个文件的脚本内容会在我们使用 git commit 的时候执行，我们可以在这个文件中添加我们刚才添加的 lint-staged 执行脚本，这样在我们提交代码之前就会自动执行代码格式化和检查，不需要我们手动再去执行命令。

修改 pre-commit 的文件内容为

npm run lint-staged 或 yarn lint-staged // 表示在git执行commit之前，先执行package.json中的 lint-staged 命令
exit 1 // 该命令可以无需提交代码即可验证 pre-commit 钩子，如果添加该命令，会终止git

配置完这些内容后就可以尝试编写违反检验规则的内容并进行提交，如果代码符合检验规则则会进行正常的提交，如果违反检验规则，则会中断提交过程，并在控制台提示哪些内容不符合规范。

注： 如果确实需要提交违反检验规则的代码，可以在提交代码的时候加上 -n 或者 --no-verify 指令来跳过本次提交代码的检查

git commit -m "message" --no-verify

husky不仅可以在提交代码前执行脚本对代码内容进行校验，也可以针对我们提交代码时通过 -m 输入的提交信息进行检查，一般可以用来要求团队成员提交代码时必须按照某种格式表明本次提交的目的。

Commit-msg钩子设置提交信息校验

npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1' # 通过指令在.husky文件夹下新建一个commit-msg文件（钩子）

在创建的文件中可以编写shell脚本或者nodejs脚本来对提交信息进行一个校验，以下时通过shell脚本编写的对commit信息进行检验的代码示例

#!/bin/sh

# 获取执行 commit 的提交信息
commit_msg=`cat $1`
# 设置颜色变量
RED='\033[0;31m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# 定义提交信息规范函数
check_commit_message() {
    # 拿到函数传递的参数进行判断
    commit_msg="$1"
    # 检查提交信息是否以指定的前缀开头，正则表达式可以按需修改
    if ! echo "$commit_msg" | grep -qE "^(feat|fix|docs|style|refactor|test|chore|ci):"; then
        echo "${RED}Error:${NC} Commit message format is incorrect. It should start with one of '${BLUE}feat|fix|docs|style|refactor|test|chore|ci:${NC}'." >&2
        # exit 1表示不符合匹配，返回1终结提交
        exit 1
    fi
}
# 执行函数并传递参数
check_commit_message "$commit_msg"

echo "${BLUE}Commit message check passed.${NC}\n"
# nodejs脚本，通过 process.exit(1) 来终止提交

结语

可能大家觉得使用ESLint不是折磨自己吗，其实不然，。在vscode配置保存自动格式化和格式化的规范按照ESLint规范，其实在开发过程中并不会因为ESLint让自己花更多时间，并且好的代码规范才能更好的迭代，大家编码风格一致，你迭代别人的需求也轻松。

本篇文章只是简单讲述了几个技术的作用，以及他们之前如何进行搭配使用方便我们的日常开发需求，除了文章介绍的作用之外，还有更多的使用方向和技巧以及各种配置项，大家感兴趣的话可以查看官方技术文档进行深入学习。如果文章有什么不对的地方，欢迎大家指正。

avatar
文章
阅读
粉丝