開發eslint外掛目的：根據專案需要，自定義滿足專案特殊需要的校驗規則 參考[eslint](https://cn.eslint.org/)官方文件展開闡述 * [外掛開發](https://cn.eslint.org/docs/developer-guide/working-with-plugins) * [自定義規則](https://cn.eslint.org/docs/developer-guide/working-with-rules) * [單元測試](https://cn.eslint.org/docs/developer-guide/unit-tests) 下面開始通過一個示例demo來介紹外掛整個開發流程 **程式碼中出現的方法及變數的詳細解釋與相關文件，會在文末給大家列舉出來，大家可以先把程式碼拷貝到自己的demo中然後結合`本文第3部分`的變數｜方法解釋去理解程式碼** >開發一個校驗註釋中是否包含指定關鍵詞的外掛(`eslint-plugin-comments-key`) # 1. 環境準備 ## 目錄結構 ```text . ├── README.md 外掛介紹文件 ├── index.js 對外暴露外掛 ├── lib │   └── rules 自定義規則 │   └── comments-key.js ├── package.json └── tests 測試自定義規則 └── lib └── rules └── comments-key.js ``` ## 安裝依賴 * eslint * mocha ```bash npm i eslint mocha -D ``` # 2. 開始編碼 ## 編寫自定義規則 >不包含自定義引數校驗規則 **/lib/rules/comments-key.js** ```js module.exports = { meta: { type: "suggestion", docs: { description: "Not allowed comment words", // 規則的簡述 category: "Stylistic Issues", // 規則分類 recommended: true // 配置檔案中的 "extends": "eslint:recommended"屬性是否啟用該規則 } }, create: function (context) { // context物件包含與規則上下文相關的資訊 // 返回一個SourceCode物件，你可以使用該物件處理傳遞給 ESLint 的原始碼 const sourceCode = context.getSourceCode() // 定義不被允許出現在註釋中的內容 const notAllowWords = ['fixme', 'xxx'] return { Program(node) { // 獲取所有註釋的節點 const comments = sourceCode.getAllComments() // 遍歷註釋節點判斷是否有不符合規範的 comments.forEach(comment => { let { loc, value, type } = comment value = value.toLowerCase() let warnWord = '' // 判斷註釋內容是否包含不被允許的word for (const word of notAllowWords) { if (value.includes(word)) { warnWord = word } } if (warnWord) { context.report({ node: comment, // 可選 與問題有關的 AST 節點 message: `註釋中含有不被允許的字元${warnWord}` // 有問題發出的訊息 }) } }) } }; } }; ``` ## 編寫測試用例 **/tests/lib/rules/comments-key.js** ```js const { RuleTester } = require('eslint') // 獲取自定義的規則 const rule = require('../../../lib/rules/comments-key') // TESTS // 加入預設配置 const ruleTester = new RuleTester({ parserOptions: { ecmaVersion: 2018 } }) const errMsg = warnWord => `註釋中含有不被允許的字元${warnWord}` ruleTester.run('comments-key', rule, { valid: [ '// sssss', '// fixdddd', `/** * 容十三內水s是說 */` ], invalid: [ { code: "// fixme: DDL 2020-4-28 測試內容", errors: [{ message: errMsg('fixme') }] }, { code: "// FIXME: DDL 2020-5-23 測試內容", errors: [{ message: errMsg('fixme') }] }, { code: `/** * xxx * 內容 */`, errors: [{ message: errMsg('xxx') }] } ] }) ``` ## 修改package.json 加入 ```js "scripts": { "test": "mocha tests/lib/rules" } ``` 執行指令碼檢視測試結果 ```bash npm run test ``` 上面的示例中限定的關鍵詞是在程式碼中寫死了的 通常的場景中如： ```js rules:{ "quotes": ["error", "double"], // 只允許雙引號 "no-warning-comments": [ // 不允許註釋開頭出現 todo｜fixme等內容 1, { "terms": [ "todo", "fixme" ], "location": "start" } ], } ``` 大多數eslint規則都擁有可配置的屬性 我們可以通過`context.options`獲取配置的屬性 下面示例加入可配置屬性，用於自定義關鍵詞的檢測(程式碼中只包含修改部分，其餘部分跟前面相同) ```js module.exports = { meta: { // ...code schema: [ // 指定該選項 這樣的 ESLint 可以避免無效的規則配置 // 遵循 json schema 後文會有介紹文件 { "keyWords": { "type": "array", "items": { "type": "string" } } } ] }, create: function (context) { // ...code // 定義不被允許出現在註釋中的內容 // 可以使用 context.options檢索一個規則的可選項，它是個陣列，包含該規則的所有配置的可選項 // console.log(context.options); // 取得設定的keywords let [argv0] = context.options let keyWords = argv0 ? argv0.keyWords ? argv0.keyWords.length > 0 ? argv0.keyWords : undefined : undefined : undefined // 沒有設定則使用預設的 let notAllowWords = keyWords || ['fixme', 'xxx'] // 忽略大小寫 notAllowWords = notAllowWords.map(v => v.toLowerCase()) // ...code } }; ``` ## 完善我們的單元測試 ```js // ...code ruleTester.run('comments-key', rule, { valid: [ '// sssss', '// fixdddd', `/** * 容十三內水s是說 */` ], invalid: [ { code: "// fixme: DDL 2020-4-28 測試內容", errors: [{ message: errMsg('ddl') }], options: [{ // 通過options 配置自定義引數 keyWords: ['ddl'] }] }, { code: '// FIXME: DDL 2020-5-23 測試內容 \n let a = "232"', errors: [{ message: errMsg('fixme') }], rules: { // 通過rules 配置eslint提供的一些規則 "quotes": ["error", "double"], }, options: [{ keyWords: ['abc', 'efg', 'fixme'] }] }, { code: `/** * xxx * 內容 */`, errors: [{ message: errMsg('xxx') }] }, { code: '// abds asa', errors: [{ message: errMsg('abd') }], options: [{ keyWords: ['abc', 'abd'] }] } ] }) ``` # 3.文中一些變數｜方法的解釋及其文件 * [meta](https://cn.eslint.org/docs/developer-guide/working-with-rules#rule-basics) (object) 包含規則的元資料 * [schema](https://cn.eslint.org/docs/developer-guide/working-with-rules#options-schemas) 指定該選項 這樣的 ESLint 可以避免無效的規則配置 * 遵循 [json schema](http://json-schema.org/) 規範 * [create](https://cn.eslint.org/docs/developer-guide/working-with-rules#rule-basics) (function) 返回一個物件，其中包含了 ESLint 在遍歷 JavaScript 程式碼的抽象語法樹 AST ([ESTree](https://github.com/estree/estree) 定義的 AST) 時，用來訪問節點的方法 * [context](https://cn.eslint.org/docs/developer-guide/working-with-rules#the-context-object) 包含與規則上下文相關的資訊 * [options](https://cn.eslint.org/docs/developer-guide/working-with-rules#contextoptions) 檢索一個規則的可選項，它是個陣列，包含該規則的所有配置的可選項 * `getSourceCode()` 返回一個[SourceCode](https://cn.eslint.org/docs/developer-guide/working-with-rules#contextgetsourcecode)物件，你可以使用該物件處理傳遞給 ESLint 的原始碼 * [getAllComments()](https://cn.eslint.org/docs/developer-guide/working-with-rules#contextgetsourcecode) 獲取所有註釋節點 * 每個註釋節點的屬性 * `loc` 註釋在文件中的位置 * `value` 註釋中的內容 * `type` 註釋的型別 `Block`｜`Line` * [report()](https://cn.eslint.org/docs/developer-guide/working-with-rules#contextreport) 它用來發布警告或錯誤（取決於你所使用的配置）。該方法只接收一個引數，是個物件 * `message` 有問題的訊息提示 * `node` (可選)與問題有關節點 * `loc` (可選)用來指定問題位置的一個物件。如果同時指定的了 loc 和 node，那麼位置將從loc獲取而非node * `data` (可選) message的佔位符 * `fix` (可選) 一個用來解決問題的修復函式 * [RuleTester](https://eslint.org/docs/developer-guide/nodejs-api#ruletester) 單元測試示例介紹 **tips:AST在開發外掛時不必深入研究，不同地方AST的實現和結構都有所差異** # 4.匯出 至此我們的外掛算開發完成了，接下來編寫對eslint暴露這個模組的程式碼 **index.js** ```js 'use strict'; module.exports = { rules: { 'diy': require('./lib/rules/comments-key') }, rulesConfig: { 'diy': 1 } }; ``` # 5.釋出npm 要在其它專案中使用的eslint-plugin外掛的話，可以把整個外掛的根目錄拷貝到目標專案的node_modules中或者釋出到`npm`中去，其它專案直接通過`npm install` 安裝這個依賴 下面介紹釋出到npm的步驟 1. 註冊npm賬號(有的話直接跳過這步驟) 直接點選[官網](https://www.npmjs.com/)註冊 2. 設定登陸的賬號 登入之前修改registry為原來的,因為國內一般用的映象源例如淘寶源:https://registry.npm.taobao.org ```bash npm config set registry https://registry.npmjs.org/ ``` ```bash npm login ``` 按提示依次輸入`賬號`,`密碼`,`郵箱` 登入完成之後,檢視當前npm使用者,不報錯說明登入成功 ```js npm whoami ``` 1. 編寫`README.md`方便指引他人使用 2. 修改packgae.json ```json { "name": "eslint-plugin-comments-key", "version": "1.0.0", "description": "校驗註釋中是否包含指定關鍵詞的外掛", "main": "index.js", "directories": { "lib": "lib", "test": "tests" }, "scripts": { "test": "mocha tests/lib/rules" }, "keywords": [], "author": "", "license": "ISC", "devDependencies": { "eslint": "^7.0.0", "mocha": "^7.1.2" } } ``` 4. 執行`npm publish`釋出npm包 至此釋出整個流程完畢 # 6.專案中引入 ### Installation You'll first need to install [ESLint](http://eslint.org): ``` $ npm i eslint --save-dev ``` Next, install `eslint-plugin-comments-key`: ``` $ npm install eslint-plugin-comments-key --save-dev ``` **Note:** If you installed ESLint globally (using the `-g` flag) then you must also install `eslint-plugin-comments-key` globally. ### Usage Add `comments-key` to the plugins section of your `.eslintrc` configuration file or `package.json`. You can omit the `eslint-plugin-` prefix: `package.json` demo ```json "eslintConfig": { "plugins": [ "comments-key" ], "rules": { "comments-key/diy":[1,{ "wordKeys":["fixme","xxx"] }] } } ``` **tips：** 如果編輯器中安裝了Eslint外掛，在編碼的時候就會給予警告⚠️ # 最後 ## eslint-plugin-comments-key相關地址 * [npm](https://www.npmjs.com/package/eslint-plugin-comments-key) * [github](https://github.com/ATQQ/eslint-plugin-comments-key/tree/master) 因筆者水平有限，內容上如有闡述不明白之處，還