Web前端开发规范

开发规范

环境配置

• node 版本：采用v14.x.x版本或最新稳定版本
• npm 版本：采用最新版本
• vue-cli 版本：采用最新稳定版本
• vue 版本： 采用3.x.x版本

项目配置

• 项目模板使用模板项目 dfcg-basic-front 生成

editorconfig

.editorconfig 文件有助于为不同 IDE 编辑器上处理同一项目的多个开发人员维护一致的编码风格。

# http://editorconfig.org
# 告诉EditorConfig插件，这是根文件，不用继续往上查找
root = true

# 匹配全部文件
[*]
# 设置字符集
charset = utf-8
# 缩进风格，可选space、tab
indent_style = tab
# 缩进的空格数
indent_size = 2
# 结尾换行符，可选lf、cr、crlf
end_of_line = lf
# 在文件结尾插入新行
insert_final_newline = true
# 删除一行中的前后空格
trim_trailing_whitespace = true

# 匹配md结尾的文件
[*.md]
insert_final_newline = false
trim_trailing_whitespace = false

UI框架选择

• PC端Vue项目UI框架优先选择：Element UI
• 移动端Vue项目UI框架：Vant-ui

编程规范

变量方法及文件名定义

• 定义变量时，常量使用const定义，全大写下划线格式命名。

• 变量定义使用小驼峰命名方式根据变量用途语义化命名。

• 方法命名同变量命名方式采用小驼峰根据用途命名。

• 文件命名同上小驼峰命名。

  • 页面xx.vue文件根据页面用途命名，文件放置该页面对应模块文件夹下。
  • 页面xx.scss文件同对应页面名，放于该页面对应模块样式文件夹下。
  • xx.js文件，同上根据用途命名，

# 文件命名示例
|— userCenter
	|— userCenter.vue
	|— userCenter.js
	|— userCenter.scss

// 常量
const USER_NAME = 'XiaoChen';
// 变量
let userName = 'XiaoChen';
// 方法
let changeUserName = (userName) => {};

页面排版规范

• 文本输入框需设置默认提示语，文本框长度若无UI情况下限制不超过300px宽度。

• 下拉选择框（包含下拉选框、联级选框）需设置默认提示语，长度若无UI情况下限制不超过300px宽度。

• 搜索表单：置于页面内容部分上方，采用inline模式el-form排版，此时输入框、下拉框长度无需设置。

• 新增/编辑表单：根据复杂程度及对应需求选择使用弹框形式或新页面形式展示，采用竖排样式排版，需设置文本框及下拉框长度，并统一设置label长度，对于表单必填项需进行参数校验。

  参数校验时如使用正则校验参数，如手机号，需考虑全号段情况，也可只校验长度。

• 列表详情页面：视复杂程度及对应需求要求选择使用弹框形式或新页面形式展示，如无特殊情况可与新增/编辑页面重用。

• 在排版页面时还需考虑数据空态页面展示。

样式规范

• 选用 sass 或 less。
• 公共样式文件内除特殊情况仅可进行新增操作，不可对原样式值进行修改。
• 单个组件样式可直接写到组件下 style 标签下，为了防止样式污染，需添加 scoped 属性，也可以通过设置作用域来防止样式污染，写样式时需使用用类选择器，尽量避免使用元素选择器。

页面编码规范

• 组件名称必须以大驼峰法命名
• 变量及方法命名需符合规范及语义化定义
• 对于页面初始进入需请求接口等操作是应放置于生命周期 mounted 函数内进行
• 代码中不可出现默认具体值出现，默认值一律为空字符串、空对象、空数组等，需要设置默认值时可另开方法操作，提测时要关闭该方法调用；本地存储相关默认值在 Chrome 的开发工具中 Application 中对应存储类型内配置默认值
• 计算函数及侦听器需注意使用场景，computed 计算属性仅可用于简单运算，涉及大量运算或存在异步操作时需改用 watch
• 开发期所有 console 应添加标识位，打包上线时要关闭所有 console
• 对于 H5 页面即需要在移动端展示的页面项目需添加 vconsole 依赖，便于调试，开发期可开启调试展示，打包上线时要关闭展示
• 提交类型的按钮需要设置 loading 展示
• 对于短时间多次触发接口调用的方法需要添加事件防抖机制

接口调用规范

• 接口地址需统一于/src/api/requestUrl.js 文件中依据模块进行分组定义

  // 命名格式： 接口名+请求方式——小驼峰 (restful接口时仅接口名定义即可)
  // ****** 授权模块 ****** //
  const AUTH_API = {
    loginPost: '/auth/login',
    registerPost: '/auth/register',
    codeGet: '/auth/code'，
  }
  // ****** 授权模块 ****** //
  // ****** 用户模块 ****** //
  const USER_API = {
    listGet: '/user/list',
    userUpdatePut: '/user/userUpdate'，
    user: '/user', // restful 风格，合并 userGet/userPost/userPut/userDelete
  }
  // ****** 用户模块 ****** //
  export {
  	AUTH_API,
    USER_API,
  }

• 接口请求方法需于 /src/api 目录下依据模块新建对应文件内进行定义

  |- src
  	|- api
  		|- requestUrl.js
  		|- auth.js
  		|- user.js

  // auth.js
  import request from '@/utils/request';
  import {AUTH_API} from '@/api/requestUrl';
  /**
   * 登录
   * @param username {String}
   * @param password {String}
   * @param code {String}
   * @param uuid {String}
   * @returns {Promise<any>}
   */
  export function login(username, password, code, uuid) {
    return request({
      url: AUTH_API.loginPost,
      headers: {
        isToken: false
      },
      method: 'post',
      data: { username, password, code, uuid }
    })
  }

• 接口调用时需添加用户加载提示，适当添加loading展示，分页加载时：

  • 滑动加载，加载提示可展示在最后一项后添加。
  • 分页器分页加载时，加载提示可采用全屏loading形式展示。

  操作类接口调用时，在对应操作按钮上添加loading展示

  如对应操作按钮在列表中则采用全局loading形式展示

• 接口调用结果视情况提示用户：

  • 加载成功：
    • 加载数据时可直接展示数据，无需提示
    • 操作类接口调用成功时，添加操作成功提示弹框，可描述为对应操作，如下架成功。
  • 加载失败：若接口有返回错误信息时，将后台返回结果提示给用户；若无返回错误信息时提示用户服务异常.

• 接口文件定义：

  • 接口地址统一定义在接口配置文件中，使用常量命名定义；

  • 接口调用统一封装至对应模块xx.js文件中，如user模块独立定义为user.js文件，其内包含增删改查等对应操作的接口调用封装方法，

    该方法应返回Promise对象，接口请求操作在该方法内部进行。

• 接口提交数据时，对文本框输入信息进行两端去空处理。

发版规范

仓库分支管理

分支解释

• master分支

  项目主分支，存放生产环境版本代码，当需求完成发布上线后通过 merge_request 方式更新并由 版本负责人/项目负责人 同步生成新版本 tag

• release分支

  预发布分支，由 版本负责人/项目负责人 从 master 分支派生，存放测试环境通过代码，用于发布预发环境及生产环境使用，测试通过后的代码需通过 merge_request 方式更新

• feature分支

  未来版本分支，由 master 分支派生，用于开发新版本需求使用，可每人按照各自任务自行创建，版本结束后应由分支创建者自行删除

• test分支

  用于未来版本或线上问题修复版本提测测试使用（该分支可存在并行多版本内容），由 master 分支与项目创建初期派生，后续通过可提测代码合入更新

• hotfix分支

  用于线上版本问题修复使用，由 版本负责人/项目负责人 从 master 分支派生，使用方式同于 feature 分支

命名格式

• release分支

  格式为：release+[版本号]+[版本概述]

  eg:
  release_v1.0.0_用户中心改版
  或 
  release_20220414_用户中心改版

• feature分支

  格式为：feature+[版本号]+[功能概述]+[创建者简称]

  eg：
  feature_v1.0.0_用户地址模块_czq
  或
  feature_20220414__用户地址模块_czq 

• hotfix 分支

  hotfix+[修复版本号]+[概述]

  eg:
  hotfix_v1.0.0_用户地址无法添加
  或 
  hotfix_202 20414_用地址无法添加

• tag

  tag+[版本号/上线日期]+[版本概述]

  eg:
  tag_v1.0.0_用户中心改版
  或 
  tag_20220414_用户中心改版

需求若无具体版本号则使用年月日代替，release为上线日期，feature为创建日期；功能概述建议使用英文

流程解读

1. 收到新需求后，由 master 拉取新 feature 分支进行需求开发，开发结束并自测冒烟通过后将 feature 分支内容合并至 test 分支进行功能提测；

2. 提测完成后收到测试反馈 bug 后在 feature 分支进行 bug 修复，修复完毕后再次合并至 test 分支并通知对应测试进行 bug 验证；

3. 当 test 分支当前版本所有功能于测试环境全部验证通过后通知 版本/项目负责人 拉取 release 分支，并通过 merge_request 方式将 feature 分支合并至对应 release 分支，此环节需 负责人 进行代码 CodeReview ；

4. release 分支产生的 bug 也同样于 feature 分支修复后通过 merge_request 方式再次合入 release 分支进行验证；

5. 当前版本 release 分支所有功能完成测试并通过后由此分支发布生产环境，并发起 merge_request 将分支代码合并至主分支并通知 版本/项目负责人 由合并后的代码生成 新版本tag 进行代码版本封存；

6. 版本上线后若产生线上问题，则需由 版本负责人/项目负责人 从 master 分支派生相应 hotfix 分支交由版本功能开发者进行修复，修复完成后通过merge_request 方式合并至 master 分支并通知 版本/项目负责人 进行代码 CodeReview ，代码审核通过后生成 新版本tag；

版本发布

• 当期需求发布时需列出当期需求所有功能点即 版本CheckList 并与对应产品经理一一确认后才可进行发版操作。

• 发版完成后需再次与对应产品经理进行功能点确认工作，并及时联系 版本负责人/项目负责人 进行代码合并等操作。

版本回滚方案

若当前发布版本产生重大问题或其他原因导致需要进行生产环境代码回滚时，需由 版本负责人/项目负责人 从 发版 前一次tag 派生新 hotfix 分支进行发布部署生产环境操作，发布完成后合并至 master 分支并生成 新tag。