前端规范制定思维导图模板_ProcessOn思维导图、流程图

为什么需要规范？

降低新成员融入团队的成本, 同时也一定程度避免挖坑

提高开发效率、团队协作效率, 降低沟通成本

实现高度统一的代码风格，方便review, 另外一方面可以提高项目的可维护性

规范是实现自动化的基础

规范是一个团队知识沉淀的直接输出

1 工作流规范

1.1 开发

1.1.1 版本规范

语义化版本规范

主版本号：当你做了不兼容的 API 修改，

次版本号：当你做了向下兼容的功能性新增，

修订号：当你做了向下兼容的问题修正。

1.1.2 版本控制系统规范

制定git分支模型/工作流

git-flow

集中式工作流

功能分支工作流

Fork工作流

参考

1.1.3 提交信息规范

优点

格式统一的提交信息有助于自动化生成CHANGELOG

版本库不只是存放代码的仓库, 它记录项目的开发日志, 它应该要清晰表达这次提交的做了什么. 这些记录应该可以帮助后来者快速地学习和回顾代码, 也应该方便其他协作者review你的代码

规范化提交信息可以促进提交者提交有意义的、粒度合适的'提交'. 提交者要想好要怎么描述这个提交，这样被动促进了他们去把控提交的粒度

规范

Atom

Angular

Eslint

JQuery

工具

conventional-changelog

从项目的提交信息中生成CHANGELOG和发布信息

commitlint

检验提交信息

commitizen

🔥简单的提交规范和提交帮助工具，推荐

standard-changelog

angular风格的提交命令行工具

1.2 构建规范

统一的构建工具链，应该强调"约定大于配置"，让开发者更专注于业务的开发

要求

约定大于配置，开箱即用

vue-cli3抽离了cli service层，可以独立更新工具链

灵活的插件机制，实现独立的更新

特点

强约定，体现团队的规范，暴露最小化的配置接口

集成代码检查、测试等功能

方便升级

工具

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 持续集成

概念

持续(Continuous)

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

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

举例

比如代码检查，‘持续的’的代码检查就是代码一变动(如保存，或者IDE实时检查、或者提交到版本库时)就马上检查代码，而‘非持续’的代码检查就是在完成所有编码后，再进行检查

集成

狭义的集成可以简单认为是‘集成测试’

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

优点

尽早发现错误，快速试错。越早发现错误，处理错误的成本越低

自动化工作流，减少人工干预。人类比机器容易犯错, 而且机器擅长做重复的事情

规范

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

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

执行的任务

划分持续集成的阶段.

检查：包括单元测试和代码lint. 所有push到版本库的代码都会跑这个阶段. 一般可以在提交title中包含[ci skip]来跳过这个阶段

构建: 对前端项目进行构建. 只有打上版本tag的提交或release分支会跑构建任务

发布: 将前端的构建结果进行交付/发布. 只有打上版本tag的提交或者release分支在构建成功后会跑发布任务

定义持续集成脚本模板

cli服务

Github

Travis CI

CircleCI

完整列表

GitLab: Gitlab-CI

通用

Jenkins

持续集成更详细解释

1.5 任务管理

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

工具

基于issue看板 - 可以基于Gitlab或Github的Issue来做任务管理，它们都支持看板。很Geek，推荐

Tower - 专门做看板任务管理的。小团队基本够用。我们现在就使用这款产品

teambition - 和Tower差不多，没有深入使用过

Trello - 颜值高.

阿里云看板

腾讯云看板

2 技术栈规范

2.1 技术选型

选择你最熟悉的技术

选择拥有强大生态和社区支撑的开源技术

选择成长期的技术

API的稳定性

基础设施配合

业务考虑

选型需要充分地理解业务，理解用户需求，当下需要解决的首要问题，以及可能的风险有哪些，再将目标进行分解，进行具体的技术选型、模型设计、架构设计

参考文档

谈谈技术选型

谈谈技术选型的注意事项

2.2 迎接新技术

学习成本

考虑团队成员的接纳能力。如果成本小于收获的利益，在团队里面推行估计阻力会比较大

收益

是否能够解决当前的某些痛点

考虑风险

一般我们不能将一个实验阶段的技术使用的生产环境中

规范包括

编程语言 - Typescript或Javascript

UI框架及其配套生态, 以及备选方案。其背后的生态非常庞大:

UI框架

路由

状态管理

组件库

国际化

动画

服务端渲染

脚手架、CLI工具

组件测试

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

动画引擎

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

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

包管理器。npm、yarn

项目管理工具

时间处理。例如Moment.js

模板引擎

开发工具

后端开发框架

工具库

开发/调试工具

3 浏览器兼容规范

概念

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

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

3.1 确定兼容策略

渐进增强

渐进增强保证低版本浏览器的体验，对于支持新特性的新浏览器提供稍好的体验

优雅降级

优雅降级则是相反的，为现代浏览器提供最好的体验，而旧浏览器则退而求之次，保证大概的功能.

3.2 确定浏览器分级

完全兼容: 保证百分百功能正常

部分兼容: 只能保证功能、样式与需求大致一致。对于一些不影响主体需求和功能的bug，会做降低优先级处理或者不处理。

不兼容: 不考虑兼容性

3.3 获取统计数据

大厂支持的监控平台

百度统计

友盟

Google Analytics 需要kx上网

通用的浏览器数据统计

百度流量研究院：主要提供国内浏览器统计

statcounter: 国际浏览器统计

浏览器发布年份统计

获取浏览器支持特性网站

caniuse

MDN

html5test

4 项目组织规范

4.1 通用的项目组织规范

README.md: 项目说明, 这个是最重要。你必须在这里提供关于项目的关键信息或者相关信息的入口.

简要描述、项目主要特性

运行环境/依赖、安装和构建、测试指南

简单示例代码

文档或文档入口, 其他版本或相关资源入口

联系方式、讨论群

许可、贡献/开发指南

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

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

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

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

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

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

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

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

src/: 源代码目录

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

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

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

.env 通用的环境变量

.env.development 开发环境的环境变量

.env.production 生成环境的环境变量

.env.*.local 本地覆盖以上配置

（开源）LICENSE: 说明项目许可

（开源）.github: 开源贡献规范和指南

CONTRIBUTING: 贡献指南, 这里一般会说明贡献的规范、以及项目的基本组织、架构等信息

CODE_OF_CONDUCT: 行为准则

COMMIT_CONVENTION: 提交信息规范，上文已经提及

ISSUE_TEMPLATE: Issue的模板，github可以自动识别这个模板

PULL_REQUEST_TEMPLATE: PR模板

4.2 目录组织的风格

Rails-style

按照文件的类型划分为不同的目录

Domain-style

按照一个功能特性或业务创建单独的目录，这个目录就近包含多种类型的文件或目录

Ducks-style

通常将相关联的元素定义在一个文件下

混合

4.3 脚手架和项目模板

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

参考

yeoman - 老牌的项目脚手架工具

plop - 代码生成辅助CLI

hygen - 类似于plop

generact - 生成React组件, 大部分组件的文件结构差不多, 这个工具就是帮助你生成这些重复的代码

babel-code-generator - 利用babel来实现更高级的代码编辑和自动生成

5 编码规范

5.1 Javascript

Lint工具

ESLint - 🔥目前是社区最流行的、通用的Javascript Lint工具，Lint界的Babel。支持定制插件、preset。如果不想折腾可以选择它的一些预定义配置

TSLint - Typescript Lint工具。不过即将废弃了, 推荐使用ESLint

规范

JavaScript Standard Style - 🔥 零配置的、‘标准’的Javascript编码规范. 底层基于Eslint。目前不支持Typescript

Airbnb JavaScript Style Guide - Airbnb的编码规范，业界标杆

类型检查. 暂时将它们归类到这里，因为它们同属于‘静态测试’

Typescript - 🔥 Javascript语言的超集，这是一门‘新’的语言，而不是简单的类型检查器. 不过它也支持原生Javascript的类型检查

Flow - Facebook出品的类型检查器，语法和Typescript类似. 个人推荐使用Typescript

5.2 HTML

Lint工具

HTMLHint

bootlint

规范

Code Guide

5.3 CSS

Lint工具

stylelint - 🔥 通用的CSS编码检查工具，支持最新的CSS语法、CSS-in-js、以及其他类CSS语法(如SCSS、Less). 它也有预定义配置，推荐使用

规范

Airbnb CSS / Sass Styleguide

Code Guide

更多

方法论

BEM - 🔥 BEM命名规范

OOCSS

smacss

5.4 代码格式化

Prettier

5.7 Code Review

检查清单

编程原则、设计思想. 例如符合SOLID原则? 是否足够DRY？接口设计是否简洁易扩展、

模块耦合程度、代码重复

代码健壮性。是否存在内存泄露、是否线程安全、是否有潜在性能问题和异常、错误是否被处理

代码的性能和效率。

是否有没有考虑到的场景？

好处

Code Review可以让其他成员都熟悉代码。这样保证其他人都可以较快地接手你的工作，或者帮你解决某些问题

提高代码质量。毫无疑问. 一方面是主动性的代码质量提升，比如你的代码需要被人Review，会自觉尽量的提高代码质量；另一方面，其他成员可以检查提交方的代码质量

检查或提高新成员的编程水平。培养新人时，由于不信任它们提交的代码，我们会做一次Review检查代码是否过关。另一方面这是一次真实的案例讲解, 可以较快提高他们的能力

方式

提交时. 大部分开源项目采用这种方式。通俗讲就是Pull Request。只有代码通过测试、和其他成员的Review才可以合进正式版本库。这种方式也称为‘阻塞式’代码检查，一般配合GitFlow使用。

定时. 在项目完结后、项目的某个里程碑、或者固定的时间(每天、每个星期..). 团队成员聚在一起，回顾自己写的代码, 让其他成员进行审查

参考

是否要做Code Review？与BAT资深架构师争论之后的思考

6 文档规范

6.1 建立文档中心

方式

石墨文档

腾讯文档

Git+Markdown

6.2 文档格式

对于开发者来说，MarkDown是最适合的

6.3 定义文档的模板

为不同类型的文档提供一个模板，通过模板来说明一个文档需要包含哪些内容, 对文档的编写者进行引导.

举例API文档

接口的索引

接口的版本、变更记录

用法和整体描述, 认证鉴权等等

描述具体的接口

功能说明

方法名称或者URI

参数和返回值定义

调用示例

注意事项等等

6.4 讨论即文档

方式

issue

方便归档组织，索引和查找

话题记录示例

设计方案

决策/建议

新功能、新技术引入

重构

性能优化

规范

问题讨论

重大事件

计划或进度跟踪

标签管理

IM

像流水一样，一去不复返

6.5 注释即文档

必要和适量的注释对阅读源代码的人来说就是一个路牌, 可以少走很多弯路.

ESlint是可以对注释进行一定程度的规范

6.6 代码即文档

工具会分析代码的数据类型，自动帮我们生成参数和返回值定义，这也可以减少很多文档编写工作以及出错率

工具

API文档

Typescript

tsdoc Typescript官方的注释文档标准

typedoc 基于tsdoc标准的文档生成器

Javascript

jsdoc Javascript文档注释标准和生成器

后端接口文档

Swagger Restful接口文档规范

GraphQL: 这个有很多工具，例如graphiql, 集成了Playground和文档，很先进

Easy Mock 一个可视化，并且能快速生成模拟数据的服务

组件文档

StoryBook 通用的组件开发、测试、文档工具

React

Docz

Styleguidist

Vue

vue-styleguidist

7 UI设计规范

意义

提供团队协作效率(产品和开发)

提高组件的复用率. 统一的组件规范可以让组件更好管理

保持产品迭代过程中品牌一致性

8 测试规范

整体测试

单元测试: 对独立的软件模块进行测试

UI组件测试: 包括了快照(Snapshot)测试

集成测试: 在单元测试的基础上，将模块组合起来，测试它们的组合性

E2E测试: 在完整、真实的运行环境下模拟真实用户对应用进行测试。主要测试前端和后端的协调性

兼容性测试: 上面提到了浏览器兼容规范，在将版本提交给测试/发布之前，需要确保能符合兼容性要求

性能测试: 测试和分析是否存在性能问题

其他:

安全测试

SEO测试

8.1 测试的流程

8.2 单元测试

好处

提高信心，适应变化和迭代. 如果现有代码有较为完善的单元测试，在代码重构时，可以检验模块是否依然可以工作, 一旦变更导致错误，单元测试也可以帮助我们快速定位并修复错误

单元测试是集成测试的基础

测试即文档。如果文档不能解决你的问题，在你打算看源码之前，可以查看单元测试。通过这些测试用例，开发人员可以直观地理解程序单元的基础API

提升代码质量。易于测试的代码，一般都是好代码

测试指标

测试覆盖率来量化

比如要求语句覆盖率达到70%；核心模块的语句覆盖率和分支覆盖率都要达到100%. 视团队情况而定

工具

Headless Browsers: 无头浏览器是网页自动化的重要运行环境。常用于功能测试、单元测试、网络爬虫

puppeteer

Headless Chromium

测试框架

Jest 🔥Facebook的单元测试框架. 零配置, 支持组件快照测试、模块Mock、Spy. 一般场景, 单元测试学它一个就行了

组件测试

testing-library 🔥

Enzyme

Intern

单元测试

AVA

Jasmine

Mocha

Tape

断言库

Chai

expect.js

should.js

Mock/Stubs/Spies

sinon.js

代码覆盖率

istanbul

基准测试

benchmark.js

jsperf.com

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

9.1 异常处理

参考

9.2 日志

规范（示例）

避免重复打印日志

谨慎地记录日志, 划分日志级别。比如生产环境禁止输出debug日志；有选择地输出info日志；

使用前缀对日志进行分类, 例如: [User] xxxx

只记录关键信息, 这些信息可以帮助你诊断问题

9.3 异常监控

处理

浏览器兼容性。

碎片收集(breadcrumbs)。收集‘灾难’现场的一些线索，这些线索对问题诊断很重要。例如当前用户信息、版本、运行环境、打印的日志、函数调用栈等等

调用栈的转换。通常在浏览器运行的压缩优化过的代码，这种调用栈基本没什么可读性，通常需要通过SourceMap映射到原始代码. 可以使用这个库: source-map

数据的聚合。后端监控系统需要对前端上报的信息进行分析和聚合

10 前后端协作规范

10.1 协作流程规范

典型的工作流程

详细

需求分析。参与者一般有前后端、测试、以及产品. 由产品主持，对需求进行宣贯，接受开发和测试的反馈，确保大家对需求有一致的认知

前后端开发讨论。讨论应用的一些开发设计，沟通技术点、难点、以及分工问题.

设计接口文档。可以由前后端一起设计；或者由后端设计、前端确认是否符合要求

并行开发。前后端并行开发，在这个阶段，前端可以先实现静态页面; 或者根据接口文档对接口进行Mock, 来模拟对接后端接口

在联调之前，要求后端做好接口测试

真实环境联调。前端将接口请求代理到后端服务，进行真实环境联调。

10.2 接口规范

注意的点

明确区分是正常还是异常, 严格遵循接口的异常原语. 上述接口形式都有明确的异常原语，比如JSONRPC，当出现异常时应该返回错误对象响应，而不是在正常的响应体中返回错误代码. 另外要规范化的错误码, HTTP响应码就是一个不错的学习对象

明确数据类型。很多后端写的接口都是string和number不分的，如果妥协的话、前端就需要针对这个属性做特殊处理，这也可能是潜在的bug

明确空值的意义。比如在做更新操作是，空值是表示重置，还是忽略更新？

响应避免冗余的嵌套。

接口版本化，保持向下兼容。就像我们上文的‘语义化版本规范’说的，对于后端来说，API就是公共的接口. 公共暴露的接口应该有一个版本号，来说明当前描述的接口做了什么变动，是否向下兼容。

现在前端代码可能会在客户端被缓存，例如小程序。如果后端做了break change，就会影响这部分用户。

标准定义的接口形式

RESTful: RESTful是目前使用最为广泛的API设计规范, 基于HTTP本身的机制来实现，大部分开发者未深入理解，设计的接口参差不齐，容易产生分歧

JSONRPC 这是一种非常简单、容易理解的接口规范，上手快，简单

GraphQL 🔥更为先进、更有前景的API规范，难度很高

10.3 接口文档规范

包含的信息

版本号

文档描述

服务的入口. 例如基本路径

测试服务器. 可选

简单使用示例

安全和认证

具体接口定义

方法名称或者URL

方法描述

请求参数及其描述，必须说明类型(数据类型、是否可选等)

响应参数及其描述, 必须说明类型(数据类型、是否可选等)

可能的异常情况、错误代码、以及描述

请求示例，可选

10.4 接口测试与模拟

理想模型

Mock Server给前端提供模拟数据

Mock Client则辅助后端对它们的接口进行测试.

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

11.1 新人培训

团队新成员培训手册

产品架构与组织架构

介绍公司背景和产品，一般组织的团队结构和产品的架构是相关联的

产品研发流程

介绍产品开发和迭代会涉及到的流程、以及团队之间的协作衔接

工作范围

团队成员的职责范围

建立资源索引

开发需要设计到的资源，比如各种文档地址、研发系统入口(例如gitlab、bug跟踪系统、文件共享、发布平台、开发/测试环境、监控系统)、协作规范等等

规范:

有规范可循，可以让成员以较快的速度入手开发、同时也减少培训成本投入。

11.2 营造技术氛围

写文

鼓励成员写技术博客，或者建立自己的团队专栏. 写一篇好的文章不容易

鼓励参与开源项目

建立面试题库

组织一起解一些面试题或算法题，加深对知识点的理解

定期的专题分享.

鼓励团队成员定期进行专题学习和研究，编写技术博客，并将学习的成果分享给其他成员. 这是一种抱团取暖的学习方式，旨在帮助团队成员一起学习和成长。

比如开发老手可以分享自己的经验，研究更深层次的技术；新手则可以研究某些开发技巧、新技术，例如CSS Grid，svg动画等等。推荐团队成员有个明确的研究领域，这样分工合作可以学习到更多东西.

专题怎么来?

专题请求. 可以请求其他成员完成专题，比如比较深的知识，可以要求团队比较有经验的进行学习分享

学习总结.

项目回顾

难点攻克

项目规范

工具使用

落实和完善开发规范

. 规范本身就是团队知识沉淀的一种直接输出

图书分享.

和离散的文章或教程相比，图书的知识会比较系统，另外很多经典的图书是要静下来好好欣赏的。

鼓励重构和持续优化代码

抽象一套基础库或框架，减少重复工作, 提高工作效率. 不加班先从提高工作效率开始