团队协作开发vue3项目应该怎么约定目录规范 ｜ 青训营笔记

GeorgeWhite
964 阅读6分钟

这是我参与「第四届青训营 」笔记创作活动的第5天

前言

团队开发中最头疼的就是你的写的东西我不太看好，我写的东西你也吐槽。当然代码规范还好，有eslint约数。但是目录规范呢？

并没有啥插件是来约束目录命名规范以及目录文件放置位置的。所以这里就导致不同开发人员放置文件的位置各有各的个性。有的喜欢不管子文件是一个还是多个，统统都给它先包一个文件夹再说。有的干脆就全部都平摊在一级目录下面。导致整个项目风格不是很好看。

angular styleguide

我搜索了一圈之后发现好像没有哪一家有明确的文件目录放置规范和目录命名规范。但是文件命名规范倒是有，比如Vue官方就规定了文件命名规范。其中目录规范我只看到了 angular styleguide 中提到了少许。

Folders-by-Feature Structure

译文：

按功能的文件夹结构

按照功能划分来创建文件夹。当一个文件夹增长到包含超过 7 个文件时，开始考虑为它们创建一个文件夹。您的阈值可能不同，因此请根据需要进行调整。

为什么？：开发者可以定位代码，一目了然地识别每个文件代表什么，结构尽可能扁平，没有重复或冗余的名称。

为什么？: LIFT 指南都包含在内。

为什么？：帮助应用程序更好的组织内容并且保持它们和LIFT指南一致

为什么？：当有很多文件（10+）时，使用一致的文件夹结构更容易定位它们，而在扁平结构中更难定位。

注意：不要按照文件的类型来划分文件夹。这需要在编写一个功能的代码时需要同时翻开多个文件夹，并且随着应用程序增长到 5、10 或 25 个以上的视图和控制器（以及其他功能），这会很快变得很慢，这样的话会比按功能进行文件夹分类更难定位到所需要的文件

/**
 * 下面是推荐的分类方法， `folders-by-feature` 按功能划分文件夹
 * 要避免 `folders-by-type` 按类型划分文件夹
 */

app/
    app.module.js
    app.config.js
    components/
        calendar.directive.js
        calendar.directive.html
        user-profile.directive.js
        user-profile.directive.html
    layout/
        shell.html
        shell.controller.js
        topnav.html
        topnav.controller.js
    people/
        attendees.html
        attendees.controller.js
        people.routes.js
        speakers.html
        speakers.controller.js
        speaker-detail.html
        speaker-detail.controller.js
    services/
        data.service.js
        localstorage.service.js
        logger.service.js
        spinner.service.js
    sessions/
        sessions.html
        sessions.controller.js
        sessions.routes.js
        session-detail.html
        session-detail.controller.js

当然上述是编写angular时适用性是最强的。但是在编写vue应用时可能就不是太方便了。因为vue手脚架创建的模板都是按照类型进行文件夹划分的

所以目录规范的问题还得看是用什么框架。

我的调研

为此我先预先定义一些规范可选范围，然后查阅了的很多中台框架和组件库进行总结，并选择大多数中台框架所采用的规范为结果。

以下为预定义规则

  1. 组件文件名
  • 大驼峰
  • 中划线
  1. 组件目录结构
  • src类型
├─组件名
│ ├─src
│ │ ├─components
│ │ │ ├─单文件组件.vue
│ │ │ ├─单文件组件.vue
│ │ ├─单文件组件.vue
│ │ ├─单文件组件.vue
│ ├─index.ts
  • 非src类型
├─组件名
│ ├─components
│ │ ├─单文件组件.vue
│ │ ├─单文件组件.vue
│ ├─index.vue
  1. 全局css、css变量位置
  2. 全局css变量文件名
  3. 组件内style、hooks、types等位置
  • 平级型
├─index.vue/index.tsx
├─index.module.less
├─other.less
  • 目录型
├─style
│ ├─other.less
├─index.vue/index.tsx
├─index.module.less
  1. HOOK文件名
  • 中划线
  • 小驼峰
  1. 全局hook目录结构
  • 目录型
/src/hooks
├─use-xxx
│ ├─index.ts
├─index.ts
  • 平铺型
/src/hooks
├─use-xxx.ts
  1. 项目全局常量位置
  2. 项目全局类型声明文件d.ts位置
  3. 项目全局类型定义文件位置
  4. 子组件(二级组件、三级组件以及其他后代组件)位置
  • 平铺型
├─组件名
│ ├─components
│ │ ├─单文件组件.vue
│ │ ├─单文件组件.vue
│ ├─index.vue
  • 文件夹型
├─组件名
│ ├─components
│ │ ├─item
│ │ │ ├─index.vue
│ │ ├─detail
│ │ │ ├─index.vue
│ ├─index.vue
  1. interface和type变量名是否加前后缀(未调研)
  2. enum变量名是否带后缀 14.interface和type名称命名(未调研)
  • 大驼峰
  • 小驼峰
  1. 组件内工具函数文件命名(未调研)
  2. 组件分组(未调研)
  3. 组件名、文件夹名称哪些单词可以缩写(未调研)

以下为调研结果

中台框架组件文件名组件目录结构全局css、css变量位置全局css变量文件名组件内style、hooks、types等位置hook文件名全局hook目录结构项目全局常量位置项目全局d.ts位置项目全局类型声明位置子组件(二级组件)位置enum变量名是否带后缀
arco-design-pro-vue中划线非src类型/src/asset/style/src/asset/style/xxx.less未找到中划线平铺型未找到未找到/src/types平铺型未找到
ant-design-vue-pro(vue2)大驼峰非src类型/src/global.less/src/global.less平级型❌❌未找到❌❌平铺型❌
vue-element-admin(vue2)中划线非src类型/src/styles/src/styles/variables.scss平级型❌❌未找到❌❌几乎平铺型(除非该组件还有附带css，或者由几个小组件组成)❌
vue-vben-adminviews中划线 component大驼峰src类型/src/design/src/design/var/xxx.less目录型小驼峰按功能用途分类+平铺型/src/enums包括枚举+常量/types/xxx.d.ts未找到平铺型✅
iview-admin(vue2)中划线非src类型/src/index.less/src/index.less平级型❌❌未找到❌❌文件夹型❌
ant-design-pro(React)大驼峰非src类型/src/global.less/src/global.less平级型❌❌未找到/src/typings.d.ts未找到平铺型+文件夹型✅
UI 框架UI框架特点:目录型 一般还有demo、.md
element-plus中划线src类型❌❌目录型(hooks目录名称:composables)中划线目录型/index.ts❌❌❌平铺型✅
vant目录中划线 组件名大驼峰非src类型❌❌平级型中划线平铺型❌❌❌无子组件，全部打平为一级组件未找到
naive-ui目录中划线 组件名大驼峰src类型❌❌目录型中划线平铺型❌❌❌无子组件，子组件和父组件同级未找到
tdesign-vue-next中划线非src类型❌❌目录型小驼峰平铺型❌❌❌无子组件，子组件和父组件同级✅
其他
VueUse小驼峰目录/index.ts

结果

根据上述预定义规则和大多数框架的选择，得出如下结果

  1. 组件文件名：中划线

单文件组件文件的大小写

官方描述是大驼峰和中划线二选一

  1. 组件目录结构：非src类型
  2. 全局css、css变量位置：/src/asset/style
  3. 全局css变量文件名：/src/asset/style/xxx.scss
  4. 组件内style、hooks、types等位置：平级型
  5. hook文件名：中划线
  6. 全局hook目录结构：平铺型
  7. 项目全局常量位置：/src/constants
  8. 项目全局类型声明文件d.ts位置：/types
  9. 项目全局类型定义文件位置：/src/types
  10. 子组件(二级组件、三级组件以及其他后代组件)位置：平铺型(除非该组件还有附带css，或者子组件)
  11. interface和type变量名是否加前后缀：❌
  12. enum变量名是否带后缀：✅
  13. interface和type名称命名：大驼峰
  14. 组件内工具函数文件命名(未调研)：util.ts
  15. 组件分组(未调研) 分类文件夹下不得有裸露的组件，可以有统一导出文件index.ts，必须用文件夹包裹。同等于一级组件
library
 ├── generic
 │   ├── input
 │   │   └── button
 │   │       └── index.vue
 │   └── show
 │       ├── image
 │       │   └── index.vue
 │       └── swipe
 │           ├── components
 │           └── index.vue
 └── index.ts

  1. 组件名、文件夹名称哪些单词可以缩写：

avatar
文章
阅读
粉丝