eslint规则插件开发-自定义
eslint我们常应用在代码静态扫描中,通过设定的eslint的语法规则,来对代码进行检查,通过规则来约束代码的风格,以此来提高代码的健壮性,避免因为代码不规范导致应用出现bug的可能。而规则是自由的,可以设定内部自己团队适用的规则,也可以直接使用开源社区比较热门的规则集合, 比如airbnb、eslint-plugin-vue等。当完成上面一系列操作之后,eslint插件模版初步完成,接下来我们
前言
eslint我们常应用在代码静态扫描中,通过设定的eslint的语法规则,来对代码进行检查,通过规则来约束代码的风格,以此来提高代码的健壮性,避免因为代码不规范导致应用出现bug的可能。而规则是自由的,可以设定内部自己团队适用的规则,也可以直接使用开源社区比较热门的规则集合
, 比如airbnb、eslint-plugin-vue等。
一、ESLint配置
手写规则前,让我们重温下eslint配置,通常我们是使用
.eslintrc.js
来配置eslint的,或者也可以直接package.json
中定义eslintConfig的属性
上图👆是eslint主要的配置,我们简单回顾下每个配置的背后包含的意义
1.1 parse
parse 是用来定义eslint所使用的解析器,默认是使用
Espree
🔗, 解析器的作用是将代码code转化成为一种AST抽象语法树,eslint中叫ESTree
,你可以理解为将code翻译为ESLint
能听👂懂的话
常用的解析器
还有包括以下几种:
- Esprima: 上文提到espree就是基于Esprima改良的
- Babel-esLint:一个对Babel解析器的包装,当你项目中使用了babel,babel的解析器会把你的code转换为 AST,然后该解析器会将其转换为ESLint能懂的 ESTree。这个目前我们应用的较多,目前也不再维护和更新,升级为
@babel/eslint-parser
- @typescript-eslint/parser: 将 TypeScript 转换成与 estree 兼容的形式,以便在ESLint中使用
对于AST的模拟生成,感兴趣的同学可以使用astexplorer在线尝试
总结:无论你使用那种解析器,本质是都是为了将code转换为ESLint能够阅读
的语言ESTree
🔗
1.2 parseOption
parserOptions参数是用来控制parse解析器, 主要包括以下几个属性👇,我们挑重点的讲讲
- ecmaVersion
:用来指定你想要使用的 ECMAScript 版本,默认设置为 5,举个例子:默认情况下,ESLint 支持 ECMAScript 5 语法,但如果你想让eslint使用es6特征来支持,就可以通过修改parserOptions中
"ecmaVersion": 6
1.3 rules
rules就是eslint的规则,你可以在rules配置中根据在不同场景、不同规范下添加自定义规则详情可参考Eslint规范手册
1.4 extends(扩展) 与 plugins(插件)
extends和plugins很容易混淆,本质是为了加强eslint的扩展性,使得我们可以直接使用别人已经写好的eslint 规则,方便快捷的应用到项目中
比如你使用extends去扩展 { "extends": [ "eslint:recommended", "plugin:react/recommended", "eslint-config-standard", ]}
但是如果你想用插件,其实等价于 {"plugin": ['react','standard']}
⏰ 提醒:官方规定 npm 包的扩展必须以 eslint-config-
开头,我们使用过程中可以省略这个开头,上面案例中 eslint-config-standard 可以直接简写成 standard。同样,如果要开发一个eslint插件,也是需要以这种形式来命名,下节会介绍
举个列子:
上图我们通过上面这个配置例子,我们可以看到要么是plugins:[]
要么是extends:[]
,通过上图所示的配置二相对于配置一少了parser
, parserOptions
和 plugins
等的信息配置,但其实这两个配置最终实现的结果是一致的,这是因为配置二中定义的extends:plugin:@typescript-eslint/recommended
会自动加载上叙提到的其他几个配置信息
二、开发eslint插件
通过上述对eslint的配置的了解,接下来看看如何从0到1开发一个eslint插件
2.1 ESLint插件初始化
ESLint 官方为了方便开发者,提供了使用Yeoman脚手架的模板(generator-eslint🔗)。以此方便我们通过该脚手架拉取eslint插件模版
2.1.1 安装脚手架
执行下列命令来安装开发eslint的脚手架
yo(yeoman)是一个脚手架工具,可以用于生成包含指定框架结构的工程
generator-eslint是ESLint官方为了方便开发者开发插件,提供的一个功能包
npm install -g yo generator-eslint
2.1.2 项目准备
mkdir eslint-plugin-demo
cd eslint-plugin-demo
2.1.3 生成项目模板
准别好项目目录之后,初始化ESLint项目结构
yo eslint:plugin
运行完之后,在项目中生成了基本的模板文件,此时在eslint-plugin-demo中的文件结构为:
|--lib
| |-index.js
| |-rules
|--test
| |-lib
| |-rules
2.1.4 生成规则文件
yo eslint:rule
执行上述命令生成eslint rule的模板文件,这里比如我们想制定一条ESLint规则检测在代码中不可使用console.error()这个函数,避免在浏览器控制台中会抛错
此时的项目结构如下所示:
2.2 ESLint运行原理
我们的代码在使用ESLint的大体是会经历以下几个步骤:
2.2.1 将代码解析为AST
将源码解析为AST的过程需要借助解析器,解析器有很多,可以参考AST在线解析
上图方框内都是常用的JS语法解析器,可以将JS/TS解析为AST。默认eslint 会使用espree这个解析器。参考来源ESLint中文文档
我们再左边输入代码,右侧就可以根据所选择的解析器将代码解析为AST了。比如
也可以借助一些可视化的工具将其解析为树,可以看到代码在解析的过程中会生成多少节点(node)和token。AST语法解析(查看node & token)
2.2.2 遍历AST各个节点
在生成AST之后,ESLint会先"从上至下"再"从下至上"的顺序遍历每个选择器两次
2.2.3 触发监听AST选择器的rule规则回调
每一条ESLint规则都会用AST节点选择器对AST树中的节点进行监听,在遍历AST过程中,如果命中ESLint规则的选择器就会触发该规则对应的回调
2.2.4 再将AST生成代码
命中之后,在触发回调的过程中,我们可以对AST做一些修改,然后再重新生成代码。比如eslint的自动修复就是依赖于此
整个过程可以用一张图表示:
2.3 开发自定义规则
当完成上面一系列操作之后,eslint插件模版初步完成,接下来我们找到目录中
lib/rules
中对刚刚创建的rule进行开发
先看一下使用脚手架生成的lib/rules/no-console-error.js文件内容:
/**
* @fileoverview no console.error() in your code
* @author yjian
*/
"use strict";
//------------------------------------------------------------------------------
// Rule Definition
//------------------------------------------------------------------------------
/** @type {import('eslint').Rule.RuleModule} */
module.exports = {
meta: {
type: null, // `problem`, `suggestion`, or `layout`
docs: {
description: "no console.error() in your code",
recommended: false,
url: null, // URL to the documentation page for this rule
},
fixable: null, // Or `code` or `whitespace`
schema: [], // Add a schema if the rule has options
},
create(context) {
// variables should be defined here
//----------------------------------------------------------------------
// Helpers
//----------------------------------------------------------------------
// any helper functions should go here or else delete this section
//----------------------------------------------------------------------
// Public
//----------------------------------------------------------------------
return {
// visitor functions for different types of nodes
};
},
};
这是脚手架生成的自定义规则的模板,一个规则的源文件导出一个具有以下属性的对象。在生成的模板中可以看到主要有meta和create两部分。简单介绍下这两部分
- meta:代表该规则的元数据,比如类别啊,对应的文档啊,还有一些入参的schema等
- create:规则的具体实现,该方法会return 一个对象,该对象的key就是AST语法树的节点选择器。
2.3.1 meta字段
截图展示的是meta中的元数据:
2.3.2 create函数
create(function) 返回一个对象,该对象具有 ESLint 调用的方法,在遍历 JavaScript 代码的抽象语法树(由 ESTree 定义的 AST)时 visit" 节点。
- 如果键是节点类型或选择器,ESLint 在down tree 时调用该 visitor函数
- 如果键是节点类型或选择器加 :exit,ESLint 在*up tree 时调用该 visitor 函数
- 如果一个键是一个事件名称,ESLint 调用该 handler 函数进行代码链路分析
一个规则可以使用当前节点和它周围的树来报告或修复问题
2.3.3 context上下文对象
context 对象包含了额外的功能,有助于规则完成其工作。顾名思义,context 对象包含与规则的上下文相关的信息。
context有以下属性:
详细的规则说明可查看
ESLint创建规则-中文
ESLint创建规则-英文
2.4 规则实现
我们将lib/rules/no-console-error.js中的文件内容修改为如下:
/**
* @fileoverview no console.error() in your code
* @author yjian
*/
"use strict";
//------------------------------------------------------------------------------
// Rule Definition
//------------------------------------------------------------------------------
/** @type {import('eslint').Rule.RuleModule} */
module.exports = {
meta: {
type: 'problem', // `problem`, `suggestion`, or `layout`
docs: {
description: "no console.error() in your code",
recommended: false,
url: null, // URL to the documentation page for this rule
},
fixable: null, // Or `code` or `whitespace`
schema: [], // Add a schema if the rule has options
// 报错信息描述
messages: {
avoidMethod: "'{{name}}' function of console is forbidden in code",
},
},
create(context) {
return {
// 'MemberExpression' 这个就是AST的节点选择器,在遍历AST时,如果命中该选择器,就会触发回调
// 关于选择器的名称,我们可以事先在 https://astexplorer.net/ 中找到目标解析器然后将其作为key即可
// 这里的选择器会在AST"自上至下"过程中触发,如果希望是"自下至上"过程中触发,需要加':exit'即MemberExpression:exit
'MemberExpression': (node) => {
// 如果在AST遍历中满足以下条件,就用 context.report() 进行对外警告⚠️
if (node.property.name === 'error' && node.object.name === 'console') {
context.report({
node,
messageId: 'avoidMethod',
data: {
name: node.property.name,
},
});
}
},
};
},
};
整个规则就写完了,原理就是依据AST解析的结果,在遍历AST时,过滤出我们想要检测的目标代码,然后对代码进行逻辑判断和修改
2.5 导出规则
我们将lib/rules/index中的文件内容修改为如下:
/**
* @fileoverview 自定义eslint规则
* @author yjian
*/
"use strict";
//------------------------------------------------------------------------------
// Requirements
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
// Plugin Definition
//------------------------------------------------------------------------------
// import all rules in lib/rules
module.exports = {
rules: {
// 项目在使用时,对应的规则名称
'no-console-error': require('./rules/no-console-error'),
},
configs: {
recommended: {
rules: {
'demo/no-console-error': 2, // 可以省略 eslint-plugin 前缀
},
},
},
}
2.6 单元测试
我们在./tests/lib/rules/no-console-error.js可以编写对应的单元测试
/**
* @fileoverview 不允许使用 console.time()
* @author lzx
*/
"use strict";
//------------------------------------------------------------------------------
// Requirements
//------------------------------------------------------------------------------
const rule = require("../../../lib/rules/no-console-time"),
RuleTester = require("eslint").RuleTester;
//------------------------------------------------------------------------------
// Tests
//------------------------------------------------------------------------------
const ruleTester = new RuleTester();
ruleTester.run("no-console-error", rule, {
valid: [
// give me some code that won't trigger a warning
],
invalid: [
{
code: "console.error('test');",
errors: [{ message: "Fill me in.", type: "Me too" }],
},
],
});
最后执行:
npm run test
2.7 NPM发布
注册一个npm账号,然后再在终端
// 登录
npm login
// 发布
npm publish
三、应用
3.1 新建项目
mkdir demo-app
cd demo-app
npm init
3.2 配置ESLint
npm i eslint --save-dev
安装刚刚发布的ESLint插件
npm install eslint-plugin-demo --save-dev
初始化 eslint 配置
npx eslint --init
在新生成的.eslintrc文件新增一个插件,插件名称为diylint
{
"plugins": [
// 这是此前使用yo eslint:plugin 生成自定义插件的ID
"demo"
],
extends: ["plugin:ecdemo/recommended"],
}
更多推荐
所有评论(0)