作者：易师傅、github

声明：文章为稀土掘金技术社区首发签约文章，14天内禁止转载，14天后未获授权禁止转载，侵权必究！

前言

大家好，我是易师傅，一个专门搞前端的搬砖师傅 ~

在上一篇文章《非大厂的我们，要如何去搞基建》中主要带领了大家入门了 如何搞基建，以及基建都有什么；

写文章就要踏踏实实，正所谓：大饼画的再多，吃不到也是白瞎，下面正式开始我们的规范篇 ~

一、场景重现

如果 Leader 在某次 Code Review 时，发现你的代码是如下这样子的；

问：如果 Leader 让你优化，你会如何优化呢？

- 你是选择无视他（Leader），还是无视它（Code）？

// 点击定位按钮，获取县市地址方法
const clickDw = function(type) {
    let dz
    // 地址列表
    let dzTable = ['北京市'，'上海市', '广州市', '深圳市']

    if(type === 1 || type === 2 || type === 3) {
	// do something
	return dz
    } else if (type === 4 || type === 5) {
	// do something
	return dz
    } else {
	// default
	return dz
    }
}
复制代码

咱们可以从这几方面入手：

命名是否规范？
- 方法名 clickDw 可否用 getLocation 代替？
- 变量名 dz 可否变成 address？
- 地址列表可否用 addressList 代替？
if 判断是否可以简化？
- if(type === 1 || type === 2 || type === 3) 可以用 [1, 2, 3].includes(type) 代替吗？
亦或还有其它优化空间？
- 是否需要 else if ?
大家觉得还有其它优化空间吗？
- 欢迎讨论

二、团队存在的问题

我相信许多中小型公司都会面临下面几个问题：

1. 老旧业务代码的技术负债：

由于历史原因，仍旧还有一些老业务在旧项目中运行（想改又不敢改）；
所以这种技术负债就必不可少了，例如同个页面多个 jQuery 版本，多个不同的 UI 组件库，代码 n 种格式化等等的问题；

2. 要研发进度，不要研发质量：

在需求进度的催促下，许多同学的代码逻辑以及代码质量可以说是一塌糊涂了；
这时候在进度与质量中到底如何取舍就耐人寻味了 ~

3. 无 GitFlow 协同工作流：

Git 的使用仍旧停留在 commit、pull、push 等简单使用中；
或者还在用 SVN；

4. 团队更迭文档负债：

存在最大的问题就是对一些老旧业务的不熟悉；因为人员的更迭，许多业务产品无记录、代码无注释，导致许多业务逻辑只能靠猜，极大的降低了团队的研发效率；

5. 后端接口文档的缺失：

接口文档有多重要，就不需要我说了吧，在座的每个前端大佬们应该深有体会；

6. 沟通少，导致效率低

可以少沟通，但是聊天工具永远无法比当面沟通有效率 ~

7. 研发与产品的爱恨情仇：

上联：兵熊熊一个
下联：将熊熊一窝
横批：懂的都懂 ~

正是由于这些问题的存在，从而 影响到团队之间的协作，使团队的效率整体降低，严重的甚至会影响团队和谐；

可想而知 牵一发而动全身 究竟有多大力量了吧！

其实作为一名 “优秀” 的程序员，写的代码无论是可读性、可维护性 还是可复用性 都是必不可少的；

那么如何去写 可读性、可维护性、可复用性 的代码呢？

就值得我们每个人深思熟虑了；

接下来我们带着疑问一起进入规范的世界！

三、规范的定义

规范包含的内容有许多，不同公司在针对现有团队所做的规范标准或许会有出入；

但无论是技术栈的统一，还是代码质量的把控，还是 Git 的钩子函数，亦或者团队文档的输出等等，其实都可以归纳至规范的范畴；

所以咱们可以这么定义（仅限笔者理解）：

在日常开发中，任何能 提高代码可维护性、降低代码理解成本、提高代码的容错率 和 提高项目可扩展性 的统一标准，称之为 规范标准；

四、规范的好处

1. 代码的一致性

2. 降低开发成本

3. 提升团队效率

4. 减少沟通成本

5. 有助于自身成长

6. 提高团队和谐（Code Review）

笔者个人见解：养成编写代码规范的习惯，有助于程序员自身的成长；

五、前端规范都有什么？

因为文章主要讲的是与前端相关，所以下面所述主要是前端相关的主题；

关于前端规范，我大致划分出了下列的内容，具体实施还需以自身公司实际情况为准；

前端规范.png

下面让我们一起去看看吧！

1. 前端命名规范

命名 有多重要，我相信每位工程师都能明白其中的重要程度；

一个不好的命名，可能就会引起别人的错误理解；

遵循一套严格的命名规范，无论是对自己还是接手的他人，都会大大降低代码的维护成本，所以想要成为一名合格的前端开发，命名规范是必须的；

一些常见的不规范命名：

单词拼写错误：到底是 form 还是 from ？
中英文混用：到底用 dzTable 还是 addressList 呢？
以 1-9，a-z 命名：不同类型直接用 type1、type2、type3？
混用命名格式：一会 addressList 一会 addresslist 一会 addresses，这样不太好吧？
单复数不分: 到底 address 还是 addresses 啊？到底是 photoes 还是 photos 啊？
正反义词错用：到底用 showDialog 还是 isDialog 还是 visibleDialog 啊啊啊啊？

WX20220924-155645@2x.png

一些常见好的命名：

驼峰式命名法介绍：
- Pascal Case 大驼峰式命名法：首字母大写；
  - eg：StudentInfo、UserInfo、ProductInfoCamel
- Case 小驼峰式命名法：首字母小写；
  - eg：studentInfo、userInfo、productInfo
文件资源命名：
- 文件名不得含有空格；
- 文件名建议只使用小写字母，不使用大写字母；
- 名称较长时采用半角连接符(-)分隔；
```
    usr/dev/document/front-end/project-vue3
复制代码
```
变量命名：
- 命名方式 : 采用小驼峰式命名方法；
- 命名规范 :
  - 普通变量(number, string, date)；
  - 布尔类型：需要一个标识变量含义的前缀，比如has, is, wether, can, should等；
  - 数组/集合等复数形式：最好以s或list等能够标识复数形式的后缀结尾，标识当前变量是复数形式，提高可读性；
- 常量全部大写，且用下划线来分割单词，eg：MAX_LENGTH = 1
函数：
- 命名方式 : 小驼峰方式 lowerCamelCase ( 构造函数使用大驼峰命名法 )
- 命名规则 : 前缀为动词，动词 eg：add / update / delete / detail / get
```
// 更新数据
function updateData(){
    return {};
}

// 获取用户信息
function getUserInfo{
    return {}
}
复制代码
```
css 命名：
- 样式类名使用小写字母，以半角连接符(-)分割；
- id 采用驼峰式命名；
- scss / less 中的变量、函数、混合、placeholder 采用驼峰式命名
```
.heavy {
  font-weight: 800;
}
.important { 
  color: red; 
}
复制代码
```

2. 技术栈规范

问答题，请选出下列合适的答案：

到底是用 TypeScript 还是 JavaScript ？
到底是用 Vue 还是 React ？
到底是用 Less 还是 Sass ？
到底是用 Webpack 还是 Vite ？
到底是用 Koa 还是 Express ?
……

我相信不同的人肯定都有不同的答案，因为在不同的公司技术栈肯定是不一致的，技术栈不仅取决于领导的拍案叫板，也取决于业务的支持，所以会出现同一个业务部门会有不同的技术栈的情况；

我司选择答案：

为什么用 TypeScript 而不用 JavaScript 呢？
- 静态类型语言要较于动态类型语言更安全；
- TypeScript 代码更可靠且更易于重构；
- TypeScript 更明确类型；
为什么用 Vue 而不用 React ？
- 这是一个容易引战的话题；
- 所以我们的答案是：领导让用
为什么用 Sass 而不是 Less ？
- Sass 功能齐全；
- 不仅有变量和作用域，还有函数和进程控制的概念；
- 更像一门正规的编程语言；
为什么用 Vite 而不是 Webpack？
- 开发效率极高 —— 🚀 般的速度；
- 上手极其简单；
- 社区成本低；
- 目前业务内所有项目已慢慢转为 Vite 构建；

注意：使用新技术前要考量其学习成本、带来的收益以及存在的风险等等，切勿盲目追行情。

3. 编程规范

为什么需要编程规范？

实际开发中因为没有规范而导致的问题真的不要太多太多；有因为 JavaScript 不规范的，也有因为 CSS 不规范的；

但是我们究其原因，无非就是没有一个所谓的统一标准而导致；

正所谓：无规矩不成方圆，有了规范才有好的团队~

编程规范的意义：

统一团队的编码规范，有助于代码的维护；
提升编码效率；
减少沟通成本；
提升团队气氛；
有利于 Code Review；

编程规范都有什么？

编程规范.png

怎么搞编程规范？

确定现有团队的问题；
定制属于自己公司的规范（从上面导图入手）；
统一规范应以自动化为前提；
- Eslint、Prettier、Stylelint 自动化必不可少；
- 如不满足可自定义自动化工具规范（后面文章会讲到）；

推荐几个编程规范文档

4. Git 规范

为什么要 Git 规范？

在实际开发中，无论是 Git 版本的规范，还是 Git Commit 的规范，都是一环较重要的部分，因为他们绝对是大有裨益的；

方便跟踪工程历史；
方便快速回溯代码；
方便 Code Review；
方便生成 CHANGELOG；
提高项目的整体质量，提高个人工程素质；

如何去做 Git 规范？

Git 版本规范

版本规范其实有许多种工作流形式，有 Git flow，有集中式工作流，有功能分支工作流；

这里主要说一下较为常用的 功能分支流；

功能分支工作流是以集中式工作流为基础的。它提倡为各个新功能分配一个专门的分支来开发，当功能分支稳定，或者说经过完备的测试之后才合并到 master 分支。

功能分支工作流相较集中式工作流的优点：
- 保持主干的干净。隔离了多个开发者在各自功能上的开发不会扰乱主干代码
- 提供了Code Review的空间。功能分支在合并到主干之前，触发集成测试，或者开启Pull Request, 启动一个围绕分支的讨论。发挥群众的力量
Git Commit 规范
- 统一格式：
```
<type>(<scope>): <subject>
// 注意冒号 : 后有空格
// 如 feat(user): 增加用户中心的 xx 功能
复制代码
```
- scope 表示 commit 的作用范围，如用户中心、购物车中心，也可以是目录名称，一般可以限定几种；
- subject 用于对 commit 进行简短的描述；
- type 必填，表示提交类型，值一般有以下几种：
  - feat：新功能 feature
  - bug：测试反馈 bug 列表中的 bug 号
  - fix：修复 bug
  - ui：更新UI；
  - docs：文档注释变更
  - style：代码格式(不影响代码运行的变动)；
  - refactor：重构、优化(既不增加新功能，也不是修复bug)；
  - perf：性能优化；
  - release：发布；
  - deploy：部署；
  - test：增加测试
  - chore：构建过程或辅助工具的变动
  - revert：回退
  - build：打包

结合工具强制使用 Git Commit 规范：

使用 commitlint 、commitizen 和 husky 来进行提交检查；
使用 commitlint-config-cz 规范命令行提示消息（可选）；
使用 conventional-changelog 提交日志

5. BFF 研发规范

BFF 的设计原则：

BFF 为前端而生，关注点在提升前端用户体验；
BFF 不承载业务能力，业务逻辑要下沉到合适的后端服务中；
BFF 不承载特定技术能力，必要时可以建立专门的服务承载，如文档打印、Excel生成、算法逻辑等；
BFF 不做后端服务的集成层，某个后端服务的数据变更需要同步到其他服务，不能通过BFF实现；

前端研发原则：

BFF 是为前端设计的后端，不可图一时之方便而越俎代庖，将大部分本该由后端服务提供的能力据为己有，而更应该关注在前端的体验优化上，做好前后端的隔离，让前后端能够各司其职，合理高效协作。

接口数据返回统一原则

场景：某天 A 同学返回的数据是 msg，但是 B 同学的是 message，所以就会有出入

优化：统一一致的数据格式
微服务接口聚合原则

场景：代码中为了统一成一个接口，BFF 把后端十几个微服务接口聚合成一个，这样对性能有沉重的打击；

优化：秉承五合一原则，即单个接口至多只能聚合五个微服务接口；
业务下沉原则

场景：例如某些需要详细计算的业务逻辑，例如金额的计算等等；

优化：需下沉至后端服务

后端研发原则：

微服务业务单一原则

场景：业务 A 中某个微服务中聚合的业务场景过多，导致对微服务拆分不过细致，对请求效率与维护有一定的影响；

优化：一个业务对应一个微服务
与前端同步原则

场景：某个业务场景中，BFF 需要聚合很多接口，但是 BFF 层前端同学对微服务的业务划分不是很清晰，所以他们在拆分接口时会有些随心所欲，任性聚合；

优化：单个需求业务场景，需与前端同学规划好哪些微服务的接口可以聚合在一起，哪些微服务接口聚合会存在影响；

现在看不懂没关系，详细 BFF 相关文章会在《前端搞基建》专栏中后续输出，敬请期待 ~

6. 前后端协作规范

场景重现：

前后端协作规范-场景.png

为什么要前后端协作规范？

随着 前后端分离开发模式 的流行，前端和后端已经在各自领域上渐行渐远；

我们把前后端共同研发的一个需求所产生的关联称之为 联调；

美其名曰联调，如何去把控好这个联调的品质就是我们值得关注的点了 ~

稍不注意就很可能产生不必要的问题。

因此，咱们就很有必要 制定前后端协作规范 来解决这些问题了 ~

前后端协作规范的意义：

提高开发效率；
降低沟通成本；
提升团队和谐；

前后端协作规范都有什么？

协作规范流程
- 需求分析。确保大家对需求有一致的认知；
- 设计接口文档。前端需要确认是否符合要求；
- 并行开发。前端需要根据接口文档进行Mock, 模拟对接后端接口；联调之前，要求后端做好接口测试；
- 真实环境联调。前端将接口请求代理到后端服务，进行真实环境联调；
接口规范
- 接口风格使用 RESTful 风格；
- 请求方法规范：
  - GET：获取对应的信息；
  - POST：用于创建或者某些资源的提交；
  - UPDATE：更新某些资源；
  - DELETE：删除某个资源；
  - OPTIONS：对请求的校验，与 POST 配合；
- 其它规范：
  - URI 结尾不应包含（/）；
  - 正斜杠分隔符（/）必须用来指示层级关系；
  - 应使用连字符（-）来提高URI的可读性
  - 不得在URI中使用下划线（_）；
  - URI路径中全都使用小写字母
  - 具体详见：RESTful 架构详解
- 接口文档规范：
  - 版本号；
  - 接口注释与字段的描述；
  - 具体接口定义：
    - 方法名称或者 URI
    - 方法描述
    - 请求参数及其描述，必须说明类型(数据类型、是否可选等)
    - 响应参数及其描述, 必须说明类型(数据类型、是否可选等)
    - 可能的异常情况、错误代码、以及描述
    - 请求示例，可选
注意点：
- 明确数据类型、空值的意义以及默认值；
- 对于大数字（整数大于 16 位、浮点数大于 18 位）做字符串处理；
- 关于日期时间格式；
- 响应避免冗余的嵌套；
- 接口版本化，保持向下兼容；接口不兼容时需升级版本；
- 鉴权通过header实现；
- 其它……

以上规范摘抄了一些较为通用的部分规范，规范因团队而已 ~

7. UI 设计规范

场景复现：

依稀记得刚进公司时，不同的业务小组弹框右上角的 close 按钮样式大小都不一样；每次要么重写 css ，要么直接重新引入一张新的 close 图，严重影响了大家的开发的效率；

UI设计规范-场景.png

设计规范的意义与目的：

统一样式风格；
提高组件的复用；
提升研发效率；
提升团队协作能力；
保持产品迭代过程中品牌一致性；

设计规范都有什么？

设计规范.png

8. 前端测试规范

为什么前端测试不那么被重视？

就前端而言，前端测试一般可以划分为 针对 UI 的测试，以及面向于组件工具库的测试；

因为所谓「前端」涵盖的领域相对后端形态更加多样化；

在组件工具库：自动化测试十分普及且必要；
在面向于 UI 侧：自动化测试等相关就不怎么普及；

归根结底一句话就是：前端页面变化太大，性价比低；

为了提升研发周期，快速迭代相关产品，我相信大部分的企业或开源项目只有在针对组件工具库时才会做 单元测试；

前端测试规范的意义

减少成本与开发量；
写出更高质量的代码；
重构或者重写代码的可靠度更高；
前端流程更加规范；

前端测试的三大类：

单元测试：
- 单元测试是最基础的自动化测试，用来检测项目当中的最小可测单元，例如工具函数、基础组件等
集成测试：
- 集成测试，也叫组装测试或联合测试。在单元测试的基础上，将所有模块按照设计要求（如根据结构图）组装成为子系统或系统，进行集成测试。
UI 测试：
- 测试用户界面的功能模块的布局是否合理，整体风格是否一致和各个控件的放置位置是否符合客户使用习惯，更重要的是要符合操作便捷，导航简单易懂，界面中文字是否正确，命名是否统一，页面是否美观，文字、图片组合是否完美。

前端测试的常用工具：

mocha：Mocha 是一个功能丰富的 JavaScript 测试框架；
jest：facebook 出的一款JavaScript 自动化测试框架，专注于简单性。
vitest：尤大团队打造，一个由 Vite 打造的单元测试框架，而且它很快！

9. 浏览器兼容规范

场景复现：

浏览器规范-场景 (1).png

浏览器兼容规范的意义

提升研发效率；
促进团队和谐，不用为兼容而存在争议；

如何搞浏览器兼容规范？

前端团队应该根据 用户设备类型 、实际开发成本、浏览器市场份额等因素来制定对应的浏览器兼容规范；

从开发成本出发：
- 假设在兼容 IE 低版本的浏览器的情况下，是否会对开发效率、网站性能、用户体验都会有影响？
从用户设备类型出发：
- 判断用户设备类型，一般就需要借助自研的 前端数据埋点系统（后续文章会讲解） 或者市面上现成的统计平台，例如百度统计、友盟、谷歌的 Google Analytics；
- 即可判断出用户设备的使用情况，如下图（我司）谷歌 GA 的分析图:
从浏览器市场份额出发（如图所示）
- 全球浏览器市场份额（2022-09）：
- 中国浏览器市场份额（2022-09）：

友情提示：IE 已死，拿着它赶紧去说服你领导吧 ~

10. IDE 编辑器规范

场景复现：

IDE 编辑器规范-场景 1.png

IDE 编辑器规范的意义

统一配置，方便开发；
规定团队编码风格；
规范对应插件；

前端 IDE 编辑器规范都有什么

IDE编辑器规范.png

11. 需求研发流程规范

为什么需要需求研发流程规范？

讨论题：

某日， A 同学的需求研发快要完毕，产品突然要求修改需求，那么身为当事人的你应该怎么做呢？

这就导致了在没有流程规范前，产品想让你改，你就得去改了；但是有了流程规范呢，那是不是就不一样了，虽然还是会修改需求，但是最起码会有迹可寻；

研发流程规范的意义与目的：

提升效率；
明确目的；
改善产品与研发的关系；
融洽团队氛围；

整体的研发流程规范（其中轻化产品部分的流程）：

需求研发规范流程.png

关于需求变更处理建议：

重视原型稿评审，重视需求确认；
需求评审的时候产品尽量多提问题，多思考各种场景，收集更广泛的意见，切不可一意孤行；
无论是研发还是产品需锻炼自己快速判断价值和优先级的能力，影响不大的变更就不要提了；
对于需求变更处理，要有原则，并不是所有的变更都要立即接受处理（可从 人力成本与时间成本考虑）；
对于重大缺陷，或越往后期改动成本越大的，可优先处理；
对于一些不影响使用的优化或需求，建议列入下一个版本计划；
所有的需求变更，需要在项目管理工具（tapd、禅道、ones）里记录；

12. CR 规范（Code Review）

看到这里，其实我们已经制定了一系列的前端规范了；

虽有规范，但是如何去约束到团队的每个成员其实是一个困扰大家的难题；

但是 Code Review 一直都是软件开发中的最佳实践之一，可以有效提高整体代码质量，及时发现代码中可能存在的问题。

像国外的 Google、微软以及国内的大厂等等公司，Code Review 都是基本要求，代码合并之前必须要有人审查通过才行。

Code Review.png

Code Review 有什么意义？

提高工程团队开发流程的标准化；
高效的个人和团队的提升；
保持项目代码风格的一致性；
减少不必要的 BUG；

搞 Code Review 规范需要注意什么？

在 Code Reivew 的评论中适当加入 Code Sample；
用 我们 代替 你，强化团队整体；
尽量不要用命令的口吻去表达自己的意见（如果你的公司阶级观念比较重，可以无视）；
批注中对要改的内容作出说明原因时候，尽量能有理论依据支撑，而不是我觉得就应该这样；
遇到紧急需求上线，来不及代码审查怎么办？
- 最好是在任务管理系统中，创建一个 Ticket，用来后续跟踪，确保后续补上 Code Review，并对 Code Review 结果有后续的代码更新。

如何去做 CR 规范？

上述所有规范方案都适合 Code Reivew；
严格按照编程规范指南（见上）来 Reivew 代码；
可以人人 Review —— 合适的 Reviewer；
快速响应；
结合工具 Review；
表达肯定，委婉表达意见（语言的魅力很重要）；
激励机制：激发主观能动性（跟考核挂钩？）

好的 Code Review 不仅能提前发现隐藏的 Bug，还能使得团队成员的代码能力得到提高。

相反，不好的 Code Review 带来的不仅不能发现 Bug，不能帮助团队提升，更可怕的是会影响整个团队的开发氛围和团队成员之间的关系。

所以 Code Review 的目的绝不仅仅是发现问题，更重要的是提升团队的开发能力；

六、前端文档都有什么？

相信在座的许多同学都吃过没文档的亏，文档对于企业的团队的发展有多重要，就好比学校里的图书馆；

它无论是对 项目的开发和维护，还是对旧与新的交替，亦或者是团队的建设轨迹，都有着无可代替的作用；

文档有什么作用：

对新人友好，快速融入团队；
规范化编码；
有效的控制团队的原型以及代码的版本；
重大决策与讨论的记录；
完善内部技术讨论交流；
团队建设；

前端文档都有什么？

前端文档.png

最后

关于前端规范，在每个企业都会有所差异，受限文章篇幅原因，所以上述主要是介绍了一些常用的规范，我相信你们的团队也一定用的到；

该系列会是一个持续更新系列，关于 前端基建，笔者主要会从如下图几个方面讲解，如果您想第一时间看到我的更新文章，可以关注我和我的《前端要搞基建》专栏

前端基建之路.png

如果你对 Vite 感兴趣，可以看看我的专栏：《Vite 从入门到精通》

如果你对微前端感兴趣，可以看看我的专栏：《微前端从入门到精通》

如果想跟我一起讨论技术吹水，欢迎加入前端学习群聊或加 vx: JeddyGong

感谢大家的支持，码字实在不易，其中如若有错误，望指出，如果您觉得文章不错，记得 点赞关注加收藏 哦 ~

关注我，带您一起搞基建 ~

备案审核专用网站模板

非大厂的我们，如何去卷一套标准的前端团队规范？

前言

一、场景重现

二、团队存在的问题

三、规范的定义

四、规范的好处

五、前端规范都有什么？

1. 前端命名规范

2. 技术栈规范

3. 编程规范

4. Git 规范

5. BFF 研发规范

6. 前后端协作规范

7. UI 设计规范

8. 前端测试规范

9. 浏览器兼容规范

10. IDE 编辑器规范

11. 需求研发流程规范

12. CR 规范（Code Review）

六、前端文档都有什么？

最后