我所理解的前端框架最佳实践(6):用 kebab-case 格式统一文件名
- 用表格组件减少通用渲染和交互的维护成本
- 利用派生值减少维护成本和心智负担
- 正确拆分组件
- 抽取业务逻辑后,谁持有状态和副作用
- 按入口和依赖组织大型模块
- 用 kebab-case 格式统一文件名(当前)
- 合理使用全局状态
我把项目里自己命名的源码文件统一成 kebab-case。组件叫 UserProfile,文件可以叫 user-profile.vue 或 user-profile.tsx。测试和类型声明继续用 user-profile.test.ts、user-profile.d.ts。这样从文件列表、终端或 import 路径查找一个模块时,只需要记住它由哪些词组成。
用同一套写法命名组件、测试和工具脚本
kebab-case 用小写字母写单词,单词之间用连字符。例如 workspace-tree 有 workspace 和 tree 两个词。文件路径和代码标识符承担不同的职责,React 组件导出仍写成 WorkspaceTree,Vue composable 的函数仍可以叫 useWorkspaceTree。
| 文件用途 | 文件名 | 代码里的名称 |
|---|---|---|
| Vue 组件 | workspace-tree.vue |
WorkspaceTree |
| React 组件 | workspace-tree.tsx |
WorkspaceTree |
| Vue composable | use-workspace-tree.ts |
useWorkspaceTree |
| 通用模块 | parse-workspace-path.ts |
parseWorkspacePath |
| 对应测试 | parse-workspace-path.test.ts |
测试文件沿用被测模块的基本名 |
| 类型声明 | workspace-tree.d.ts |
WorkspaceTreeNode |
Angular 把文件名的分词方式和测试后缀都写进了官方风格指南。例如,UserProfile 可以放在 user-profile.ts,对应的测试叫 user-profile.spec.ts。Vue 对单文件组件给出 PascalCase 和 kebab-case 两种统一方案,并提到混用大小写的路径在大小写不敏感的文件系统上可能带来问题,见 Vue 风格指南。
Google 的开发者文档文件命名指南也选用小写和连字符,理由包括跨操作系统兼容和文件搜索。这份指南管的是文档文件。应用源码采用同样的习惯时,我主要看重查找时的可预测性,以及组件、测试和工具脚本能使用同一套命名方式。
大小写差异会在换机器后暴露
假设磁盘上的文件是 user-profile.ts,调用方写的是 ./User-Profile。在大小写不敏感的文件系统上,解析器可能找到那个文件。换到大小写敏感的文件系统后,这两个路径可以指向不同文件,构建就可能在解析 import 时失败。Git 也会根据工作树文件系统探测 core.ignoreCase,用来处理大小写不敏感的路径查找,详见 Git 配置文档。
统一文件名可以减少这类拼写分歧。改已有文件时,还要同步修改 import、测试入口和构建配置。只改大小写时,可以先用 git mv 改成一个临时名称,再改成目标名,最后用 git status 核对 Git 记录的路径。这样做也能让大小写不敏感的工作树记录两次明确的移动。
框架约定文件名时保留它的语义
vite.config.mts 的 .config、user-profile.test.ts 的 .test 和 user-profile.d.ts 的 .d 都有各自的用途。可以把点号两边看成不同的命名段,分别用小写和连字符,保留工具识别用的后缀。
文件路由要先看框架怎样解释路径。例如 Nuxt 用 pages/users/[id].vue 识别动态参数,也允许 pages/users-[group].vue 这样的混合路由。这里可以统一静态部分的拼写,并保留参数语法和参数名。修改一个已有路由文件名之前,要核对公开 URL 和读取路由参数的代码。相关约定见 Nuxt 文件路由文档。
用 Lint 在新文件进入项目时统一检查
命名规则覆盖 ESLint 扫描到的项目源码,组件、模型、测试和构建脚本都用同一条规则。接入时用项目里的合法路径和反例试一次。例如 src/models/UserProfile.ts 和 tests/UserProfile.test.ts 都应该被提示,vite.config.mts 和 app/pages/[id].vue 则可以通过。生成物、第三方代码和特殊框架入口按实际路径处理。修改建议只提示命名方式,由维护者同时更新路径的所有消费者。
同一个仓库还有图片、样式和文章时,可以按各自的工具和发布约定选择检查范围。源码路径的统一由 ESLint 保证,图片资源和文章的公开 URL 则由对应的构建或资源检查负责。