前端团队的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 流程：

什么是持续集成？它的含义是什么？

我们需要把持续集成单独拆成两个词来理解，什么是连续？ 什么是整合？

连续可以理解为“频繁”或“连续”。 无论是持续集成、敏捷开发思维，还是看板，“持续”都被认为是它们的基础。

举个通俗的例子，比如代码检查，‘连续’的代码检查是指只要代码发生变化就立即检查代码（比如保存，或者IDE实时检查，或者提交到仓库），而‘非连续’ ' 代码检查 所有编码完成后检查即可。 比较两者，我们可以发现，持续的代码检查可以尽早发现错误，并且错误更容易理解和处理。 相反，非连续的代码检查可能会发现一堆错误，甚至最轻微的错误也可能导致数千个错误。 互相纠缠最终会变得难以管理。

“连续性”的概念可以用于软件开发的各个方面。 本质上，它打破了传统的瀑布式软件开发流程，形成更小的开发闭环，不断输出产品。 同时，产品也不断向上游提供反馈和修正。

那么什么是“整合”呢？ 狭义上的集成可以简单地认为是“集成测试”。 集成测试可以静态测试代码，单元测试，单元测试通过后可以进行集成测试，应用集成成一个整体后可以在模拟环境中运行端到端测试等等。即一系列自动化的测试在这里进行测试以验证软件系统。

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

好吧，让我们总结一下为什么持续集成是有益的：

持续集成规范一般定义了这些内容：

定义持续集成脚本模板

常用的CI服务：

GitLab：Gitlab-CI

普遍的

扩张

1.5 任务管理

作为前端负责人，任务管理是必不可少的。 看板是目前最流行的任务管理工具。 它可以帮助我们了解项目的进度、资源的分配、恢复开发现场。

笔者毕业第一年就在一家很小的外包公司工作。 我刚出生的时候并不害怕老虎。 我实际上向我的老板推广了看板和敏捷项目管理。 我想改善项目管理的低效率。 我的老板表示支持，但其他成员却没有多大积极性，结果当然是失败了。

当时我还起草了一份《看板实施规则》，所以我在任务管理方面有了一些经验。

我们来谈谈一些比较有用的工具：

2 技术栈规范

笔者目前所在公司的前端技术栈非常混乱。 三大框架：Vue、React、AngularJS，风格也有很大不同。 当时我就想拿起包裹就走。 关于技术栈不标准的后果，可以参考印度的飞机：

精通这三个框架的人很少，更不用说团队了。

与编程语言一样，三大框架都有自己的设计理念，与库不同。 更换库的成本非常低； 框架的背后是一个架构和一个生态系统。 每个框架背后都涉及开发思维、生态系统、支持工具、最佳实践和性能调优。 精通、精通一个框架的成本是非常高的。

因此，团队的开发效率是建立在稳定、熟练的技术栈之上的。 稳定的技术栈规范有利于团队协作和沟通； 另外，如果团队精通这个技术栈，当出现问题或者需要深度调优的时候，也会相对容易一些。

前端技术栈规范主要包括以下几种：

风格。 包括命名约定、预处理器、方法等。

动画引擎

质量保证。 包括测试、Lint、格式化工具和监控

项目构建工具流程。 例如，webpack、vue-cli

包管理器。 npm、纱线

项目管理工具

时间处理。 例如 Moment.js

模板引擎

开发工具

后端开发框架

工具库

开发/调试工具

ETC。

您可以参考我们团队的技术栈规范。

2.1 技术选型

如何从头开始规范团队的技术栈，或者说如何选型？ 例如，首先确定替代方案。 现在你应该选择Vue还是React（这个话题可能会引起争议）？

前几天正好在SegmentFault上回答过一个问题：我讲了一个例子，几年前我们是如何决定使用React或Vue的（注意，结果并不重要！）：

这篇文章写得很好，给了我一些启发。 结合上面答案的例子，我们来说一下相关技术选择的一些方法（评分项）：

综上所述，在这种情况下，React 获胜。

扩大：

2.2 欢迎新技术

当然，也应该鼓励团队学习新技术，淘汰旧的技术栈。 因为一般来说，新技术或解决方案是为了更高的生产力而诞生的。 在选择新技术时，团队需要考虑以下因素：

就我们团队而言，每个成员都有自己的方向和兴趣领域，所以我们可以分工合作，探索各自的领域，然后分享成果。 如果可靠的话，我们可以先在实验项目中尝试一下。 最后，它被扩展到其他项目。

3 浏览器兼容性规范

前端团队应根据应用面临的用户情况、应用类型、开发成本、浏览器市场统计等因素，制定自己的浏览器兼容性规范，并写入应用手册。

有了浏览器兼容性规范，前端开发和兼容性测试才能有理有据，避免纠纷； 同时，这也是前端团队对外的说法。 除非有特殊要求，前端开发者可以选择忽略。

3.1 确定兼容策略

渐进增强或优雅降级。 这是两种不同方向的策略。 渐进增强保证了低版本浏览器的体验，并为支持新功能的新浏览器提供了稍好的体验； 优雅降级则相反，为现代浏览器提供尽可能最好的体验，而旧浏览器则选择次优，确保近似的功能。

选择不同的策略会对前端开发产生较大的影响，但开发者别无选择。 确定哪种兼容策略应该取决于用户的比例。 如果大多数用户使用现代浏览器，则应使用优雅降级，否则应选择渐进增强。

3.2 确定浏览器评级

YUI曾经提出了浏览器分级原则，这个原则至今仍然适用。 简单来说，浏览器分为多个级别，不同级别代表不同程度的支持。 例如，我们团队将浏览器分为以下三个级别：

一般来说，级别的划分是根据浏览器市场分布、用户比例、开发成本等因素来划分的。

例如，这是我们的管理系统兼容性规范：

3.3 获取统计数据

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

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

一般浏览器统计信息可以从这些地方获得：

判断浏览器是否支持某项功能：

4 项目组织规范

项目组织规范定义了如何组织一个前端项目，比如项目命名、项目文件结构、版本号规范等。特别是对于开源项目，标准化的项目组织就显得更加重要。

4.1 项目组织总体规范

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

CHANGELOG.md：放置各个版本的变化，通常描述各个版本的变化。 方便用户确定应该使用哪个版本。 关于CHANGELOG的规范，请参考保留变更日志

package.json：前端项目所需。 描述当前版本、可用命令、包名称、依赖项、环境限制、项目配置等信息。

.gitignore：忽略不必要的文件，避免将自动生成的文件提交到存储库

.gitattributes：git 配置。 可能需要在此处配置一些跨平台差异，例如换行规则。

docs/：项目的详细文档，可选。

example/：项目的示例代码，可选。

build：项目工具脚本放在这里，不是必需的。如果使用统一构建工具，则没有这个目录

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

src/：源代码目录

test/：单元测试目录。 根据 Jest 规范， __tests__ 目录通常与被测试的模块位于同一父目录中，例如：

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

测试：全局测试目录，通常包含应用程序集成测试或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 脚手架和项目模板

确定项目结构规范后，您可以创建自己的脚手架工具或项目模板，以快速初始化项目或代码模板。

相关资源：

5 编码标准

网上的“前端规范”大多指的是编码规范，是“狭义”的前端规范。

统一的编码标准有利于团队项目的长期维护。 一致的代码标准可以增强团队开发协作效率、提高代码质量、减轻遗留系统维护负担。

最直接的好处就是避免写出糟糕的代码。 糟糕的代码与新手和老手没有什么关系。 我还见过工作多年的“高级”工程师写出恶心的代码。 这样的代码会随着项目的迭代而增加。 将会变得难以控制。

现代 Lint 工具非常先进，可以限制几乎所有类型的编码行为。 比如限制文件长度、功能复杂度、命名约定、注释规范、接口黑名单、DeadCode、检查简单逻辑错误……

每个程序员对“好代码”都有自己的看法。 统一编码标准可以避免不必要的争论和纠纷，就像秦始皇统一战国一样。

事实上，作者建议选择社区制定的标准，而不是自己建立前端编码标准。 这方面的资源有很多，所以本文并没有武断地提出自己的标准建议。 推荐以下资源：

5.1 JavaScript

规格

类型检查。 这里暂时归类，因为它们都属于“静态测试”

5.2 HTML

规格

5.3 CSS

规格

方法

关于CSS，可以学习Bootstrap等传统UI框架。 他们的代码组织得很好，值得学习。

5.4 代码格式化

基本上所有代码格式相关的工作都可以交给Prettier，在此基础上可以使用Eslint来覆盖语义相关的检查。

5.5 综合

5.6 特定于框架的风格指南

5.7 代码审查

上述Lint工具和类型检查器可以约束代码风格并避免低级语法错误。 但即使它通过了上面的 lint 和类型检查，代码也不一定是“好代码”。

具体的自动化工具或文档无法涵盖代码设计中的许多“最佳实践”。 这时候，“经验”或者“群众的智慧”就派上用场了。 例如，代码审查阶段将检查以下内容：

如果这是您第一次实施代码审查，您可以创建一个清单并对照它进行检查。 一旦熟练了，你的脑子里自然就没有代码了。

代码审查有很多好处，例如：

代码审查有两种方式：一种是提交时审查，一种是预约时间审查：

Code Review实施起来比较困难，但是也要看你团队的情况。 我们的团队钱少，工作多，没有时间立即照顾其他成员的代码。 这个时候，定时Review会更有用，因为它会更‘省时间’。

提交时的审查可以针对新手，例如，如果您不信任他们的代码或想要帮助他们提高编码技能。

相关资源：

6 文件规范

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

就像编写测试一样，大多数开发人员发现编写文档很痛苦，但只有时间才能证明它的价值。 例如，对于人员流动性比较大的公司来说，如果有标准化的文件系统，调动工作就会非常容易发生变化。

广义的文档不仅仅指“文档文档”本身。 它有多种形式、来源和载体，可以描述一条知识，以及知识形成和迭代的过程。例如，存储库代码提交记录、代码注释、决策和讨论记录、CHANGELOG、示例代码、规范、传统文件等

6.1 建立文档中心

我们公司是搞IM的，所以之前我们优先使用自己的通讯工具来共享文档。 这个方法有很大的问题：

如果没有归档习惯（比如后端API文档一般不会主动归档，因为是由后端维护的），文档可能会丢失，通讯工具也不会永久保存你的文档。当你文件丢失，需要再次向文档维护者索取。

不好的是文档维护者还手动将其存档在本地。 由此带来的问题是：如果工作被转移，其他开发人员需要花一段时间才能找到它； 如果丢了，那就真的没了。

每次更新文档都要重新下发，非常麻烦，而且可能会漏掉，导致不一致。

知识学习和有意义的讨论的记录无法存档。

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

建议将项目本身的文档放在关联的项目存储库中，并与项目代码一起迭代。 当我们检索或跟踪文档的历史记录时，这种方法是最方便的。

然而，很多应用程序跨越多个团队，每个团队都会有自己的文档输出（例如需求文档、系统设计文档、API文档、配置文档等），并且它们通常不在一个版本存储库中。 这时候的文件就比较分散了。 因此，需要一个统一的文档中心。

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

一般的git项目组织如下：

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

Git仓库（如Gitlab）有很多优点，比如历史跟踪、版本控制、问题讨论（可以与问题或提交相关联）、多人协作、搜索、权限管理（为不同的仓库或不同的人的组设置）权限）等

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

因此，Git+Markdown无法满足多样化的文档处理需求，比如思维导图、图表、表格、PPT、白板等，毕竟它不是专业的文档处理工具。 因此，对于产品、设计师等文档需求丰富的场景，通常采用传统的方式或者更专业的工具来管理文档。

6.2 文件格式

毫无疑问，Markdown 是最适合开发人员且用途广泛的文档格式。 支持存储库在线预览和更改历史记录跟踪。

以下工具可以提高Markdown开发效率：

markdownlint：编码检查器

扩展（Visual Studio 代码）：

图表绘制工具：

6.3 定义文档模板

关于如何写出一份好的文档，很难通过标准或者规范来限制，因为它比较主观。 好的文档取决于编辑的逻辑总结能力、表达能力以及是否能站在读者的角度思考。 。

所以大多数情况下，我们可以为不同类型的文档提供一个模板，通过模板来解释文档需要包含哪些内容，并指导文档编写者。

例如，API 文档可能需要：

具体规格因团队而异，所以我们就到此为止。

扩大：

6.4 作为文档的讨论

一般来说，对于一个开源项目来说，除了官方文档之外，Issues也是一个非常重要的信息来源。 在Issues中，我们可以获取其他开发者遇到的问题和解决方案、给予官方反馈/投票、关注官方最新动态、与其他开发者进行头脑风暴和辩论等。

因此，相比于使用IM，笔者更推荐Issue的沟通方式，因为它方便归档组织、索引和搜索。 IM上的讨论如流水一般，一去不复返。

当然，两种工具的适用场景是不同的。 如果你像IM一样使用Issue，Issue就会变得水汪汪的。 问题适合有意义且有目的的讨论。 所以我要谴责那些充斥Github Issues的开发者。