初级 Vue 前端开发者的命名与代码规范指南

一、命名

1.1 基本原则

1.1.1 不要有拼写错误的单词

无论是 文件名 、文件夹 、组件名 还是 类名 ，都必须确保英文拼写正确。

你可以英语不好，但不能出现拼写错误。

错误示例：

• ❌ data.ts（本意为日期，应为 date.ts）
• ❌ devise.ts（本意为设备，应为 device.ts）

拼写错误不仅影响可读性，还可能造成引用错误或他人理解偏差。

1.1.2 避免使用含糊或不明确的命名

命名应语义清晰、表达准确，避免使用模糊、过于笼统的词汇。

不推荐：

• info、data、handle、doSomething、temp

推荐：

• userInfo、orderData、handleSubmit、fetchUserList

清晰的命名能让他人快速理解逻辑，也方便后期维护和扩展。

每次提交代码前，建议快速检查一下命名是否合理，避免留下低级错误。

1.2 工具类文件命名后缀

tools、utils、helper 等后缀常用于区分不同类型的工具类文件。

类型	适用场景	示例
Tools	功能分类明确、封装性强的工具函数	stringTools.ts / dateTools.ts
Utils	通用型工具函数集合	stringUtils.ts / localstorageUtils.ts
Helper	辅助逻辑或中间处理函数	stringHelper.ts / dateHelper.ts

1.3 功能类文件命名后缀

用于表达业务逻辑的"功能性"模块，例如处理器、管理器、适配器等。

类型	说明	示例
Handler	用于事件或逻辑处理类函数，如监听、回调等	eventBusHandler.ts / msgHandler.ts
Manager	用于管理类逻辑，如状态或队列管理	fileManager.ts / statusManager.ts
Adapter	用于适配器模式或兼容性转换	fileAdapter.ts / statusAdapter.ts
Controller	控制类逻辑，负责协调模块或接口	fileController.ts / statusController.ts

二、文件引用

2.1 设置别名 @

我们一般会在 vite.config.ts 中给 src 根目录设置别名 @。

1. 引用文件时，可以直接使用 @ 开头的绝对路径，而不必使用繁琐的相对路径。

2. 除了 src 根目录，还可以给其他常用文件夹设置别名，如公共组件库或工具库：

3. 1. @components → src/components（可选）
   2. @utils → src/utils（可选）

2.2 相对路径 vs 相对路径

1. 相对路径 ：
   适合同一个功能模块或文件夹下的引用，避免使用过深的相对路径（如 ../../../）。
   如果超过二层相对路径，建议改用别名。
2. 绝对路径 ：
   对于重要且不会轻易移动的核心功能模块，使用 @ 开头的绝对路径更清晰可靠。

三、VUE 文件模版的开发建议

3.1 最小标签化原则

在一个模块中，如果只包含一句文案，只需要使用一个容器标签（如 div）即可，不要增加冗余的子标签。

只有在样式或语义上有特殊需求时，才需要额外添加标签。比如下面的例子，你根本需要增加 span 标签，除非你的样式有特殊要求。

<template>
    <div>
        <!-- 不推荐的写法 -->
        <div class="container">
                <span>你好</span>
        </div>

        <!-- 推荐的写法 -->
        <div class="container">你好</div>
    </div>
</template>

3.2 每个重要的 DOM 都增加类名

在开发中，哪些 DOM 是"重要的"，需要根据实际情况评估。一般来说：

1. 组件最外层 DOM：通常是整个组件的容器，需要添加类名以便统一样式或定位。
2. 功能模块的外层 DOM：例如按钮、表单区块等，也属于重要 DOM，应增加类名以便样式和逻辑操作。
3. 影响布局的 DOM：任何会影响页面布局的元素也应视为重要 DOM。

比如下面的列子：

• div.container：组件最外层容器，是重要 DOM，需要类名。
• div.btn：按钮是独立的功能模块，也属于重要 DOM，需要类名。
• img 标签：只是按钮内部的图标，且是唯一图标，不必单独增加类名，可以使用 CSS 选择器 btn > img 来设置样式。

<template>
    <div class="container">
        <div class="btn">
            <img />
            确定
        </div>
    </div>
</template>

四、组件库的使用

很多人经常说"不要造轮子"，但如果什么都依赖组件库，也会降低开发效率、限制灵活性。因此，我们需要根据实际业务场景，灵活判断是否使用组件库。

4.1 建议使用组件库的场景

4.1.1 含有层级或定位逻辑的组件

尤其是那些结构复杂、涉及定位与层级控制的组件，例如 Dialog、Toast、Popover、Tooltip、Select 等。

这些组件通常包含 位置计算、滚动监听、遮罩层、z-index 管理 等复杂逻辑，自己从零实现不仅耗时，还容易出现兼容性问题。

这类组件一定要用组件库，费力不讨好地自己造轮子毫无必要。

4.1.2 大规模重复的功能模块

当项目中存在大量相似的功能模块时，组件库可以显著提升开发效率。

例如表单场景：如果页面中有两个以上输入框，或者涉及表单验证等逻辑，推荐使用组件库。以 Element Plus 为例，el-form 内置了完善的验证机制和交互体验，非常省心。

例如登录表单，通常包含"手机号"和"验证码"两个输入框，还要校验格式、空值等，这类场景就非常适合直接用组件库实现。

4.2 不建议使用组件库的场景

虽然组件库能大大提高开发效率，但在一些场景中使用反而会拖慢进度、增加维护成本。以下是几个不建议使用组件库的典型情况。

4.2.1 功能简单但样式复杂的场景

以 Element Plus 的 Image 组件为例，它的图片预览功能确实很方便，一个 el-image 就能实现自适应和点击放大预览。

但如果你的业务场景中并不需要点击预览，而是希望在图片周围加入各种装饰、标签或特殊样式，那么此时使用原生 <img> 标签更灵活也更轻量。

换句话说，当样式比功能更重要时，组件库往往会成为束缚。此时直接使用原生标签 + 自定义样式，不仅可控性更强，还能更好地满足设计需求。

4.2.2 功能极其简单的场景

一些非常简单的功能没必要使用组件库。例如：

• 分割线完全可以用 <hr> 或 <div> 实现，比用组件库更高效；
• 页面上只有一个输入框时，也没必要用 el-input。

五、CSS 开发建议

5.1 使用小写与短横线分割

CSS 类名区分大小写，因此建议统一使用小写，并通过短横线（-）分割单词，而不要使用驼峰命名或下划线。

5.2 类名应与业务逻辑关联且保持唯一

5.2.1 避免命名困难

如果类名与业务逻辑无关，比如取名为 new-dialog，当你在多个地方复用这个组件时，很快就会陷入命名困境。你总不能依次命名为 new2-dialog、new3-dialog 吧？

而且在调试时，通过开发者工具选中该元素时，不看代码根本无法判断它属于哪个页面的弹框。

与其这样，不如直接根据业务逻辑命名：

• 登录模块使用 user-login-dialog-wrapper
• 设置模块使用 setting-dialog-wrapper
• 订单列表模块使用 order-list-dialog-wrapper

通常项目中的业务逻辑不会完全重复，因此这种命名方式既直观又无需反复思考，能大幅提升开发与定位效率。

5.2.2 避免重复类名

即便是同一业务逻辑下的弹框类名，也应避免重复。例如，登录模块可能有两个弹框：一个用于输入手机号，另一个用于输入验证码。如果都命名为 user-login-dialog-wrapper，就会在项目中搜索时出现大量重复结果，难以判断需要修改哪一个。

正确做法是根据功能细化命名，如：

• user-login-phone-dialog-wrapper
• user-login-verify-code-dialog-wrapper

当然，并非所有类名都必须唯一。例如，小型文案可以统一使用 text，按钮可以使用 btn。关键是要区分"大功能模块的类名"，如弹框最外层容器或布局元素，保证这些类名在项目中唯一。

5.3 优先书写布局属性，再书写样式属性

这里所说的布局属性通常分为两类：

1. 元素自身在父容器中的布局 ，主要由 position、margin、width、height 等属性控制；
2. 元素内部子元素的布局 ，通常由 display、padding 等属性决定。书写顺序建议先写第一类，再写第二类。总的原则是：先确定元素的位置，再定义其他样式。

样式属性主要指颜色、字体、行高等，这类属性顺序没有严格要求，但同类型的属性最好放在一起，例如：

• font-size 和 line-height 放在一起
• background-size 和 background-position 放在一起

总结起来，CSS 样式从上到下的推荐顺序如下：

1. 定位（position）
2. 外边距（margin）
3. 尺寸（width / height）
4. 布局（display）
5. 内边距（padding）
6. 字体与颜色（font-* / color）
7. 背景相关（background-*）
8. 其他属性

不必严格按照此顺序书写，关键是大模块上先写布局属性，再写样式属性即可。

5.4 最大简化原则

最大简化原则指尽量合并可合并的属性，以减少冗余代码。例如，如果一个 div 同时有两侧的 margin，最好合并起来写一行。

同样的原则也适用于 padding、border、background 等属性，尽可能使用简写形式，提高代码简洁性和可维护性。

5.5 最小改动原则

最小改动原则指在 :hover 等状态下尽量只修改必要的样式。例如，一个 div 默认有边框，当需要在 hover 时改变颜色，只修改必要的颜色属性即可。

这样做的好处是，如果以后需要修改边框宽度，只需修改一处默认样式，而无需再去改 hover 中的样式，提高维护性。

六、commit 规范

常用的提交文案：

• feature（新功能），如 feat: 登录功能
• fixbug（修复 bug），如 fix: 用户列表展示问题
• style（紧急修复），如 style: 输入框样式调整