我所理解的 Lint 最佳实践(9):让 Lint 规则覆盖所有适用的代码位置
用 ESLint 约束源码的目录归属时,文件路径就是判断依据。检查一段表达式时,路径只能帮助工具选中它所在的文件。把同一个表达式从 Vue 脚本移进模板,它还在同一个文件里,原来会报的规则却可能漏掉它。
写规则时,我会先问这条规则凭什么认定违规。只看运算符就能判断的检查,可以在任何能解析出该运算符的位置执行。依赖变量声明、类型或运行环境时,先确认那些信息在当前位置能否取得。只要违规的理由相同,同一种写法就应该得到同样的诊断。
文件被检查后,还要访问文件里的表达式
ESLint 遍历 JavaScript 的抽象语法树(AST),遇到指定的节点时调用规则注册的函数。规则通过 create() 返回这些访问函数,通常称为 visitor。例如 BinaryExpression 会收到 left == right 这样的二元表达式。规则的入口和节点选择器见 ESLint 自定义规则指南。
vue-eslint-parser 也会把 <template> 里的 left == right 解析成 BinaryExpression。脚本里的表达式由 ESLint 的普通遍历访问,模板里的表达式挂在模板节点下,需要另行接入那棵树。判断只依赖运算符时,两个入口可以调用同一个检查函数。模板访问器的用法见 eslint-plugin-vue 开发指南。
下面是规则 create() 中负责注册访问器的片段,checkComparison 负责实际检查。接入 Vue 时,defineTemplateBodyVisitor() 的第一个参数负责模板,第二个负责脚本。没有这项解析器服务时,ESLint 仍可用原来的访问器遍历普通脚本。
const visitor = { BinaryExpression: checkComparison };
const { parserServices } = context.sourceCode;
return parserServices.defineTemplateBodyVisitor?.(visitor, visitor) ?? visitor;
官方插件把 ESLint 核心 eqeqeq 的比较约束带到了模板表达式中,详见 vue/eqeqeq 规则文档。
维护自有插件时,可以把这种注册方式放进共享入口,让检查表达式形态的规则直接复用。检查静态 import 后缀的规则仍然监听脚本里的声明节点。模板表达式没有这种声明,自然没有检查对象。
枚举顺序检查还要确认变量来自哪里
检查 Object.values(Mode)[0] 时,仅凭调用的形状不能断定问题。枚举顺序规则要先确认 Mode 是普通字符串枚举,运行时会生成枚举对象。把对象的第一个值当成默认项,会让默认行为随枚举成员的声明顺序改变。
<script setup lang="ts">
enum Mode {
Edit = 'edit',
Read = 'read',
}
const modes = Object.values(Mode);
const layouts = [{ primary: 'compact' }];
</script>
<template>
<p>{{ Object.values(Mode)[0] }}</p>
<p>{{ modes[0] }}</p>
<p v-for="Mode in layouts" :key="Mode.primary">
{{ Object.values(Mode)[0] }}
</p>
</template>
前两个表达式都依赖枚举顺序。第一个直接读取枚举值数组,第二个先在脚本里把枚举值数组存到 modes。脚本会按词法作用域解析 Mode 和 modes。来到模板,规则要先看名字是不是由 v-for 或插槽引入,再把可以关联到脚本的引用追到声明。最后一个表达式里的 Mode 指当前的布局对象,因此不会触发枚举顺序规则。
共享入口负责让规则看到表达式。需要追踪来源时,规则分别取得脚本绑定或模板绑定,再共用判断逻辑。报错位置指向实际的取位操作。默认项可以直接写成 Mode.Edit,列表顺序可以写成 [Mode.Edit, Mode.Read]。modes.includes(Mode.Edit) 只检查成员是否存在,交换枚举成员的声明顺序也不会影响它。
用成对样例验收规则的覆盖范围
只测一个 .vue 文件,很容易只测到其中的 <script setup>。写回归用例时,可以保持输入和违规前提相同,只换表达式所在的位置。再保留一组位置相同、但违规前提不同的样例,确认新增的入口没把无关写法一并拦住。
| 样例 | 预期 |
|---|---|
独立 .ts 或 Vue 脚本中的 Object.values(Mode)[0] |
报告取位 |
模板插值或属性绑定中的 Object.values(Mode)[0] |
报告取位 |
脚本生成 modes,模板读取 modes[0] |
报告模板里的取位 |
v-for 引入同名变量,模板在循环内读取它 |
放过 |
只用 .includes() 校验枚举成员 |
放过 |
迁移现有规则时,可以先跑一遍这些样例。某个位置漏报,就查访问器有没有收到表达式,再顺着表达式核对变量声明。带自动修复的规则还要重新解析修复后的模板,确认替换文本没有破坏属性引号。把一段违规代码移到另一个位置,只要违规的理由没变,它就仍然会被指出来。