前端开发规范相关（先行版）

一、项目结构规范

项目结构图

Vue

React

demo项目地址

https://gitlab.lanhanba.com/fe/lhb-template

文件命名规范

1、页面命名规范：小写单词命名

如  /pages/home/index/entry.vue   
   /pages/home/list/entry.tsx

2、/common/components公共组件命名规范除了 index.vue以外，所有的必须是驼峰式写法，首字母大写

正常情况下： 
  /common/components/Table/ShowMore.vue
  /common/components/Table/Opreate.tsx

仅index.vue的情况下
  /common/components/Table/index.vue
  /common/components/Table/index.tsx

3、pages/**/components 页面内业务组件命名规范除了 index.vue以外，所有的vue文件包括组件文件夹都必须是驼峰式写法，首字母大写

正常情况下： 
  /components/List.vue
  /components/Search.tsx

拥有更深层组件的情况下：
 i.
  /components/Info/index.vue
  /components/Info/components/UserHeader.vue
  /components/Info/components/FooterBtns.vue
 ii.
  /components/Info.tsx
  /components/InfoUserHeader.tsx
  /components/InfoFooterBtns.tsx

二、git分支规范

分支拉取图示

三、git提交规范

目前已经在新项目及模板上添加、如果不规范提交commit是无法提交代码的

用于说明 commit 的类别，只允许使用下面7个标识。

feat：新功能（feature）

fix：修补bug

docs：文档（documentation）

style： 格式（不影响代码运行的变动）

refactor：重构（即不是新增功能，也不是修改bug的代码变动）

test：增加测试

chore：构建过程或辅助工具的变动

示例

git add .
git commit -am "添加了一个XX功能" // 这样就报错了，无法提交

git commit -am "feat: 添加了一个XX功能" // 可以正常提交
git push

协作开发流程规范

具体的操作流程参考如下:

新建分支之前，一定要先pull最新的代码，然后再创建分支
commit之前，要先将代码add到暂存区，以免代码没有被提交
commit之后，要先pull一下当前分支的最新代码(如果多个人公用一个分支开发)
如果要将当前分支合并到分支B，先要切到分支B，pull最新的代码再合并
合并分支如果有冲突，必须先再本地解决完冲突，再add和commit代码
最后再进行push 总之，不管是提交代码还是合并代码，push之前，都要先pull一下，确保当前分支是最新的代码。

参考

git命名规范和协作开发流程

四、package引用规范

版本写死，不再使用 "^"和"~" 等符号

五、组件化规范

1、细分程度

  普通组件要求=》 200行以内
  表单相关组件=》 400行以内

2、底层组件规范

尽量解耦业务，通过二级封装，如继承、多态等 扩展。
不允许一个底层组件杂糅业务逻辑，大量入参配置

六、编码规范

1、html命名规范

1. 
    i.普通标签必须全部小写
        good:
          <div>
          ...
          </div>

        bad:
          <DIV>
          ...
          </DIV>
    ii.组件标签必须大驼峰
       good:
         <ButtonGroup>
         ...
         </ButtonGroup>

       bad:
         <button-group>
         ...
         </button-group>

2. 属性值使用双引号
good:
  <div class="example">
  ...
  </div>

bad:
  <div class='example'>
  ...
  </div>

3. 注意自闭和标签的使用
如：
  <meta>标签:设置页面元信息的 
  <base>:设置网页所有链接的相对目录(如根目录)的 
  <br>:换行 
  <hr>:水平线 
  <img>:图像 
  <input>:表单元素 
  <col>:在表格table中定义一个或多个列的属性 
  <frame>:定义框架的一个窗口（已遗弃） 
  <link>:定义文档与外部资源的关系的链接 
  <area>: 标签定义图像映射内部的区域（图像映射指的是带有可点击区域的图像）。 
  <param>:元素允许您为插入 XHTML 文档的对象规定 run-time 设置，也就是说，此标签可为包含它的 
  <object> 或者<applet> 标签提供参数。 
  <embed>: HTML5 中新增的,标签定义了一个容器，用来嵌入外部应用或者互动程序（插件）。 
  <keygen>:该对象提供了一个安全的方式来验证用户。 
  <source>: 标签为媒体元素（比如 和 ）定义媒体资源。

4. html (vue templete)
<template>
  <div>
    <!-- 推荐 -->
      <!-- 多行属性，注意属性的顺序(三个以内可以一行，超过三个时每个独占一行)
        1.条件判断 
        2.参数 -> 动态参数
        3. class
        4.绑定的方法
      -->
      <ElDatePicker
        v-if="humanFlowForm.granularity === 4"
        v-model="humanFlowForm.start"
        type="year"
        value-format="yyyy-MM-dd"
        placeholder="开始时间"
        :picker-options="dateOptions"
        class="picker"
        @change="exportDateChange">
      </ElDatePicker>
      <!-- 单行属性 -->
      <div ref="something">
      </div>
    
    <!-- 强烈不推荐 -->
    <ElDatePicker v-if="humanFlowForm.granularity === 4" v-model="humanFlowForm.start" type="year" value-format="yyyy-MM-dd" placeholder="开始时间" style="width: 100%" :picker-options="dateOptions" @change="exportDateChange"></ElDatePicker>
  </div>
</template>

2、css命名规范

1. 命名推荐皆为小写
good:
  .section-box {
    
  }

bad: 
  .sectionBox {
    
  }

2. 长名称或词组可以使用中横线来为选择器命名
.example-name

3. 不要随意使用id选择器
    情况特殊时请注意格式
        good:
            #special-confirm {
            
            }

        bad: 
            #specialConfirm {
            
            }

4. 语义明确的命名，尽量少用简写，除非大家达成了共识
  good: 
      .btn {}
  bad: 
      .bn {}
5. class的复用、scss的使用（该项作为了解，不作为规范）
   
      <div class="section-con ft-14 mt-10 c-333">
        <div class=""></div>
      </div>
      <div class="section-con ft-12 c-999 custom">
       <div class=""></div>
      </div>

      @mixin wh($width, $height) {
        width: $width;
        height: $height
      }

      .ft-12 {
        font-size: 12px
      }

      .ft-14 {
        font-size: 14px
      }

      .c-333 {
        color: #333
      }
      .section-con {
        @include wh(100px, 200px);
        ...
        &.custom {
         height: 500px;
        }
      }

  原写法:
     <div class="section-1">
      <div class=""></div>
     </div>
     <div class="section-2">
      <div class=""></div>
     </div>

    .section-1 {
      width: 100px;
      height: 200px;
      font-size: 14px;
      margin-top: 10px;
      color: #333
   }

   .section-2 {
     width: 100px;
     height: 500px;
     font-size: 14px;
     margin-top: 10px;
     color: #333
   }

3、js命名规范

1. 变量名、函数名、方法名：小驼峰式的命名方法
const exampleName = `name`;
function exampleFun() {}
...

2. 类、构造函数：大驼峰式的命名方法
class Example {
  constructor(name) {
   ...
  }
}

3. 常量：全部大写，以_连接
const EXAMPLE_CONST = ``;

4. 文件命名: 全部小写，以-连接
example-test.js

5. 注释
单行注释 // 
多行注释 /* */ 

6. 组件化和抽象化
 当同样的方法在多个组件内使用时，考虑使用vue的mixns（该方法依赖于某些特定组件时）或者单独抽象一个方法放到项目中的公共方法文件中
 当类似的组件在多个页面使用时，抽象为一个公共组件（业务层面的），通过不同的入参来具体使用


7. 慎用vuex（考虑复杂度和可维护性）

七、lint规范

.eslintrc.js文件 针对js和ts的一些校验。

八、codereview规范

流程和规则

采用 Merge Request 方式来做Code Review。

Merge Request 的说明

任务完成才能提交MR
MR提交之后只允许针对Review发现问题再次提交代码，除非有充足的理由，严禁在同一个MR中再次提交其它任务的代码
MR发起前应该提前与目标审核者确认，在对方时间允许的前提下进行
由于目前项目现状，在紧急业务发布、时间紧张的时候，可以暂时跳过或者简化codereview这环

Code Review Checklist

Code Review主要检查代码中是否存在以下方面问题：代码的一致性、编码风格、代码的安全问题、代码冗余、是否正确设计以满足需求（功能、性能）等等

完整性检查（暂时不做code review要求）
- 代码是否完全实现了原型文档、UI设计稿中提出的功能需求
- 代码是否已按照原型文档、UI设计稿进行了自测
- 代码中是否存在任何没有定义或没有引用到的变量、常数、方法、文件
一致性检查（暂时不对code review进行严格要求）
- 代码的逻辑是否符合设计文档
- 代码中使用的格式、符号、结构等风格是否保持一致
- 上传前是否已经通过了代码风格检测工具的检测
正确性检查
- 代码是否符合制定的标准
- 所有的变量都被正确定义和使用
- 所有的注释都是准确的
- 所有的函数调用都使用了正确的参数个数
可修改性检查
- 代码涉及到的常量是否易于修改(如使用配置、定义为类常量、使用专门的常量类等)
- 代码中是否包含了交叉说明或数据字典，以描述程序是如何对变量和常量进行访问的
- 代码是否只有一个出口和一个入口（严重的异常处理除外）
可预测性检查
- 代码所用的开发语言是否具有定义良好的语法和语义
- 是否代码避免了依赖于开发语言缺省提供的功能
- 代码是否无意中陷入了死循环
- 代码是否是否避免了无穷递归
健壮性检查
- 异常处理
- 代码是否采取措施避免运行时错误（如空数据、被零除、堆栈溢出等）
结构性检查
- 每个功能是否都作为一个组件存在
- 是否合理的设计文件路径
可理解性检查
- 注释是否足够清晰的描述每个函数、变量
- 是否使用到不明确或不必要的复杂代码，它们是否被清楚的注释
- 使用一些统一的格式化技巧（如缩进、空白等）用来增强代码的清晰度
- 是否在定义命名规则时采用了便于记忆，反映类型等方法，严禁通过数字进行命名，如 fn1 fn2
- 每个变量都定义了合法的取值范围
- 代码中的算法是否符合开发文档中描述的数学模型
可验证性检查
- 代码中的实现技术是否便于测试
可重用性
- 考虑可复用的服务，功能和组件
- 考虑通用函数和类
可扩展性
- 轻松添加功能，对现有代码进行最小的更改，一个组件可以被更好的组件替换
- 安全性
性能
- 使用合适的数据类型
- 懒加载，异步和并行处理
- 缓存

代码检查包括不局限于上述清单，还包括其他规范。

Code Review的步骤

代码编写者进行功能开发
编写者提交分支到远端
编写者发起 Merge Request
代码编写者和代码审核者坐在一起，由代码编写者按照功能模块依次讲解自己负责的代码和相关逻辑
审核者在此过程中可以随时提出自己的疑问，同时积极发现隐藏的bug，并在对应的代码段落上评论
代码讲解完毕后，代码审核者再对代码审核一遍
如果代码没有任何问题，合并请求
如果代码不通过，进行评论并关闭请求，通知编写者修改
编写者根据修改意见，修改好代码，并在评论处标记已解决，有不清楚的地方可积极向代码审核者提出
编写者修改完毕后，重新打开被关闭的请求，从第4步开始继续执行
如果有部分需求在不影响正常功能使用的前提下（如些许性能问题）可以延期处理，那么在问题代码处注明TODO后允许提交

流程图如下：

生成 Code Review 报告

当某一次 codereview 存在值得他人学习的部分，编写者可以总结出 codereview 报告，分享到前端群中
如果审核者觉得这次评审中有比较好的编码技巧，也可以总结出 codereview 报告
延期处理的问题需要生成 codereview 报告，分享到前端群中

codereview报告模板：

codereview报告.xlsx

codereview事项记录

http://confluence.lanhanba.com:8090/display/frontEnd/2020

Edited Jun 05, 2023 by JayChen

GitLab