跳到正文

我所理解的 Lint 最佳实践(8):用 ESLint 检查源码文件的目录归属

我所理解的 Lint 最佳实践

  1. 把项目约定写成 ESLint 护栏
  2. 使用 Stylelint 而不是 @eslint/css 检查样式
  3. 用 ESLint 约束 Nuxt 的自动导入
  4. 用 ESLint 判断 Vue 组件的根 Block
  5. 用 ESLint 守住 Composable 的模块边界
  6. 给 Nuxt 模块级 Composable 补上 SSR 护栏
  7. 用组件调用图检查可选 props
  8. 用 ESLint 检查源码文件的目录归属(当前)
  9. 让 Lint 规则覆盖所有适用的代码位置

在 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。这里给目录模式加了一个 **/ 前缀,从上层工作区运行时也能匹配。