前端规范

仰望星空 2023/12/8 规范

约定优于配置，这其实是产品设计的思路，减少认知量，更易理解、操作、美观。大部分按照约定的来，只有少部分才需要另外的方式。

规范、规则、约定可以理解为约束，有约束才有信息，系统其实是人的决定构成的。每做一个决定就是产生一些约束，你又得评估其逻辑闭包、不确定性、影响范围等，以达到最后的目的是有利于系统发展的。

说白了制定一个好的规范有利于系统发展，但无论怎样都要清楚目的，这样你才能合道。

# Vue 文件规范

单文件名称

单文件组件的文件名应该要么始终是单词大写开头 (PascalCase)，要么始终是横线连接 (kebab-case)。

// bad
mycomponent.vue
myComponent.vue
// good
my-component.vue
MyComponent.vue

1
2
3
4
5
6

紧密耦合的组件名

和父组件紧密耦合的子组件应该以父组件名作为前缀命名。

// bad
components/
|- TodoList.vue
|- TodoItem.vue
└─ TodoButton.vue
// good
components/
|- TodoList.vue
|- TodoListItem.vue
└─ TodoListItemButton.vue

1
2
3
4
5
6
7
8
9
10

自闭合组件

在单文件组件中没有内容的组件应该是自闭合的。

export default {
  data() {
    return {
      foo: 'bar',
    };
  },
};

1
2
3
4
5
6
7

props顺序

标签的 Props 应该有统一的顺序，依次为指令、属性和事件。

<my-component
  v-if="if"
  v-show="show"
  v-model="value"
  ref="ref"
  :key="key"
  :text="text"
  @input="onInput"
  @change="onChange"
/>

1
2
3
4
5
6
7
8
9
10

组件选项的顺序

组件选项应该有统一的顺序。

export default {
  name: '',
  mixins: [],
  components: {},
  props: {},
  data() {},
  computed: {},
  watch: {},
  created() {},
  mounted() {},
  destroyed() {},
  methods: {},
};

1
2
3
4
5
6
7
8
9
10
11
12
13

单文件组件顶级标签的顺序

单文件组件应该总是让顶级标签的顺序保持一致。

<template>
  ...
</template>
<script>
  /* ... */
</script>
<style>
  /* ... */
</style>

1
2
3
4
5
6
7
8
9

# CSS 规范

.declaration-order {
  /* 定位 */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* 盒模型 */
  display: block;
  float: right;
  width: 100px;
  height: 100px;
  border: 1px solid #e5e5e5;

  /* 排版 */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* 外观 */
  background-color: #f5f5f5;

  /* 其他 */
  opacity: 1;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# Git 规范

# Git 提交规范

基本格式

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]

1
2
3
4
5

type

feat: 新增功能
fix: 修复 bug
docs: 文档相关的改动
style: 对代码的格式化改动，代码逻辑并未产生任何变化(例如代码缩进，分号的移除和添加)
test: 新增或修改测试用例
refactor: 重构代码或其他优化举措
chore: 项目工程方面的改动，代码逻辑并未产生任何变化
revert: 恢复之前的提交
wip: work in progress 当一天工作完,代码没有完全写完，但你想要commit已经写的代码会用到

scope(可选)

chore(babel-helper-plugin-utils): add npmignore

footer(可选)

footer 通常用于代码评审过程记录、作者签名等。例如：

Reported-by: User1 <user1@example.com>
Helped-by: User2 <user2@example.com>
Reviewed-by: User3 <user3@example.com>

1
2
3

# Git 分支规范

新建分支的命名格式为：{type}-{issue id}-the-thing-you-do

比如以下格式都满足规范：

feat-ssr-prefetch：新增 ssr prefetch 功能
fix-1379-component-insert-order：修复 issue 1379 中提到的组件插入顺序 bug
revert-14218-memory-leak-on-unmount：回退版本解决 issue 14218 提到的组件卸载时内存泄露的问题

# Git tag 命名规范

命名格式为 v{semver}，semver 是遵循 semantic version (opens new window) 的版本号，例如 v1.2.3。

git tag -a v1.2.3 -m "发布经销商管理模块"

# 技巧

又一次领悟到小即是好的道理。本来是想着为了git commit记录少而把很多次修改amend到一个commit记录。一开始没出现问题，过了一个多星期才发现了一个bug，不能一下子就解决掉。就想到了用那控制变量法对commit记录回滚来定位bug在具体的版本。终于定位到了这个commit，结果呢，这个commit包括了几十个文件，只能回想具体那些文件的行是可能导致bug，然后手动的注释掉看效果。就这个过程来回搞了十几遍看效果，才找到一个导致bug的代码。整个过程耗了将近三个多钟，真是吃惊！生命被这个无意义的bug浪费呀。

如果commit是少量文件并且单独的功能呢，那么我就可以对这一个个commit进行回滚测试了，这样子很明确并且效率高不少，估计半个钟左右就定位出来了。