前端代码规范化配置ESLint + Prettier + husky + lint-staged

站长

2024年03月18日 13:35 · 阅读数 8

上次讲了配合git提交代码之前代码注释规范检测的pre-commit插件的使用，今天来讲讲另一种前端代码规范化的工具使用，ESLint + Prettier + husky + lint-staged同样可以实现配合git钩子实现代码的规范化检测。

1. ESLint + Prettier + husky + lint-staged工具介绍

ESLint：对代码进行风格和规范进行检查，对不符合规范的代码给出提示，同时可以进行一定程度的自动修复(eslint侧重影响代码质量的问题（比如==和===）)；
Prettier：自动格式化代码工具，根据prettier规范对代码进行修复，拥有比eslint更加强大的代码规范性修复能力(prettier更侧重代码风格的问题（比如代码折行），以及对代码自动修复)；
Husky：Git hooks工具，通过配置一系列钩子，可以在git操作的不同阶段执行相应的命令；
lint-staged：在提交代码前进行lint检查时，可以让lint只检查git暂存区（staged）的文件，而不会检查所有文件；

2、使用说明

2.1、ESLint和Prettier

安装eslint和prettier及相关工具
除了安装eslint和prettier外，安装其他几个工具及它们作用分别是：

· eslint-plugin-prettier：将 prettier 的能力集成到 eslint 中, 按照 prettier 的规则检查代码规范性，并进行修复；

· eslint-config-prettier：让所有可能会与 prettier 规则存在冲突的 eslint rule 失效，并使用 prettier 的规则进行代码检查；

· @typescript-eslint/parser：解析器，使 eslint 可以解析 ts 语法；

· @typescript-eslint/eslint-plugin：指定了 ts 代码规范的 plugin；

· eslint-plugin-import：对 ES6+ 的导入/导出语法进行 lint, 并防止文件路径和导入名称拼写错误的问题；

· eslint-import-resolver-typescript：这个插件为eslint-plugin-import添加了 ts 支持。

配置.eslintrc.cjs和.prettierrc.cjs。 eslintrc.cjs

module.exports = {
    env: {
        browser: true,
        es2021: true,
        node: true,
    },
    // 为ESLint扩展其它配置文件
    extends: [
        "eslint:recommended",
        "plugin:vue/vue3-essential",
        "plugin:@typescript-eslint/recommended",
        "plugin:prettier/recommended", // 使用prettier的规则格式化代码
        "./.eslintrc-auto-import.json", // 使eslint识别自动引入的组件和API
        "plugin:jsdoc/recommended",
    ],
    overrides: [
        {
            files: ["**/*.vue"],
            rules: {
                // 限制整个 .vue 文件的代码行数（包括模板、脚本和样式）不超过 300 行
                "max-lines": ["error", { max: 300, skipBlankLines: true, skipComments: true }],
            },
        },
    ],
    parser: "vue-eslint-parser", // 配置ESLint解析器
    parserOptions: {
        ecmaVersion: "latest",
        parser: "@typescript-eslint/parser", // 配置JS解析器
        sourceType: "module",
    },
    plugins: ["vue", "@typescript-eslint", "jsdoc"],
    rules: {
        "vue/multi-word-component-names": "off", // 关闭Vue3中要求.vue文件的名称必须为多个单词的检查
        "no-unused-vars": "off", // 关闭Javascript变量未使用时的校验，在Typescript项目中必须禁用此校验，否则会误报
        "@typescript-eslint/no-unused-vars": "warn", // Typescript变量未使用时，仅发出警告，而不阻止程序运行
        "jsdoc/require-jsdoc": [
            "error",
            {
                require: {
                    ArrowFunctionExpression: true,
                    ClassDeclaration: true,
                    ClassExpression: true,
                    FunctionExpression: true,
                    MethodDefinition: true,
                },
                contexts: ["TSInterfaceDeclaration"], // 检查接口是否写注释
            },
        ],

        // 强制在注释中 // 或 /* 使用一致的空格。您可以通过这个规则来统一注释的格式
        "spaced-comment": ["error", "always"],
        // 自定义规则
        // my-custom-rule': 'error',
    },
};

prettier.config.cjs

module.exports = {
    printWidth: 140, // 单行长度
    tabWidth: 4, // 缩进长度
    useTabs: false, // 使用空格代替tab缩进
    semi: true, // 句末使用分号
    singleQuote: false, // 使用单引号
    jsxSingleQuote: true, // jsx中使用单引号
    trailingComma: "all", // 多行时尽可能打印尾随逗号
    insertPragma: false, // 在已被prettier格式化的文件顶部加上标注
    endOfLine: "lf", // 保持各平台换行符统一为lf

2.2、husky

我们已经成功安装并配置了 eslint 相关的检查，但是我们不能仅仅依靠我们开发人员的自觉来保证提交到仓库的代码符合eslint规范，这时候就需要husky这样一个工具来操作git提供的一些钩子hooks，在提交代码时对代码进行 lint 检查。

安装husky npm install --save-dev husky
向package.json的scripts中添加命令

{

  "scripts": {

    "prepare": "husky install"

  }

}

prepare命令会在执行npm install（不带参数的情况下）之后自动执行。也就是说当我们执行npm install安装完项目依赖后会执行husky install命令，该命令会创建.husky/并指定该目录为git hooks所在的目录。这里我们先手动执行一次npm run prepare。

配置husky 添加pre-commit hooks：npx husky add .husky/pre-commit 或 npx husky set .husky/pre-commit；这将在./husky/目录下生成一个pre-commit脚本文件，在文件里添加npm run lint这个命令，添加完成后文件内容为：

#!/bin/sh

. "$(dirname "$0")/husky.sh"

npm run lint

2.3 lint-staged

完成husky配置之后，我们做到了通过每次git提交时都对项目做 lint 检查，防止不符合规范的代码提交到仓库，但是这带来一个问题：每次提交都将对整个项目做 lint 检查，对于一个越来越大的项目来说，这无疑是一个很耗时的操作，除此之外，对于新接入这些配置的项目，项目中可能已经存在了大量不符合规范的代码，不能要求在提交时把所有历史遗留的问题修复之后才能提交。这个时候就需要用到lint-staged这个工具了。

安装lint-staged npm install --save-dev lint-staged
在package.json中配置lint-staged 在package.json中添加如下配置，配置表明在运行lint-staged的时候将只匹配src和test目录下的ts和tsx文件，我们可以根据自己项目的需要修改配置：

{

  "lint-staged": {

    "src/**/*.{ts,vue}": [

      "eslint"

],

// 自定义需要检测的文件目录

    "test/**/*.{ts,tsx,js,vue}": [

      "eslint"

    ]

  }

}

向package.json的scripts中添加命令：

{

  "scripts": {

    "lint-staged": "lint-staged"

  }

}

修改.husky/pre-commit脚本的内容将.husky/pre-commit脚本的内容改为npm run lint-staged

#!/bin/sh

. "$(dirname "$0")/husky.sh"

npm run lint-staged

通过上面的步骤，就完成了lint-staged的配置，这个时候再进行 git 提交时，将只检查暂存区（staged）的文件，不会检查项目所有文件，加快了每次提交 lint 检查的速度，同时也不会被历史遗留问题影响。通过这样的约束让我们定义的规则规范大家都能去遵守，共同维护代码的质量。

3 注释规则

3.1 JSDoc注释规则(www.jsdoc.com.cn/)

在 ESLint 中，JSDoc 注释规则可以帮助你确保代码中的注释符合特定的格式和约定。 JSDoc 是一种用于 JavaScript 的文档生成工具，它可以解析代码中的注释并生成易于阅读的文档要使用 ESLint 中的 JSDoc 注释规则，首先需要安装下载eslint-plugin-jsdoc插件，然后需要在 ESLint 配置文件中启用相应的规则。在项目的 .eslintrc.cjs 配置文件中进行。安装下载插件JSDoc: npm install --save-dev eslint-plugin-jsdoc eslint-config-jsdoc：；下面是一个 JSDoc 注释规则在eslint配置文件的具体配置：（官方推荐的规则集）

{  

  "extends": ["plugin:jsdoc/recommended"],

   "plugins": ["jsdoc"],  

   "rules": {  

//要求函数、类、方法等具有 JSDoc 注释

    "jsdoc/require-jsdoc": ["error",{

                    require: {

                        ArrowFunctionExpression: true,

                        ClassDeclaration: true,

                         ClassExpression: true,

                         FunctionExpression: true,

                         MethodDefinition: true,

                        },

                        contexts: ["TSInterfaceDeclaration"], // 检查接口是否写注释

                    },  

//验证 JSDoc 注释中的类型是否有效

    "jsdoc/valid-types": "error",  

//检查 JSDoc 注释的对齐

    "jsdoc/check-alignment": "error",

// 检查 JSDoc 注释中的示例代码是否有效

    "jsdoc/check-examples": "error",

//检查 JSDoc 注释中的标签名称是否符合规范

    "jsdoc/check-tag-names": "error",  

//检查 JSDoc 注释中的类型注释是否符合规范

    "jsdoc/check-types": "error",  

//要求 JSDoc 注释的描述部分之后有一个新行

    "jsdoc/newline-after-description": "error",

//要求 JSDoc 注释具有描述部分  

    "jsdoc/require-description": "error",  

//要求 JSDoc 注释的描述部分是一个完整的句子

    "jsdoc/require-description-complete-sentence": "error",  

// 要求函数或方法的每个参数都有 @param 标签

    "jsdoc/require-param": "error",  

//要求 @param 标签具有描述部分

    "jsdoc/require-param-description": "error",

//要求 @param 标签具有参数名称

    "jsdoc/require-param-name": "error",  

// 要求 @param 标签具有参数类型

    "jsdoc/require-param-type": "error",

// 要求函数或方法具有 @returns 标签

    "jsdoc/require-returns": "error",  

// 要求 @returns 标签检查函数或方法的返回值

    "jsdoc/require-returns-check": "error",  

// 要求 @returns 标签具有描述部分

    "jsdoc/require-returns-description": "error",  

// 要求 @returns 标签具有返回值类型

    "jsdoc/require-returns-type": "error"  

  }  

}

启用这些规则后，ESLint 将在代码检查期间应用这些规则，以确保 JSDoc 注释符合规范。如果代码中的注释不符合规则，ESLint 将报告相应的错误或警告。我们也可以查阅 ESLint 和 JSDoc 的官方文档以获取更多关于这些规则的信息和用法示例。

3.2 其他常用注释规则

// 强制多行注释的风格

"multiline-comment-style": ["error", "starred-block"],

 //  强制在注释中 // 或 /* 使用一致的空格。您可以通过这个规则来统一注释的格式

 "spaced-comment": ["error", "always"],

// 禁止行内注释

 "no-inline-comments": "error",

3.3 自定义注释规则

ESLint 中使用自定义规则，需要遵循几个步骤来创建、注册和应用这些规则。(未完待续)