非常全面的前端协作规范-JieYingAI捷鹰AI

CHANGELOG

什么是规范?

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

为什么需要规范?

规范包含哪些内容?

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

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

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

1 工作流规范 1.1 开发 1.1.1 版本规范

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

1.1.2 版本控制系统规范

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

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

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

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

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

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

1.1.3 提交信息规范

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

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

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

1.2 构建规范

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

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

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

1.3 发布工作流规范

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

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

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

1.4 持续集成

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

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

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

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

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

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

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

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

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

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

定义持续集成脚本模板

常用的CI服务:

GitLab: Gitlab-CI

通用

扩展

1.5 任务管理

作为前端Leader少不了任务管理。看板是目前最为流行的任务管理工具，它可以帮助我们了解项目的进度、资源的分配情况、还原开发现场.

笔者毕业第一年在一家很小的外包公司中工作，初生牛犊不怕虎，我竟然给老板推销起了看板和敏捷项目管理，想要改善项目管理这块效率低下问题，老板表示很支持，但是其他成员积极性并不高, 结果当然是失败的。

当时还起草了一份‘看板实施细则’, 所以任务管理这一块也算小有心得吧.

说说一些比较好用的工具吧：

2 技术栈规范

笔者现在所在的公司之前前端技术栈就非常混乱，Vue、React和AngularJS三大框架都有, 而且风格相差也很大. 当时我就想收包裹走人. 关于技术栈不规范的下场可以参考印度的飞机:

很少有人能精通这三个框架的，更别说是一个团队。

三大框架跟编程语言一样都有自己的设计哲学，这跟库是不一样, 一个库的替换成本很低；而框架的背后是一个架构、一个生态。每个框架背后牵涉着开发思维、生态系统、配套工具、最佳实践、性能调优。要精通和熟练一个框架需要付出的成本是很高。

所以说团队的开发效率是基于稳定且熟练的技术栈的。稳定的技术栈规范有利于团队协作和沟通; 另外如果团队精通这个技术栈，当出现问题或者需要深入调优, 会相对轻松。

前端技术栈规范主要包含下面这些类型:

样式. 包含了命名规范、预处理器、方法论等等

动画引擎

QA. 包含了测试、Lint、格式化工具、监控

项目构建工具流. 例如webpack、vue-cli

包管理器。npm、yarn

项目管理工具

时间处理。例如Moment.js

模板引擎

开发工具

后端开发框架

工具库

开发/调试工具

等等

可以参考一下我们团队的技术栈规范

2.1 技术选型

如何从零对团队的技术栈进行规范, 或者说怎么进行选型呢？举个例子, 先确定备选项, 你现在要选Vue还是选React(一个可能引起论战的主题)？

恰好前几天在SegmentFault回答了一个问题: , 我讲了一个我们几年前是如何决定要使用React还是Vue的例子(注意结果不重要！)：

这篇文章写得非常好，给了我一些启发。结合上面的回答的例子, 来讲一讲在对相关技术进行选型的一些方法(评分项):

综上，在这个案例中，React是胜出的。

扩展:

2.2 迎接新技术

当然，对于团队而言也要鼓励学习新的技术、淘汰旧的技术栈。因为一般而言新的技术或解决方案，是为了更高的生产力而诞生的。当团队容纳一个新的技术选型需要考虑以下几点：

就我们团队而言，每个成员都有自己感兴趣的方向和领域，所以我们可以分工合作，探索各自的领域，再将成果分享出来，如果靠谱的话则可以在实验项目中先试验一下，最后才推广到其他项目.

3 浏览器兼容规范

前端团队应该根据针对应用所面对的用户情况、应用类型、开发成本、浏览器市场统计数据等因素，来制定自己的浏览器兼容规范，并写入应用使用手册中.

有了浏览器兼容规范，前端开发和兼容性测试就有理有据，避免争议; 同时它也是前端团队的一种对外声明，除非特殊要求，不符合浏览器兼容规范的浏览器，前端开发人员可以选择忽略。

3.1 确定兼容策略

渐进增强还是优雅降级. 这是两个不同方向策略，渐进增强保证低版本浏览器的体验，对于支持新特性的新浏览器提供稍好的体验；优雅降级则是相反的，为现代浏览器提供最好的体验，而旧浏览器则退而求之次，保证大概的功能.

选择不同的策略对前端开发的影响是比较大的，但是开发者没有选择权。确定哪种兼容策略，应该取决于用户比重，如果大部分用户使用的是现代浏览器，就应该使用优雅降级，反之选择渐进增强.

3.2 确定浏览器分级

YUI就曾提出浏览器分级原则，到今天这个原则依然适用。简单说就是将浏览器划分为多个等级，不同等级表示不同的支持程度. 比如我们团队就将浏览器划分为以下三个等级:

一般而言, 根据浏览器市场分布情况、用户占比、开发成本等因素划分等级.

举个例子，下面是我们对管理系统的兼容规范:

3.3 获取统计数据

百度统计是中文网站使用最为广泛的、免费的流量分析平台. 如上图，通过这些统计平台可以获取到终端真实的浏览器使用情况, 点击查看示例。

如果公司没有开发自己监控服务，还是建议使用这些免费的，有大厂支持的监控工具:

可以从这些地方获取通用的浏览器统计数据:

确定浏览器是否支持某个特性:

4 项目组织规范

项目组织规范定义了如何组织一个前端项目, 例如项目的命名、项目的文件结构、版本号规范等等。尤其对于开源项目，规范化的项目组织就更重要了。

4.1 通用的项目组织规范

一个典型的项目组织规范如下:

CHANGELOG.md: 放置每个版本的变动内容, 通常要描述每个版本变更的内容。方便使用者确定应该使用哪个版本. 关于CHANGELOG的规范可以参考keep a changelog

package.json: 前端项目必须. 描述当前的版本、可用的命令、包名、依赖、环境约束、项目配置等信息.

.gitignore: 忽略不必要的文件，避免将自动生成的文件提交到版本库

.gitattributes: git配置，有一些跨平台差异的行为可能需要在这里配置一下，如换行规则

docs/: 项目的细化文档, 可选.

examples/: 项目的示例代码，可选.

build: 项目工具类脚本放置在这里，非必须。如果使用统一构建工具，则没有这个目录

dist/: 项目构建结果输出目录

src/: 源代码目录

tests/: 单元测试目录. 按照Jest规范, __tests__目录通常和被测试的模块在同一个父目录下, 例如:

/src  __tests__/    index.ts    a.ts  index.ts  a.ts复制代码

tests: 全局的测试目录，通常放应用的集成测试或E2E测试等用例

.env*: 项目中我们通常会使用环境变量来影响应用在不同运行环境下的行为. 可以通过dotEnv来从文件中读取环境变量. 通常有三个文件:

基本上这些文件的变动的频率很少，团队成员应该不要随意变动，以免影响其他成员。所以通常会使用.env.*.local文件来覆盖上述的配置, 另外会设置版本库来忽略*.local文件.

对于开源项目通常还包括这些目录:

任意一个优秀的开源项目都是你的老师，例如React、Vue…

4.2 目录组织的风格

上面只是一个通用的项目组织规范，具体源代码如何组织还取决于你们使用的技术栈和团队喜好。网上有很多教程，具体可以搜索怎么组织XX项目. 总结一下项目组织主要有三种风格:

大部分情况下, 我们都是使用混合两种方式的目录结构，例如:

src/  components/      # ? 项目通用的‘展示组件’    Button/      index.tsx    # 组件的入口, 导出组件      Groups.tsx   # 子组件      loading.svg  # 静态资源      style.css    # 组件样式    ...    index.ts       # 到处所有组件  containers/      # ? 包含'容器组件'和'页面组件'    LoginPage/     # 页面组件, 例如登录      components/  # 页面级别展示组件，这些组件不能复用与其他页面组件。        Button.tsx # 组件未必是一个目录形式，对于一个简单组件可以是一个单文件形式. 但还是推荐使用目录，方便扩展        Panel.tsx      reducer.ts   # redux reduces      useLogin.ts  # (可选)放置'逻辑', 按照?分离逻辑和视图的原则，将逻辑、状态处理抽取到hook文件      types.ts     # typescript 类型声明      style.css      logo.png      message.ts      constants.ts      index.tsx    HomePage/    ...    index.tsx      # ?应用根组件  hooks/           # ?可复用的hook    useList.ts    usePromise.ts  ...  index.tsx        # 应用入口, 在这里使用ReactDOM对跟组件进行渲染  stores.ts        # redux stores  contants.ts      # 全局常量复制代码

框架官方很少会去干预项目的组织方式，读者可以参考下面这些资源来建立自己项目组织规范:

4.3 脚手架和项目模板

在将项目结构规范确定下来后，可以创建自己的脚手架工具或者项目模板，用于快速初始化一个项目或代码模板。

相关资源:

6 文档规范

文档对于项目开发和维护、学习、重构、以及知识管理非常重要。

和写测试一样、大部分开发人员会觉得写文档是一件痛苦的事情，不过只有时间能够证明它的价值。比如对于人员流动比较大的公司，如果有规范的文档体系，转交工作就会变动非常轻松.

广义的文档不单指‘说明文件’本身，它有很多形式、来源和载体，可以描述一个知识、以及知识形成和迭代的过程。例如版本库代码提交记录、代码注释、决策和讨论记录、CHANGELOG、示例代码、规范、传统文档等等

6.1 建立文档中心

我们公司是做IM的，所以之前我们优先使用’自己的’通讯工具来分享文档，这种方式有很大问题:

如果没有存档习惯(比如后端的API文档，因为由后端维护，一般不会主动去存档), 文档就可能丢失，而且通讯工具是不会永久保存你的文档的。当丢失文件就需要重新和文档维护者索要糟糕的是文档维护者也是自己手动在本地存档的，这样导致的问题是: 如果工作转交，其他开发者需要花费一点时间来查找; 丢失了就真的没了每一次文档更新要重新发一份, 这很麻烦，而且可能出现漏发的情况, 导致前后不一致.关于知识的学习、以及有意义的讨论记录无法归档。

上面介绍的是一种非常原始的文档共享方式，很多小团队就是这么干的。

对于项目本身的文档建议放置在关联项目版本库里面，跟随项目代码进行迭代, 当我们在检索或跟踪文档的历史记录时，这种方式是最方便的。

然而很多应用是跨越多个团队的，每个团队都会有自己的文档输出(比如需求文档、系统设计文档、API文档、配置文档等等)，而且通常也不会在一个版本库里。这时候文档就比较分散。所以一个统一的文档中心是很有必要。

我们公司现在选择的方案是Git+Markdown，也就是说所有的文档都放置在一个git版本库下。之前也考虑过商业的方案，譬如石墨文档、腾讯文档, 但管理层并不信任这些服务。

大概的git项目组织如下:

规范/A应用/  产品/  设计/  API文档/  测试/  其他/B应用/复制代码

Git版本库(例如Gitlab)有很多优势，例如历史记录跟踪、版本化、问题讨论(可以关联issue、或者提交)、多人协作、搜索、权限管理(针对不同的版本库或分组为不同人员设置权限)等等。

Git+Markdown可以满足开发者的大部分需求。但是Git最擅长的是处理纯文本文件、对于二进制是无能为力的，无法针对这些类型的文档进行在线预览和编辑。

所以Git+Markdown并不能满足多样化的文档处理需求，比如思维导图、图表、表格、PPT、白板等需求. 毕竟它不是专业的文档处理工具。所以对于产品、设计人员这些富文档需求场景，通常会按照传统方式或者更专业的工具对文档进行管理.

6.2 文档格式

毫无疑问，对于开发者来说，Markdown是最适合的、最通用的文档格式。支持版本库在线预览和变更历史跟踪。

下面这些工具可以提高Markdown的开发效率:

markdownlint: 编码检查器

扩展(Visual Studio Code):

图表绘制工具:

6.3 定义文档的模板

关于如何写好文档，很难通过标准或规范来进行约束，因为它的主观性比较强, 好的文档取决于编辑者的逻辑总结能力、表达能力、以及有没有站在读者的角度去思考问题。

所以大部分情况下，我们可以为不同类型的文档提供一个模板，通过模板来说明一个文档需要包含哪些内容, 对文档的编写者进行引导.

例如一个API文档可能需要这些内容:

具体规范内容因团队而异，这里点到为止.

扩展:

6.4 讨论即文档

一般情况下，对于一个开源项目来说除了官方文档，Issues也是一个很重要的信息来源。在Issue中我们可以获取其他开发者遇到的问题和解决方案、给官方反馈/投票、关注官方的最新动态、和其他开发者头脑风暴唇枪舌战等等。

所以相对于使用IM，笔者更推荐Issue这种沟通模式，因为它方便归档组织，索引和查找。而IM上的讨论就像流水一样，一去不复返。

当然两种工具的适用场景不一样，你拿IM的使用方式来使用Issue，Issue就会变得很水。Issue适合做有意义的、目的明确的讨论。所以要谴责一下在Github Issue上灌水的开发者。

版权声明 1 本网站名称：捷鹰AI导航
2 本站永久网址：www.jieyingai.com
3 本站原创内容转载请注明出处，付费内容未经本站授权禁止转载二次发布
4 本站所有内容禁止用于任何非法用途！部分文章、素材、资源软件来自网络，仅供大家学习与参考。如有侵权，请联系站长QQ:1392478547进行删除处理
5 本站投稿禁止发布任何违法内容，如发现将立即封号处理，欢迎举报监督
6 本站附件资源、教程等内容如因时效原因失效或不可用，请联系留言或联系站长及时更新

THE END