作者：易师傅 、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
    }
}

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

1. 命名是否规范？

   • 方法名 clickDw 可否用 getLocation 代替？
   • 变量名 dz 可否变成 address？
   • 地址列表可否用 addressList 代替？

2. if 判断是否可以简化？

   • if(type === 1 || type === 2 || type === 3) 可以用 [1, 2, 3].includes(type) 代替吗？

3. 亦或还有其它优化空间？

   • 是否需要 else if ?

4. 大家觉得还有其它优化空间吗？

   • 欢迎讨论

二、团队存在的问题

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

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）

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

五、前端规范都有什么？

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

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

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

1. 前端命名规范

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

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

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

一些常见的不规范命名：

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

一些常见好的命名：

1. 驼峰式命名法介绍：

   • Pascal Case 大驼峰式命名法：首字母大写；

     • eg：StudentInfo、UserInfo、ProductInfoCamel

   • Case 小驼峰式命名法：首字母小写；

     • eg：studentInfo、userInfo、productInfo

2. 文件资源命名：

   • 文件名不得含有空格；

   • 文件名建议只使用小写字母，不使用大写字母；

   • 名称较长时采用半角连接符(-)分隔；

       usr/dev/document/front-end/project-vue3
   

3. 变量命名：

   • 命名方式 : 采用小驼峰式命名方法；

   • 命名规范 :

     • 普通变量(number, string, date)；
     • 布尔类型：需要一个标识变量含义的前缀，比如has, is, wether, can, should等；
     • 数组/集合等复数形式：最好以s或list等能够标识复数形式的后缀结尾，标识当前变量是复数形式，提高可读性；

   • 常量全部大写，且用下划线来分割单词，eg：MAX_LENGTH = 1

4. 函数：

   • 命名方式 : 小驼峰方式 lowerCamelCase ( 构造函数使用大驼峰命名法 )
   • 命名规则 : 前缀为动词，动词 eg：add / update / delete / detail / get

   // 更新数据
   function updateData(){
       return {};
   }
   
   // 获取用户信息
   function getUserInfo{
       return {}
   }
   

5. css 命名：

   • 样式类名使用小写字母，以半角连接符(-)分割；
   • id 采用驼峰式命名；
   • scss / less 中的变量、函数、混合、placeholder 采用驼峰式命名

   .heavy {
     font-weight: 800;
   }
   .important { 
     color: red; 
   }
   

2. 技术栈规范

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

• 到底是用 TypeScript 还是 JavaScript ？

• 到底是用 Vue 还是 React ？

• 到底是用 Less 还是 Sass ？

• 到底是用 Webpack 还是 Vite ？

• 到底是用 Koa 还是 Express ?

• ……

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

我司选择答案：

1. 为什么用 TypeScript 而不用 JavaScript 呢？

   • 静态类型语言要较于动态类型语言更安全；
   • TypeScript 代码更可靠且更易于重构；
   • TypeScript 更明确类型；

2. 为什么用 Vue 而不用 React ？

   • 这是一个容易引战的话题；
   • 所以我们的答案是：领导让用

3. 为什么用 Sass 而不是 Less ？

   • Sass 功能齐全；
   • 不仅有变量和作用域，还有函数和进程控制的概念；
   • 更像一门正规的编程语言；

4. 为什么用 Vite 而不是 Webpack？

   • 开发效率极高 —— 🚀 般的速度；
   • 上手极其简单；
   • 社区成本低；
   • 目前业务内所有项目已慢慢转为 Vite 构建；

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

3. 编程规范

为什么需要编程规范？

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

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

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

编程规范的意义：

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

编程规范都有什么？

怎么搞编程规范？

1. 确定现有团队的问题；

2. 定制属于自己公司的规范（从上面导图入手）；

3. 统一规范应以自动化为前提；

   • Eslint、Prettier、Stylelint 自动化必不可少；

   • 如不满足可自定义自动化工具规范（后面文章会讲到）；

推荐几个编程规范文档

• 阿里前端规范
• 腾讯前端规范
• 京东前端规范
• 百度前端规范

4. Git 规范

为什么要 Git 规范？

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

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

如何去做 Git 规范？

1. Git 版本规范

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

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

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

   

   功能分支工作流相较集中式工作流的优点：

   • 保持主干的干净。隔离了多个开发者在各自功能上的开发不会扰乱主干代码
   • 提供了Code Review的空间。功能分支在合并到主干之前，触发集成测试，或者开启Pull Request, 启动一个围绕分支的讨论。发挥群众的力量

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

1. 接口数据返回统一原则

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

   优化：统一一致的数据格式

2. 微服务接口聚合原则

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

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

3. 业务下沉原则

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

   优化：需下沉至后端服务

后端研发原则：

1. 微服务业务单一原则

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

   优化：一个业务对应一个微服务

2. 与前端同步原则

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

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

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

6. 前后端协作规范

场景重现：

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

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

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

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

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

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

前后端协作规范的意义：

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

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

1. 协作规范流程

   • 需求分析。确保大家对需求有一致的认知；
   • 设计接口文档。前端需要确认是否符合要求；
   • 并行开发。前端需要根据接口文档进行Mock, 模拟对接后端接口；联调之前，要求后端做好接口测试；
   • 真实环境联调。前端将接口请求代理到后端服务，进行真实环境联调；

2. 接口规范

   • 接口风格使用 RESTful 风格；

   • 请求方法规范：

     • GET：获取对应的信息；
     • POST：用于创建或者某些资源的提交；
     • UPDATE：更新某些资源；
     • DELETE：删除某个资源；
     • OPTIONS：对请求的校验，与 POST 配合；

   • 其它规范：

     • URI 结尾不应包含（/）；
     • 正斜杠分隔符（/）必须用来指示层级关系；
     • 应使用连字符（-）来提高URI的可读性
     • 不得在URI中使用下划线（_）；
     • URI路径中全都使用小写字母
     • 具体详见：RESTful 架构详解

   • 接口文档规范：

     • 版本号；

     • 接口注释与字段的描述；

     • 具体接口定义：

       • 方法名称或者 URI
       • 方法描述
       • 请求参数及其描述，必须说明类型(数据类型、是否可选等)
       • 响应参数及其描述, 必须说明类型(数据类型、是否可选等)
       • 可能的异常情况、错误代码、以及描述
       • 请求示例，可选

3. 注意点：

   • 明确数据类型、空值的意义以及默认值；
   • 对于大数字（整数大于 16 位、浮点数大于 18 位）做字符串处理；
   • 关于日期时间格式；
   • 响应避免冗余的嵌套；
   • 接口版本化，保持向下兼容；接口不兼容时需升级版本；
   • 鉴权通过header实现；
   • 其它……

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

7. UI 设计规范

场景复现：

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

设计规范的意义与目的：

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

设计规范都有什么？

8. 前端测试规范

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

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

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

• 在组件工具库：自动化测试十分普及且必要；

• 在面向于 UI 侧：自动化测试等相关就不怎么普及；

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

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

前端测试规范的意义

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

前端测试的三大类：

• 单元测试：

  • 单元测试是最基础的自动化测试，用来检测项目当中的最小可测单元，例如工具函数、基础组件等

• 集成测试：

  • 集成测试，也叫组装测试或联合测试。在单元测试的基础上，将所有模块按照设计要求（如根据结构图）组装成为子系统或系统，进行集成测试。

• UI 测试：

  • 测试用户界面的功能模块的布局是否合理，整体风格是否一致和各个控件的放置位置是否符合客户使用习惯，更重要的是要符合操作便捷，导航简单易懂，界面中文字是否正确，命名是否统一，页面是否美观，文字、图片组合是否完美。

前端测试的常用工具：

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

9. 浏览器兼容规范

场景复现：

浏览器兼容规范的意义

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

如何搞浏览器兼容规范？

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

• 从开发成本出发：

  • 假设在兼容 IE 低版本的浏览器的情况下，是否会对开发效率、网站性能、用户体验都会有影响？

• 从用户设备类型出发：

  • 判断用户设备类型，一般就需要借助自研的 前端数据埋点系统（后续文章会讲解） 或者市面上现成的统计平台，例如 百度统计、友盟、谷歌的 Google Analytics；
  • 即可判断出用户设备的使用情况，如下图（我司）谷歌 GA 的分析图:

• 从浏览器市场份额出发（如图所示）

  • 全球浏览器市场份额（2022-09）：

  • 中国浏览器市场份额（2022-09）：

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

10. IDE 编辑器规范

场景复现：

IDE 编辑器规范的意义

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

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

11. 需求研发流程规范

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

讨论题：

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

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

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

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

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

关于需求变更处理建议：

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

12. CR 规范（Code Review）

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

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

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

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

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 的目的绝不仅仅是发现问题，更重要的是提升团队的开发能力；

六、前端文档都有什么？

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

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

文档有什么作用：

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

前端文档都有什么？

最后

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

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

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

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

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

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

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