我所理解的 Lint 最佳实践(8):用 ESLint 检查源码文件的目录归属
在 Marker 的工作台源码里,Vue 组件放进 components/,TypeScript 文件也可以放进 composables/、types/ 或 utils/。把组件放错目录时,可以让 ESLint 在命令行和编辑器里给出提示。这个判断只需要知道文件叫什么、放在哪个目录。
用语法规则报错时,允许路径藏在忽略列表里
Marker 原先靠内置的 no-restricted-syntax 报错。files 先选中工作台的 .ts 和 .vue,局部 ignores 再排除允许的位置。每个剩下的文件都有一个 Program 根节点,规则就拿它来报一次错。
这种写法能拦住放错位置的文件。维护时要同时读三个地方才能还原约定。例如,components/ 下的 TypeScript 和 Vue 文件都可以通过,utils/ 下只允许 TypeScript。这项区别藏在两个路径模式里,Program 本身看不出目录政策。ESLint 的语法限制和局部忽略分别见 no-restricted-syntax 和 flat config 文件范围。
用文件名和目录的映射表达同一个约定
eslint-plugin-check-file 的 folder-match-with-fex 直接把文件名模式映射到允许的目录模式。先把插件加为开发依赖,再把下面的 workbenchFilePlacement 放进 ESLint flat config 的导出数组。这个例子沿用项目已经配置好的 TypeScript 和 Vue parser。命令从应用的包根目录运行。
pnpm add -D eslint-plugin-check-file
import checkFile from 'eslint-plugin-check-file';
const workbenchSource = 'src/renderer/src';
export const workbenchFilePlacement = {
files: [`${workbenchSource}/**/*.{ts,vue}`],
ignores: [`${workbenchSource}/{App.vue,main.ts,env.d.ts}`],
plugins: { 'check-file': checkFile },
rules: {
'check-file/folder-match-with-fex': [
'error',
{
'*.ts': `**/${workbenchSource}/{components,composables,types,utils}/**/`,
'*.vue': `**/${workbenchSource}/components/**/`,
},
],
},
};
files 选择接受检查的文件。两个规则选项分别写明 .ts 和 .vue 文件可放的位置,**/ 覆盖目标目录及其子目录。局部 ignores 排除了三个位置固定的文件,它们仍参与其他检查。插件按文件名选规则,再匹配目录,详见 folder-match-with-fex 的选项。
验证时,我用现有项目的 ESLint 配置对照了替换前后的 17 个路径。以下是几个能看出边界的例子,路径以工作台源码目录为基准。
| 路径 | 放置检查结果 |
|---|---|
components/workspace-tree/index.vue |
通过,Vue 文件在组件目录下 |
components/workspace-tree/utils/expand.ts |
通过,组件私有工具随组件存放 |
utils/expand.ts |
通过,共享 TypeScript 工具可以放在这里 |
utils/tree.vue |
报错,Vue 文件需要放进组件目录 |
env.d.ts |
通过,根目录的环境声明使用固定位置 |
独立的 PlantUML 页面和主进程也在对照范围内。它们使用各自的源码入口,路径不会命中工作台这段配置。
共享规则可以复用,源码目录由应用决定
src/renderer/src 是 electron-vite 推荐布局里的一个位置,应用也可以用构建配置指定其他入口。即使两个项目都用 Vue,Nuxt 仍会从 app/pages/ 识别页面。仅凭 package.json 里的 Vue 依赖,能选择对应的解析器,无法知道应用把哪几类文件放在哪里。两个项目的约定分别见 electron-vite 项目布局 和 Nuxt 文件路由。
几套应用都要检查时,可以用同一个规则,各自声明源码根目录、允许目录和固定入口。
在 monorepo 里还要从工作区根目录试跑。规则里的目录路径以 ESLint 的工作目录为基准,配置块的 basePath 只影响 files 和 ignores。这里给目录模式加了一个 **/ 前缀,从上层工作区运行时也能匹配。