不完全前端规范指南

合理的规范，能在多人开发的时候，起到意想不到的效果。

0. 前文

文章内容包括但不限于：本地开发环境、代码格式化、Vue 风格指南、Git 提交基本规范指南、新人上手指南、注释...

文章目标：社区主流 + 适合中小公司

1. 本地开发环境

IDE

默认情况下，我们采用 Visual Studio Code 编辑器编写前端代码。如果你是开发 Vue2 项目，那么你最少需要在 VSCode 中安装并开启这些插件：

Vetur：Vue2 官方插件
Eslint：代码校验
Prettier：代码格式化

当然 Eslint 和 Prettier 这两个插件最好是配合项目中的对应依赖进行使用，假如你的项目没有这两个依赖（那建议你学会配置，或者至少找一个配置好这两个依赖的模板项目进行开发，例如：V3 Admin Vite）。

对于配置好的项目来说，你在 Ctrl + S 保存代码的时候，Eslint 与 Prettier 可能就已经开始工作了，将你的代码自动进行格式化。

假如你的项目是一个没有配置好的项目，那么至少建议你右键鼠标，选择 Prettier 插件进行格式化。

假如你的项目只配置了其中一个插件，例如只配置了 Eslint，那么建议你只开启你的 Eslint 插件，并且在保存代码时，选择采用 Eslint 来进行格式化（是的，Eslint 也具备一部分格式化能力）。

如果你是 Vue3 项目，那么你最少需要安装并开启这些插件：

Volar：Vue3 官方插件（注意不要和 Vetur 同时开启，避免插件冲突）
Eslint：代码校验
Prettier：代码格式化

Node

Node 版本是要根据具体项目来安装的，但是当前时间的话（2023年10月31日），一般安装 16+ 版本的就可以通用了

2. 代码格式化

Tab 键一般情况下设置为两个空格或四个空格大小
项目有配置 Prettier 时，一般采用 Prettier 插件格式化
项目没有配置 Prettier 时，但配置了 Eslint 时，一般采用 Eslint 插件格式化
项目 Prettier 和 Eslint 都没有配置时，一般采用 Prettier 插件进行格式化

3. Vue 风格指南

必要的（必须严格执行）

Prop 的定义应该尽量详细

在你提交的代码中，prop 的定义应该尽量详细，至少需要指定其类型。

为 v-for 设置 key

在组件上总是必须用 key 配合 v-for，以便维护内部组件及其子树的状态。

v-for 时将 index 当做 key

在对 v-for 循环出来的列表有删除操作的时候，切记不要轻易使用 index 当做 key！可以像上图中那样，用唯一的 id 当做 key。

至于为什么，请仔细阅读这篇文章：Vue2.0 v-for 中 :key 到底有什么用？ - 知乎

避免 v-if 和 v-for 用在一起

一般在两种常见的情况下会倾向于这样做：

为了过滤一个列表中的项目 (比如 v-for="user in users" v-if="user.isActive")。在这种情形下，请将 users 替换为一个计算属性 (比如 activeUsers)，让其返回过滤后的列表。
为了避免渲染本应该被隐藏的列表 (比如 v-for="user in users" v-if="shouldShowUsers")。这种情形下，请将 v-if 移动至容器元素上 (比如 ul、ol)。

4. Git 提交基本规范指南

commit 规范

前端这边默认采用前端开源社区主流的 commit 规范：

reference vue specification (Angular)

feat: Add new features
fix: Fix the problem/BUG
style: The code style is related and does not affect the running result
perf: Optimization/performance improvement
refactor: Refactor
revert: Undo edit
test: Test related
docs: Documentation/notes
chore: Dependency update/scaffolding configuration modification etc.
workflow: Workflow improvements
ci: Continuous integration
types: Type definition file changes
wip: In development

简单翻译翻译就是：

feat: 增加新的业务功能
fix: 修复业务问题/BUG
perf: 优化性能
style: 更改代码风格, 不影响运行结果
refactor: 重构代码
revert: 撤销更改
test: 测试相关, 不涉及业务代码的更改
docs: 文档和注释相关
chore: 更新依赖/修改脚手架配置等琐事
workflow: 工作流改进
ci: 持续集成相关
types: 类型定义文件更改
wip: 开发中

实际操作中，就会呈现下图这样统一规范且语义化的 commit 记录：

当然，这里的话只是规范你的描述信息。至于何时提交一个 commit 的话，我们简单采用一个原则：完成一件事情，就提交一次 commit。而不是等到你写完一整天的代码后，才在下班前只提交一次。

代码冲突

多人合作开发项目是，经常会遇到代码冲突的情况。这种时候不要惊慌，如果你不熟悉解决冲突的流程，那么你应该在发生冲突时，尽快备份你的本地代码备用。
我们提交代码的基本规则是：先 pull，再 push，并始终保持本地代码和远程代码同步。 这能大大降低冲突的概率！简单解释一下为什么：代码冲突是指我们和别人同时修改了一处相同的代码。git 这时候不知道并该采用谁的代码，就会抛出冲突，让程序员自己解决冲突（就是让你从你和你同事的代码里选择一份）。如果你始终遵循先 pull 再 push 的原则，那么在你刚到公司，你应该自觉 pull 同步一下代码，写代码前也要 pull，提交代码前也要 pull，最后才是 push。这能尽可能的保证你是在最新的代码版本上进行编写新的代码，而不是在老版本的代码进行编写新代码，可以有效的避免你去修改了别人的老代码（实际上你的同事早就更新了这段代码），从而导致冲突。
如果你必须要去修改同事的代码，或者要去修改公共模块的代码。你其实可以给你的同事打个招呼，问问他本地有没有要推送的代码。可以让他先推送后，你在去基于最新的代码修改。修改完成后，也可以提醒一下你的同事 pull 一下你的刚才提交的代码。
如果你是第一次遇见代码冲突，不要紧张 。你可以自行上网搜索试着解决它，或者第一时间找一个同事来指导你。假如代码比较重要，切记备份代码，并且不要使用强制推送去污染远程的代码。

5. 新人上手指南

确保熟悉以下几点后，就可以尝试上手一些真实的项目开发了：

熟悉常用 Git 命令（clone/add/commit/pull/push），然后熟悉 Git 可视化软件，比如 Sourcetree
理解 Git 中 "始终先 pull 再 push" 的规范，防止多人合作时提交代码冲突
熟悉一个开源的后台管理模板，比如 v3-admin-vite（vue3）或 vue-admin-template（vue2）或若依（vue2）
重点熟悉项目的登录、鉴权、权限三个模块。也顺便去看看它对表格的 CRUD
学会配置本地开发环境（vscode、node 16+、pnpm 8+、yarn 1.22.x、eslint 插件、prettier 插件、vue3 的话是两款 volar 插件、vue2 的话是 vetur 插件）
vscode 配置为保存代码时，自动 eslint 校验代码
注意有些项目是用的 yarn，有些是 pnpm，甚至有些是 npm（可以通过 lock 文件来识别、或者看该项目文档有没有提示），根据具体的项目选择不同的工具，不能在同一个项目中混用（出问题了后可以删除 node_models、甚至删除 lock 文件，然后重新依赖）
不能用 npm 命令来安装 yarn，要去 yarn 官网下载安装包

6. 注释

基本的注释：至少得告诉别人，该函数或者该变量是做什么用的。
优秀的注释：好的代码注释是用来告诉别人你为什么写这样的代码，而不是告诉别人你的代码做了什么
优秀的命名：如果你的变量命名风格统一且友好，那么你其实就不用写太多基本的注释 ，因为别人看见变量名就知道你要做什么。这时候，你可以大胆的去写优秀的注释。

7. 单元测试

单元测试框架 Vitest 上手指南