一个人走的更快，一群人可以走得更远，前提是统一的策略，还要不断地反省和优化。
为了提升团队凝聚力，统一团队代码风格，优化团队协作效率，提出了前端开发规范。
为什么需要规范
-
规范的代码可以促进团队合作；
-
规范的代码可以降低维护成本；
-
规范的代码有助于 code review（代码审查）；
-
养成代码规范的习惯，有助于程序员自身的成长；
*规范架构图来直观的了解一下
一、开发规范
1､技术选型
如何对团队的技术栈进行规范, 怎么进行选型呢？举个例子, 先确定备选项, 你现在要选Vue还是选React(一个可能引起论战的主题)。
*团队的开发效率是基于稳定且熟练的技术栈的。
1.1 技术选型
-
选择你最熟悉的技术。则可以很好地控制使用过程中的风险，方便对程序进行调优。
-
选择拥有强大生态和社区支撑的开源技术。有强大的生态和社区意味着，很多东西你不需要重复去造轮子，或者遇到问题可以很快解决，有更多的选择。
-
选择成长期的技术。选择一个技术的最低标准是，技术的生命周期必须显著长于项目的生命周期。
-
API的稳定性。比较典型的例子就是Angular和Python，API不稳定会导致社区的割裂，也会导致项目升级成本变高、或者无法升级, 最终成为技术债。
-
基础设施配合。一个技术往往不是孤立存在的，它需要和其他技术相互配合，这种技术之间的融合度也是需要考虑的。
-
业务考虑。选型需要充分地理解业务，理解用户需求，当下需要解决的首要问题，以及可能的风险有哪些，再将目标进行分解，进行具体的技术选型、模型设计、架构设计。
1.2 迎接新技术
当团队容纳一个新的技术选型需要考虑以下几点：
-
学习成本。考虑团队成员的接纳能力。如果成本小于收获的利益，在团队里面推行估计阻力会比较大。
-
收益。是否能够解决当前的某些痛点。
-
考虑风险。一般我们不能将一个实验阶段的技术使用的生产环境中。
团队的开发效率是基于稳定且熟练的技术栈的
vue2.6以上 构建用户界面的渐进式框架
axios 前端异步执行http请求的ajax框架
eslint 代码格式静态检查的工具
babel JavaScript编译器
element-ui 组件库
less预编译
2､兼容规范
团队应该根据的用户设备占比情况、应用类型、开发成本、浏览器市场统计数据等因素，来制定自己的浏览器兼容规范。
*有了浏览器兼容规范，前端开发和兼容性测试就有理有据，避免争议; 同时它也是前端团队的一种对外声明，除非特殊要求，不符合浏览器兼容规范的浏览器，前端开发人员可以选择忽略。
1.1 CSS 的兼容要求
在CSS的兼容处理上，我们使用的是 postcss 的 autoprefixer
// postcss.config.js
module.exports = {
plugins: {
autoprefixer: {},
},
};
1.2 JS 的兼容要求
在处理 js 的兼容性时，我们使用 babel 抹平浏览器差异。
1.3 总体的机型兼用要求
安卓需要兼容安卓 4.0 以上，iOS 需要兼容 8.0 以上
# .browserlistrc
> 1%
last 3 versions
iOS >= 8
Android >= 4
Chrome >= 40
3､编码规范
统一的编码规范对团队项目的长远维护不无裨益. 一致性的代码规范可以增强团队开发协作效率、提高代码质量、减少遗留系统维护的负担。
1.1 Editorconfig 规范编辑器的的配置
配置文件 .editorconfig
root = true
[*]
charset = utf-8 # 字符编码 utf-8
indent_style = space # 输入的 tab 都用空格代替
indent_size = 2 # 一个 tab 用 2 个空格代替
end_of_line = lf # 换行符使用 unix 的换行符 \n
trim_trailing_whitespace = true # 去掉每行末尾的空格
insert_final_newline = true # 每个文件末尾都加一个空行
[*.md]
trim_trailing_whitespace = false # .md 文件不去掉每行末尾的空格
1.2 ESlint 具体配置文件（待完善）
rules: {
// allow async-await
'generator-star-spacing': 'off',
"no-tabs":"off",
// allow debugger during development
'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
'space-before-function-paren': 0
}
1.3 vscode配置
vscode配置
Auto Rename Tag - 修改HTML标签时自动修改匹配标签
beautify css/sass/scss/less - css/sass/scss/less格式化
Bracket Pair Colorizer - 颜色标识匹配 (快速区分括号位置和类型)
css peek - html与css关联
ESLint - 规范js代码书写规则
Git History - 查看git提交的历史记录
Git supercharged - 提交信息
HTML Snippets - html标签的代码提示
koroFileHeader - 头部注释和函数注释的插件
Live Server - 开启服务
path intellisense - 文件路径提示
Prettier - Code formatter 格式化插件
SonarLint - 监控代码质量
TSlint - ts的书写规范
vetur - vue语法高亮 (Vue开发者必备)
vueHelper - vue2代码段
setting.json配置
{
"workbench.editor.enablePreview": false, //打开文件不覆盖
"search.followSymlinks": false, //关闭rg.exe进程
"editor.minimap.enabled": false, //关闭快速预览
"liveServer.settings.donotShowInfoMsg": true, //关闭liveserver提示
// "files.autoSave": "afterDelay", //打开自动保存
"editor.fontSize": 16, //设置文字大小
"editor.lineHeight": 24, //设置文字行高
"editor.lineNumbers": "on", //开启行数提示
"editor.quickSuggestions": {
//开启自动显示建议
"other": true,
"comments": true,
"strings": true
},
"window.zoomLevel": 0, // 调整窗口的缩放级别
"editor.tabSize": 2, //制表符符号eslint
// "editor.formatOnSave": true, //每次保存自动格式化
// #让prettier使用eslint的代码格式进行校验
"fileheader.configObj": {
"autoAdd": true // 默认开启
},
// #使用带引号替代双引号
"prettier.singleQuote": false,
"vetur.format.defaultFormatterOptions": {
"prettier": {
"eslintIntegration": true,
"semi": false
}
},
"javascript.format.insertSpaceBeforeFunctionParenthesis": false, //让函数(名)和后面的括号之间加个空格
"vetur.format.defaultFormatter.js": "vscode-typescript", //让vue中的js按编辑器自带的ts格式进行格式化
// "vetur.format.defaultFormatter.html": "js-beautify-html",
"eslint.validate": [
//开启对.vue文件中错误的检查
"javascript",
"javascriptreact",
"html",
"vue"
],
// "workbench.iconTheme": "vscode-icons",
"explorer.confirmDelete": false,
// 文件头部注释
"fileheader.customMade": {
"Author": "jiashuangxi",
"Date": "Do not edit",
"LastEditors": "jiashuangxi",
"LastEditTime": "Do not Edit",
"Describe": ""
},
//函数注释
"fileheader.cursorMode": {
"Description": "",
"param": ""
},
"[javascript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[typescript]": {
"editor.defaultFormatter": "vscode.typescript-language-features"
},
"editor.wordWrap": "on",
// 每次保存的时候将代码按eslint格式进行修复
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
}
}
4､命名规范
命名规范一般指命名是使用驼峰式、匈牙利式还是帕斯卡式；用名词、名词组或动宾结构来命名。
变量命名和函数命名的侧重点不同。
1.1 变量命名
变量命名的重点是表明这个变量“是什么”，倾向于用名词命名。
1.2 函数命名
函数命名的重点是表明这个函数“做什么”，倾向于用动宾结构来命名（动宾结构就是 doSomething）。
// 变量命名示例
const appleNum = 1
const sum = 10
// 函数命名示例
function formatDate() { ... }
function toArray() { ... }
5､注释规范
合理的注释，可以提高代码的可读性和可维护性。
1.1 注释的原则
如无必要，勿增注释，应当追求「代码自注释」
// bad
// 如果已经准备好数据，就渲染表格
if (data.success && data.result.length > 0) {
renderTable(data);
}
// good
const isTableDataReady = data.success && data.result.length > 0;
if (isTableDataReady) {
renderTable(data);
}
**注释：**如有必要，尽量详尽，需要注释的地方应该尽量详尽地去写。
1.2 注释的规范
遵循统一的风格规范，如一定的空格、空行，以保证注释自身的可读性。
-
头部注释
-
单行注释使用//，
注释行的上方需要有一个空行；注释内容和注释符之间需要有一个空格。
// 关闭弹窗
handleClose(formName) {
this.resetForm(formName)
this.$emit('close', false)
},
// 重置为空
resetForm(formName) {
this.$refs[formName].resetFields()
}
-
多行注释使用 /** ... */
/**
- make() returns a new element
- based on the passed-in tag name */ function make(tag) { // ...
return element; }
-
css注释
.page { padding: 0px 20px 20px; background-color: #fff;
// 正文标题 &-title { padding: 30px 0 10px; font-size: 14px; color: #475669; }
// 查询条件 &-search { padding: 20px; background-color: #f7f8fb; /deep/ .el-form { &-item { &__content { .el-input{ width: 200px; } } } } }
// 操作按钮与上面距离 &-button { padding-top: 30px; }
// 表格与上面距离 &-result { padding-top: 30px; }
// 分页设置 (位置右) &-pagination { padding-top: 10px; text-align: right; } }
6､代码提交规范
*Git显著优点就是版本的分支（branch）和合并（merge）十分方便。（重要）
1.1 版本控制系统规范
团队使用git作为版本库，管理好代码也是一种学问。比较流行的git分支模型/工作流是git-flow。
*代码管理 — git flow 流程
项目存在两个长期分支
主分支master：对外发布的版本，任何时候在这个分支拿到的，都是稳定的分布版；
开发分支develop：用于日常开发，存放最新的开发版。
项目存在三种短期分支
功能分支 feature branch： feature分支都是基于develop创建的，开发完成后会合并到develop分支上。
预发分支 release branch：基于最新develop分支创建，当新功能足够发布一个新版本。
补丁分支 hotfix branch：基于master分支创建，对线上版本的bug进行修复。
*经验总结：新需求的 数据分析功能 开发。
Git 有很多工作流方法论，这些工作流的选择可能依赖于项目的规模、项目的类型以及团队成员的结构。
// ***** 一人开发时：
# 1、主分支(master) 开一个新的分支
git checkout -b develop-dataAnalysis // 在这个分支开发
// ***** 多人开发时：
# 1、主分支(master) 开一个新的分支
git checkout -b develop-dataAnalysis
# 2、从日常开发分支(develop-dataAnalysis)开一个新的分支: 功能+名字缩写
dataAnalysis-jsx
dataAnalysis-lby
dataAnalysis-zll
# 3､ 代码提交之前先 “develop+功能” 进行同步。（减少冲突）
// 1､ 本地分支代码有修改，会出现同步不下来的情况.（避免问题）
git stash // 删除并保存改动
// 2､ 代码同步
git checkout develop-dataAnalysis
git pull develop-dataAnalysis
// 3､切到自己分支，与develop-dataAnalysis同步
git checkout dataAnalysis-jsx // 切到自己的功能分支
git stash pop // 恢复代码，处理冲突，提交代码
说明：
1、主干master必须是可部署状态，避免下一个特性分支是不可运行的状态
2、每一个合并回主干的特性分支也必须是可部署状态。
3、多人合作是无法避免冲突，遇到冲突的时候，切换到冲突分支，解决完冲突后再次请求合并到主干。
4、每一个特性分支经过测试后都可以合并到主干，合并到主干后都可以被删除掉，这样确保项目的分支尽可能简洁，不需要顾虑这个特性分支以后还有没有用。
1.2 提交信息规范
组织好的提交信息, 可以提高项目的整体质量. 至少具有下面这些优点：
1）格式统一的提交信息有助于自动化生成CHANGELOG；
2）版本库不只是存放代码的仓库, 它记录项目的开发日志, 它应该要清晰表达这次提交的做了什么；
（记录可以帮助快速地学习和回顾代码, 也应该方便其他协作者review你的代码）
3）规范化提交信息可以促进提交者提交有意义的、粒度合适的'提交'；
规则：功能｜修复｜文档 ｜ 样式｜重构
1.3 开发上线流程
1.4 避坑日志
代码冲突原因：两个人同时修改同一个文件，提交就会报冲突的错误。
解决冲突方法：
1、建议在代码提交之前先git merge develop 与develop进行同步。（减少冲突）
2、如果merge不成功，说明你的代码与别人的代码冲突了。需要怎么搞呢？
1）首先git status 查看本地代码修改情况。
2）通过以下命令，删除与恢复代码。
git stash 删除并保存改动
git stash pop 恢复改动
注：用这个操作，一般都处理 merge不成功的问题。
*多人开发注意点：
1、今日代码今日提交，保证正常。
2、功能点建项目分支。
3、git commit 注释明确。
4、git rebase (待考虑)。
7､图片规范
1.1 图片无损压缩
相关地址：tinypng.com/
1.2 iconfont 的项目实践
Font class方式（较友好）
1、在线使用
超级简单，只要在线生成代码，引用在线的css文件即可使用。
1）在index.html中引用
<link rel="stylesheet" href="//at.alicdn.com/t/font_1261797_48wm20jf8z.css">
2）项目中就可以使用字体图标
<template>
<i class="iconfont cl-icon-fold"></i>
<i class="iconfont cl-icon-delete-solid"></i>
</template>
2、本地使用
与unicode方式类似，下载代码到本地。因为我是用scss管理样式的，需要在下载的代码中提取出关键部分。除了引用字体库，还要将其中的iconfont.css中定义的before伪元素全部复制到自己的scss文件中。
@font-face {
font-family: "iconfont";
src: url('../fonts/iconfont.eot'); /* IE9*/
src: url('../fonts/iconfont.eot#iefix') format('embedded-opentype'), /* IE6-IE8 */
url('../fonts/iconfont.woff') format('woff'), /* chrome, firefox */
url('../fonts/iconfont.woff2') format('woff2'), /* chrome, firefox */
url('../fonts/iconfont.ttf') format('truetype'), /* chrome, firefox, opera, Safari, Android, iOS 4.2+*/
url('../assets/fonts/iconfont.svg#iconfont') format('svg'); /* iOS 4.1- */
}
.iconfont {
font-family: "iconfont" !important;
font-size: 16px;
font-style: normal;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
// 列了一部分举例
.cl-icon-user:before {
content: "\e64b";
}
*总结
1）兼容性良好，支持ie8+，及所有现代浏览器。
2）相比于unicode语意明确，书写更直观。可以很容易分辨icon是什么。
3）因为使用class来定义图标，所以当要替换图标时，只需要修改class里面的unicode引用。
4）不过因为本质上还是使用的字体，所以多色图标还是不支持的。
8､项目结构规范
项目组织规范定义了如何组织一个前端项目, 例如项目的命名、项目的文件结构、版本号规范等等。尤其对于开源项目，规范化的项目组织就更重要了。
├── dist // [生成] 打包目录
├── src // [必选] 开发目录
│ ├── api // [必选] api接口
│ ├── assets // [可选] 公共资源（被项目引用的经过webpack处理的资源）
│ ├── components // [必选] 业务组件必须写在这里
│ ├── route // [可选] 路由
│ ├── style // [可选] 公共样式
│ ├── libs // [可选] 公共库（一般用于对一些库的封装）
│ ├── utils // [可选] 工具库（用于一些函数方法之类的库）
│ ├── store // [可选] 数据存储 vuex
│ ├── views // [必选] 页面组件，不允许有其他类型组件混入
│ ├── App.vue // [必选] 根组件
│ └── main.(js|ts) // [必选] 入口文件
├── public // [必选] 不会被webpack编译的资源
│ ├── index.html // [必选] 模板
│ └── logo.png // [可选] 项目 logo
├── config // [可选] 配置目录
├── mock // [可选] mock 数据
├── test // [可选] 测试代码
├── docs // [可选] 文档
│── .gitignore // [必选] git 忽略的文件
│── .editorconfig // [必选] 编译器配置
│── .npmignore // [可选] 如果是 npm 包是必选
│── jsconfig.json // [可选] 用于 vscode 配置
├── README.md // [必选] 导读
├── package.json // [必选] 大家都懂
└── ...... // [可选] 一些工具的配置，如果 babel.config.js 等
例如：vue 项目开发
通用的项目组织规范
docs/: 项目的细化文档, 可选.
node_moules文件
node_moules：存放的是npm加载的项目依赖模块
src文件
src：放置组件和入口文件。
assets：主要存放一些静态图片资源的目录。(css 等也可放在这里)
views :放置的为公共组件(主要还是各个主要页面)
components：(自定义功能组件)这里存放的是开发需要的的各种组件，各个组件联系在一起组成一个完整的项目。
router：存放了项目路由文件。
App.vue：是项目主(/根)组件，***也是项目所有组件和路由的出口***，之后它会被渲染到项目根目录的 index.html 中显示出来，我们可以在这里写一些适合全局的css样式。
main.js：入口文件，引入了vue模块和app.vue组件以及路由router，我们需要在全局使用的一些东西也可以定义在这里面。
store.js: 为vuex的文件
其他文件
.babelrc：ES6语法编译配置。
.eslintrc.js：eslint的配置文件，eslint是用来管理和检测js代码风格的工具，可以和编辑器搭配使用，如vscode的eslint插件，当有不符合配置文件内容的代码出现就会报错或者警告。
.gitignore：忽略的文件。
package.json：项目及工具的依赖配置文件。只是粗略的版本,具体依赖于
README.md：项目说明。
二、协作规范
1､UI协作规范
简单总结一下UI设计规范的意义：
-
提供团队协作效率(产品和开发)；
-
提高组件的复用率. 统一的组件规范可以让组件更好管理；
-
保持产品迭代过程中品牌一致性；
注意，这里的 UI 规范是指项目里常用 UI 组件的表现方式以及组件的命名方式，而不是指 UI 组件如何设计。
1.1 表现方式
现在开源的 UI 组件库有很多，不同的组件库的组件表现方式也不一样。例如有些按钮组件点击时颜色变深，有些组件则是变浅。所以建议在 PC 端和移动端都使用统一的 UI 组件库（PC 端、移动端各一个），或者同一个项目里只使用一个 UI 组件库。
另外，项目里常用的组件表现方式也需要通过文档确定下来。例如收缩展开的动画效果，具体到动画持续时间、动画是缓进快出还是快进缓出等等。
如果不把这些表现方式的规范确定下来，就有可能出现以下这种情况：
1.同样的组件，在不同的页面有不同的表现方式（例如动画效果）。因为没有规范，开发根据个人喜好添加表现效果。
2.同样的二次确认弹窗，提示语不一样，按钮类型也不一样。
1.2 统一命名
统一命名，也是为了减少沟通成本。
举个例子，现在的日期组件可以选单个日期、也可以选择范围日期，有的还可以选择时间。这样一来，一个日期组件就有四种情况：
1.单个日期带时间
2.单个日期不带时间
3.日期范围带时间
4.日期范围不带时间
如果这种情况不区分好，开发在看产品文档的时候就会疑惑，从而增加了开发与产品的沟通成本。
综上所述，我们可以发现制定 UI 规范的好处有两点：
1.统一页面 UI 标准，节省 UI 设计时间。
2.减少沟通成本，提高前端开发效率。
三、监控规范
1､sonar 代码质量检查
相关地址：www.yuque.com/docs/share/… 《2、Sonar 代码质量 (检测结果)》
2､sentry 监控系统
*本文档参考改以下规范。
CSS创作指南 github.com/cssdream/cs…
Code-guide github.com/mdo/code-gu…
HTML-CSS-guide github.com/doyoe/html-…
前端大全的前端协作规范 mp.weixin.qq.com/s/FxhtAFI9n…
转转前端开发规范的落地实践
