【Vue】前端规范及工程化

关于前端规范及工程化的分享,具体按自己实际需求而定

Github

1.前端规范

1.1工作流规范

1.1.1 版本号规范

• 主版本号：当你做了不兼容的 API 修改，
• 次版本号：当你做了向下兼容的功能性新增，
• 修订号：当你做了向下兼容的问题修正。

1.1.2 版本控制规范

参考git flow协作流程,以功能为主要自下而上的开发流程规范。

• master(production分支): 只合并其他分支，不能在此分支上开发修改代码，此分支是发布到最近的生产环境中的分支。
• develop(开发分支):合并其他功能特性(feature)分支。
• feature(功能特性分支):主要开发新功能、模块的分支。分支命名:[作者]-[功能或模块]-[日期]，如Jay-login-6.20。
• 修复Bug在各自的特性分支(feature)上修改，修改完成后合并到develop分支，再合并到master分支。
• 每次develop合并到master分支时需要基于版本号规范使用git tag打上版本标签，便于版本回退。

1.1.3 提交信息规范

采用Angular提交信息规范，格式如下:

• type(本次提交的类型)

	feat：新增功能；
	fix：修复bug；
	docs：修改文档；
	refactor：代码重构，未新增任何功能和修复任何bug；
	build：改变构建流程，新增依赖库、工具等（例如webpack修改）；
	style：仅仅修改了空格、缩进等，不改变代码逻辑；
	perf：改善性能和体现的修改；
	chore：非src和test的修改；
	test：测试用例的修改；
	ci：自动化流程配置修改；
	revert：回滚到上一个版本；

• 空行
• body(提交信息主体)
• 空行
• footer(放置不兼容变更和Issue关闭的信息)

注：这里的type即header是必须的，body和footer可省略

使用提交信息工具(Commitizen)

• 全局安装commitizen
  npm install -g commitizen
• 在package.json配置scripts:"commit": "git-cz"使用npm run commit代替git commit提交信息

1.2 代码规范

1.2.1 Javascript

• 变量命名需要准确，不能无意义 let yyyymmdd; // 错误案例
• 每个语句不宜过长，擅于拆分长语句
• 函数传参不宜多余两个，多于两个使用对象传参
• 函数命名需要说明要做的事 handleData() // 错误案例

使用eslint来检查js代码

• 不能定义数组或对象最后多余的逗号
• 对象key不能重复
• 允许使用 async-await
• 开发模式允许使用 console
• 开发模式允许使用 debugger
• 不允许使用var变量
• 确保运算符周围有空格
• 不允许使用 ==
• 函数圆括号之前没有空格
• 禁止出现多个空行
• 统一逗号周围空格风格

使用prettier来检查js代码

• 单行最大字符数:120个字符
• 使用tab缩进
• 对象或数组最后项不添加逗号
• tab 两个空格
• 允许分号
• 使用单引号

1.2.2 CSS

• 类名命名基于BEM(block, element, modifier)规范，全部为小写字母，连接线改为单横线，如：btn(block)-text(element)-success(modifier)
• 可加上g(global全局)、m(module模块)等前缀来表示命名空间，如:g(global)-btn(block)-text(element)-success(modifier)
• 样式文件名使用短横线(-)命名,如element-variables.scss

使用stylelint来检查并修复css代码(并不是全部问题都能修复)

• 最大空行为1(自动修复)
• 冒号后需要空格(自动修复)
• 不允许无效的颜色值
• 单位白名单: px、em、rem、%、s
• 字符串使用单引号(自动修复)
• 单位使用小写(自动修复)
• 多个选择器需要换行(自动修复)
• 不允许空块
• 使用tab缩进(2个空格)(自动修复)
• 每个规则之间需要空一行(自动修复)

1.2.3 Vue组件

• 组件名用短横线(-)命名,如name: activity-approval
• 组件文件名命名使用驼峰大写命名,如SideBar.vue
• 建议单文件不可多于1000行，使用组件拆分复杂页面
• prop定义时尽量附上类型、默认值以及验证
• 统一v-bind、v-on使用缩写:、@

参考Element UI组件

• prop使用短横线(-)命名,如current-row-key
• event使用短横线(-)命名,如filter-change
• method使用驼峰命名,如setCurrentRow

1.2.4 注释

采用jsdoc注释规范，以下简单案例:

/**
 * 节流工具函数
 * @param {function} fn - 节流事件
 * @param {number} wait - 规定时间
 * @returns {function} fn
 */
export const throttle = function(fn, wait) {
	let prev = new Date();
	return function() {
		const args = arguments;
		const now = new Date();
		if (now - prev > wait) {
			fn.apply(self, args);
			prev = new Date();
		}
	};
};

可根据jsdoc配置并生成注释文档(并未实现)

1.2.5 半自动化代码检查提交

使用husky及lint-staged来实现git钩子函数，配合代码检查及修复工具来实现git半自动化代码提交流程，现流程如下:

• git add .
• npm run commit
• stylelint检查并修复css代码
• prettier格式化js代码
• eslint来检查js代码
• 成功 ==> commitizen提交规范化信息 失败 ==> 更改代码保存再次提交

2.项目工程

2.1 技术选型

• 编程语言 JavaScript
• 样式 sass
• 代码检查、格式化工具 eslint、prettier、stylelint
• git提交信息工具 commitizen
• 包管理 npm
• 项目构建工具流 vue-cli3
• 时间处理库 moment.js
• 工具库 lodash.js
• 开发工具 vscode(推荐)
• 开发框架 Vue
• 开发UI框架 Element-UI

2.2 项目结构

所有结构分层逻辑以模块为基准，模块名均以首字母大写开头命名,如ActivityApproval

.
├── README.md
├── babel.config.js		// babel配置文件
├── package-lock.json
├── package.json		// 项目运行配置文件
├── postcss.config.js	// postcss配置文件
├── .eslintignore		// git忽略文件
├── .eslintrc.js		// eslint配置文件
├── .prettierrc.js		// prettier配置文件
├── .stylelintrc.js		// stylelint配置文件
├── src					// 源代码
│   ├── App.vue			// 根Vue文件
│   ├── api				// 项目api文件,存放所有服务端接口
│   ├── assets			// 静态资源文件
│   ├── components		// Vue组件文件,存放所有被使用两个及以上的组件
│   ├── directives		// Vue指令文件
│   ├── filters			// Vue过滤器文件
│   ├── layout			// Vue布局文件
│   ├── main.js			// Vue入口文件			
│   ├── router			// 路由文件
│   ├── store			// Vuex文件
│   ├── styles			// 全局样式文件
│   ├── utils			// 项目工具库
│   └── views			// 各页面视图文件
└── vue.config.js		// 项目工程文件,可设置webpack相关配置

2.2.1 api

文件结构

├── api
│   └── User
│       └── login.js

示例

src/api/User/login.js

import axios from '@/utils/request';

/**
 * 登录
 * @param {object} params
 * @prop {string} params.username - 用户名
 * @prop {string} params.password - 密码
 * @returns {Promise}
 */
export const getLoginFirstExample = params => {
	return axios.request({
		url: `login`,
		method: 'get',
		params
	});
};

• 此文件夹根据业务模块存放服务端接口，添加相应注释，并达到项目中接口复用原则
• 函数名以接口方法 + 接口目的命名

2.2.2 components

文件结构

├── components
│   ├── Example
│   │   └── Example.vue

示例

src/components/Example/Example.vue

此文件夹存放项目中被使用两次及以上的组件

2.2.3 directives

文件结构

├── directives
│   ├── debounce.js
│   ├── index.js
│   └── throttle.js

示例

src/directives/debounce.js

import { debounce } from '@/utils';

/**
 * 防抖指令 v-debounce:arg.event="fn"
 * @param {number} arg - 防抖函数的时间参数
 * @param {string} event - 目标的监听事件 如: click, scroll
 * @param {function} fn - 防抖函数的绑定事件
 */
export default {
	inserted: function(el, binding) {
		let event = Object.keys(binding.modifiers)[0];
		if (event) {
			el.addEventListener(event, debounce(binding.value, binding.arg));
		}
	}
};

2.2.4 filters

文件结构

├── filters
│   ├── dateTransToTimestamp.js
│   └── index.js

示例

src/filters/dateTransToTimestamp.js

import moment from 'moment';

/**
 * 将日期转换为时间戳过滤器
 * @param {string} datestr - 日期字符串
 * @returns {number} 时间戳
 */
const DateTransToTimestamp = datestr => {
	return parseInt(moment(datestr).valueOf() / 1000);
};

export default DateTransToTimestamp;

2.2.5 layout

文件结构

├── layout
│   ├── components
│   │   └── SideBar.vue
│   └── index.vue

layout结构与views相同

2.2.6 router

文件结构

├── router
│   ├── index.js
│   └── routes.js

路由可提供如下配置功能

/**
 * path: 路径
 * name: 路由名称
 * meta: {
 *   title: 菜单名称
 * 	 icon: 菜单图标
 *   lazyload: 是否懒加载
 * 	 noCache: 是否缓存
 * 	 hidden: 是否在菜单栏显示
 * }
 */

2.2.7 store

文件结构

├── store
│   ├── index.js
│   └── module

使用vuex来进行数据复用，建议每个页面都配备一个vuex

2.2.8 styles

文件结构

├── styles
│   ├── element-ui.scss
│   ├── index.scss
│   ├── mixin.scss
│   ├── transition.scss
│   └── variables.scss

2.2.8 utils

文件结构

├── utils
│   ├── auth.js				// 存放权限方法,如token
│   ├── global.js			// 存放全局函数
│   ├── index.js			// 根文件，存放项目工具函数
│   ├── request.js			// axios网络请求文件
│   └── validate.js			// 项目验证工具文件,如提供验证手机号等工具函数