非常全面的前端协作规范

非常全面的前端协作规范

万字长文，继续刷新我的文章长度记录，涉及前端开发的方方面面。本文将持续更新和完善, 文章部分观点可能比较武断或不完整，欢迎评论和补充，一起完善该文章. 谢谢

笔者长期单枪匹马在前端领域厮杀(言外之意就是团队就一个人)，自己就是规范。随着公司业务的扩展，扩充了一些人员，这时候就要开始考虑协作和编码规范问题了。本文记录了笔者在制定前端协作规范时的一些思考，希望能给你们也带来一些帮助.

一个人走的更快，一群人可以走得更远，前提是统一的策略，还要不断地反省和优化。

以下是目录概览, 看出这是一篇浩浩荡荡的长文

• 1 工作流规范

• • 1.1.1 版本规范
  • 1.1.2 版本控制系统规范
  • 1.1.3 提交信息规范
  • 1.1 开发
  • 1.2 构建规范
  • 1.3 发布工作流规范
  • 1.4 持续集成
  • 1.5 任务管理

• 2 技术栈规范

• • 2.1 技术选型
  • 2.2 迎接新技术

• 3 浏览器兼容规范

• • 3.1 确定兼容策略
  • 3.2 确定浏览器分级
  • 3.3 获取统计数据

• 4 项目组织规范

• • 4.1 通用的项目组织规范
  • 4.2 目录组织的风格
  • 4.3 脚手架和项目模板

• 5 编码规范

• • 5.1 Javascript
  • 5.2 HTML
  • 5.3 CSS
  • 5.4 代码格式化
  • 5.5 集大成的
  • 5.6 特定框架风格指南
  • 5.7 Code Review

• 6 文档规范

• • 6.1 建立文档中心
  • 6.2 文档格式
  • 6.3 定义文档的模板
  • 6.4 讨论即文档
  • 6.5 注释即文档
  • 6.6 代码即文档

• 7 UI设计规范

• 8 测试规范

• • 8.1 测试的流程
  • 8.2 单元测试

• 9 异常处理、监控和调试规范

• • 9.1 异常处理
  • 9.2 日志
  • 9.3 异常监控

• 10 前后端协作规范

• • 10.1 协作流程规范
  • 10.2 接口规范
  • 10.3 接口文档规范
  • 10.4 接口测试与模拟

• 11 培训/知识管理/技术沉淀

• • 11.1 新人培训
  • 11.2 营造技术氛围

• 12 反馈

CHANGELOG

• 2019.7.28 新增技术选型
• 2019.7.29 新增浏览器统计数据获取
• 2019.9.6 建立技术氛围一节 新增面试题库

什么是规范?

规范，名词意义上：即明文规定或约定俗成的标准，如：道德规范、技术规范等。动词意义上：是指按照既定标准、规范的要求进行操作，使某一行为或活动达到或超越规定的标准，如：规范管理、规范操作.

为什么需要规范?

• 降低新成员融入团队的成本, 同时也一定程度避免挖坑
• 提高开发效率、团队协作效率, 降低沟通成本
• 实现高度统一的代码风格，方便review, 另外一方面可以提高项目的可维护性
• 规范是实现自动化的基础
• 规范是一个团队知识沉淀的直接输出

规范包含哪些内容?

如文章标题，前端协作规范并不单单指‘编码规范’，这个规范涉及到前端开发活动的方方面面，例如代码库的管理、前后端协作、代码规范、兼容性规范；

不仅仅是前端团队内部需要协作，一个完整的软件生命周期内，我们需要和产品/设计、后端(或者原生客户端团队)、测试进行协作, 我们需要覆盖这些内容.

下面就开始介绍，如果我是前端团队的Leader，我会怎么制定前端规范，这个规范需要包含哪些内容?

1 工作流规范

1.1 开发

1.1.1 版本规范

项目的版本号应该根据某些规则进行迭代, 这里推荐使用语义化版本规范, 通过这个规范，用户可以了解版本变更的影响范围。规则如下:

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

1.1.2 版本控制系统规范

大部分团队都使用git作为版本库，管理好代码也是一种学问。尤其是涉及多人并发协作、需要管理多个软件版本的情况下，定义良好的版本库管理规范，可以让大型项目更有组织性，也可以提高成员协作效率.

比较流行的git分支模型/工作流是git-flow, 但是大部分团队会根据自己的情况制定自己的git工作流规范, 例如我们团队的分支规范

Git 有很多工作流方法论，这些工作流的选择可能依赖于项目的规模、项目的类型以及团队成员的结构.

比如一个简单的个人项目可能不需要复杂的分支划分，我们的变更都是直接提交到 master 分支;

再比如开源项目，除了核心团队成员，其他贡献者是没有提交的权限的，而且我们也需要一定的手段来验证和讨论贡献的代码是否合理。所以对于开源项目 fork 工作流更为适合.

了解常见的工作流有利于组织或创建适合自己团队的工作流, 提交团队协作的效率:

• 简单的集中式
• 基于功能分支的工作流
• Git Flow ?
• Fork/Pull Request 工作流

1.1.3 提交信息规范

组织好的提交信息, 可以提高项目的整体质量. 至少具有下面这些优点:

• 格式统一的提交信息有助于自动化生成CHANGELOG
• 版本库不只是存放代码的仓库, 它记录项目的开发日志, 它应该要清晰表达这次提交的做了什么. 这些记录应该可以帮助后来者快速地学习和回顾代码, 也应该方便其他协作者review你的代码
• 规范化提交信息可以促进提交者提交有意义的、粒度合适的’提交’. 提交者要想好要怎么描述这个提交，这样被动促进了他们去把控提交的粒度

社区上比较流行的提交信息规范是Angular的提交信息规范, 除此之外，这些也很不错:

• Atom
• Ember
• Eslint
• JQuery

另外这些工具可以帮助你检验提交信息, 以及生成CHANGELOG:

• conventional-changelog - 从项目的提交信息中生成CHANGELOG和发布信息
• commitlint - 检验提交信息
• commitizen - ?简单的提交规范和提交帮助工具，推荐
• standard-changelog - angular风格的提交命令行工具

1.2 构建规范

对于团队、或者需要维护多个项目场景，统一的构建工具链很重要, 这套工具应该强调"约定大于配置"，让开发者更专注于业务的开发。笔者在<为什么要用vue-cli3?>文章中提出了vue-cli3更新有很多亮点，非常适合作为团队构建工具链的基础:

• 首先这类工具是推崇’约定大于配置’。即按照他们的规范，可以实现开箱即用，快速开发业务. 在团队协作中这点很重要，我们不推荐团队成员去关心又臭又长的webpack构建配置
• vue-cli3抽离了cli service层，可以独立更新工具链。也就是说项目的构建脚本和配置在一个独立的service项目中维护，而不是像以前一样在每个项目目录下都有webpack配置和依赖. 这样做的好处是独立地、简单地升级整个构建链
• 灵活的插件机制。对于团队的定制化构建应该封装到插件中，这样也可以实现独立的更新。

我们可以选择第三方CLI, 当然也定制自己的构建链，按照上面说的这个构建链应该有以下特点:

• 强约定，体现团队的规范。首先它应该避免团队成员去关心或更改构建的配置细节，暴露最小化的配置接口。 另外构建工具不仅仅是构建，通常它还会集成代码检查、测试等功能。
• 方便升级。尤其是团队需要维护多个项目场景, 这一点很有意义

下面是社区上比较流行的构建工具. 当然，你也可以根据自己的团队情况开发自己的CLI, 但是下面的工具依然很有参考价值：

• create-react-app - ?零配置开始React开发
• vue-cli - ?零配置、渐进增强的项目构建CLI
• parcel - 零配置的Web应用打包工具
• Fusebox - 高速易用的打包工具
• microbundle - 零配置, 基于Rollup，适合用于打包‘库’

1.3 发布工作流规范

发布工作流指的是将‘软件成品’对外发布(如测试或生产)的一套流程, 将这套流程规范化后，可以实现自动化.

举个例子, 一个典型的发布工作流如下：

• 代码变更
• 提交代码变更到远程版本库
• 程序通过CI测试(例如Travis变绿)
• 提升package.json中的版本
• 生成CHANGELOG
• 提交package.json和CHANGELOG.md文件
• 打上Tag
• 推送

如果你遵循上面的规范，那么就可以利用社区上现有的工具来自动化这个流程. 这些工具有:

• conventional-changelog-cli
• conventional-github-releaser
• 实际上自己开发一个也不是特别难的事情.

1.4 持续集成

将整套开发工作流确定下来之后, 就可以使用持续集成服务来自动化执行整个流程。比如一个典型的CI流程:

持续集成是什么，有什么意义呢?

我们需要持续集成拆成两个词分别来理解, 什么是持续? 什么是集成?

持续(Continuous), 可以理解为’频繁’或者‘连续性’. 不管是持续集成还是敏捷开发思维、看板，都认为‘持续’是它们的基础。

举一个通俗的例子，比如代码检查，‘持续的’的代码检查就是代码一变动(如保存，或者IDE实时检查、或者提交到版本库时)就马上检查代码，而‘非持续’的代码检查就是在完成所有编码后，再进行检查。对比两者可以发现，持续性的代码检查可以尽早地发现错误，而且错误也比较容易理解和处理，反之非持续性的代码检查，可能会发现一堆的错误，失之毫厘谬以千里，错误相互牵连，最终会变得难以收拾。

‘持续’的概念，可以用于软件开发的方方面面，本质上就是把传统瀑布式的软件开发流程打碎，形成一个个更小的开发闭环，持续地输出产品，同时产品也持续地给上游反馈和纠正。

那什么是‘集成’呢？狭义的集成可以简单认为是‘集成测试’吧. 集成测试可以对代码静态测试、单元测试、通过单元测试后可以进行集成测试，在应用组成一个整体后在模拟环境中跑E2E测试等等。也就是说，在这里进行一系列的自动化测试来验证软件系统。

广义的持续集成服务，不仅仅是测试，它还衍生出很多概念，例如持续交付、持续部署，如下图

OK, 总结一下为什么持续集成的好处:

• 尽早发现错误，快速试错。越早发现错误，处理错误的成本越低
• 自动化工作流，减少人工干预。人类比机器容易犯错, 而且机器擅长做重复的事情

对于持续集成规范一般会定义这些内容:

• 执行的环境. 比如容器、Node版本、操作系统等等

• 触发的条件。比如定时触发、在哪个分支触发、会触发什么任务等等

• 执行的任务

• 划分持续集成的阶段. 比如

• • 检查：包括单元测试和代码lint. 所有push到版本库的代码都会跑这个阶段. 一般可以在提交title中包含[ci skip]来跳过这个阶段
  • 构建: 对前端项目进行构建. 只有打上版本tag的提交或release分支会跑构建任务
  • 发布: 将前端的构建结果进行交付/发布. 只有打上版本tag的提交或者release分支在构建成功后会跑发布任务

• 定义持续集成脚本模板

常用的CI服务:

• Github

• • Travis CI
  • CircleCI
  • 完整列表

• GitLab: Gitlab-CI

• 通用

• • Jenkins

扩展

• 持续集成是什么

1.5 任务管理