迈向前端 Leader - 制定前端规范

hi，我是风骨，今天和大家聊一聊「前端规范」话题。在团队协作开发中，规范可以约束和统一，每一位成员的编码习惯、降低协作沟通和维护成本，提升研发效率。

接下来，我将结合自己的工作经历，和大家一起走进今天的话题：「前端规范」。

内容大纲：

毛遂自荐 ：笔者最近在看工作机会，各位小伙伴 如果有适合的内推岗位（高级前端、前端项目负责人），可以帮我引荐一下（掘金上私信 或是 添加微信: iamcegz），感谢！个人简介如下：

男，27 岁，计算机专业，工作年限 6 年，Base 北京，从事过 AIGC、低代码、云文件、动态表单、前端基础建设、优化页面性能和用户体验 等领域工作。

1、认识前端规范

1. 什么是前端规范？

规范，是一套明文规定或约定俗成的标准，用来指导操作和活动达到既定要求，确保所有参与者都能在同一套逻辑下高效协作 。而前端规范，就是针对前端开发这一特定领域的规则集合，目的是让代码更易读、更易维护，同时提升团队协作效率。

2. 制定它有什么好处？

• 技术层面：让代码更稳定、更高效。规范能确保代码风格一致，极大提升代码的可读性和可维护性。
• 协作层面：降低沟通成本，提升效率。让每个开发者都能快速理解别人的代码，减少误解和冲突。
• 管理层面：知识沉淀与长期价值。记录了团队在长期实践中积累的最佳实践，帮助新人快速成长，同时也为项目的长期维护提供了保障。

3. 前端规范包含哪些内容？

前端规范不单单指 "代码书写规范"，涉及前端开发活动范围、跨团队协作的方方面面。常见的前端规范可以归纳为以下几类：

1. 编码规范：使用工具 ESLint、Prettier 按照规范约束代码，还有团队内约定下来的代码书写规范
2. 工作流操作规范：包含 任务分配管理 - 看板、技术文档规范、Git 版本控制规范、上线流程操作规范、项目模板与构建工具规范、包版本发布升级规范
3. UI 设计和产品功能交互规范：统一样式和交互，降低研发成本
4. 接口对接规范：降低对接和沟通成本
5. 三方工具选型规范：适配项目

2、编码规范

在企业中，一个大型项目通常是由一个团队一起协作开发。统一的编码规范，可以保证代码的书写一致、风格统一，提升代码的可读性和可维护性。

执行统一的编码规范，除了从 开发者个人认知 和 编码习惯 着手外，还需要借助一些工具来辅助约束。下面我们先来看看如何在团队中使用工具约束形成统一的编码规范。

2.1、使用工具约束规范

能够约束编码规范的工具有两类：ESLint 和 Prettier，此外还有一个是语言 - TypeScript（JavaScript 的强类型语言）。

2.1.1、ESLint

ESLint - JavaScript 代码检查工具（注重检查，检查语法和格式），帮助开发者编写更高质量的代码。

它可以：

• 语法错误、质量检查：

ESLint 可以检测代码中的语法错误，例如：JSX map 数组时元素必须定义 key 属性、强制使用 ===(全等) 代替 ==(相等)、禁止使用 var 声明变量、switch 语句中 case 值重复 等等。

• 统一代码风格：

ESLint 可以强制团队或个人遵循一致的代码风格，例如：缩进（2 空格还是 4 空格）、分号的使用（是否必须加分号）、引号风格（单引号还是双引号）等等。

有关在项目中集成 ESLint 可以参考官网 ESLint Getting Started，或者阅读作者先前积累的这篇笔记文章 - 前端项目配置 ESLint/Prettier。

2.1.2、Prettier

Prettier - JavaScript 代码格式工具（注重规范，规范格式）。

虽然 ESLint 也能做代码风格检查，但是需要执行 ESlint --fix 命令才会会对代码做格式化处理。而 Prettier 则可以结合编辑器（VSCode）在保存代码时自动对文件内容，按照配置的规则进行格式化处理。

PS：在编辑器上开启 保存自动格式化 选项，可以提高开发效率。比如代码缩进、单双引号统一、添加分号，无需我们手动干预。

Prettier 常见的代码风格规则有：

• printWidth：指定每行代码的最大宽度，默认为 80；
• tabWidth：指定每个缩进级的空格数，默认为 2；
• semi：是否在语句末尾添加分号，默认为 true；
• singleQuote：是否使用单引号而不是双引号，默认为 false；
• bracketSpacing：是否在对象属性和后面的括号之间添加空格，默认为 true；
• bracketSameLine：是否将元素的右括号显示在最后一行的末尾（比如 HTML 元素的 ">" 不会换行单独展示在下一行），默认wield false；
• arrowParens：箭头函数只有一个参数时，是否在参数周围加上括号，可选值为 "always"（总是添加）、"avoid"（尽可能省略）。

有关在项目中集成 Prettier 可以参考官网 Usage 或阅读作者先前积累的这篇笔记文章 - 前端项目配置 ESLint/Prettier。

2.1.3、ESLint + Prettier 组合使用

对于工具约束规范落地的最佳实践是：ESLint + Prettier 组合使用，同时配合上编辑器提供的对应扩展插件。

不过，两者一起使用时，格式化处理上难免会遇到冲突，当两者的格式处理不相同时，比如 ESLint 要求声明的函数名称后面与括号之间留存一个空格（如：function created () {...}）而 Prettier 在保存时则会将留存的空格移除掉（如：function created() {...}）。

要解决冲突也很简单，通常我们会以 Prettier 的格式规则作为第一优先级，将 ESLint Rules 中对应的规则进行关闭。

2.1.4、TypeScript

TypeScript 作为 JavaScript 的严格静态类型语言，它的优势在于：

• 类型检查：TypeScript 会在编译代码时，进行严格的静态类型检查，这意味着你会在编码阶段，发现可能存在的隐患，而不必把它们带到线上去。
• 提升代码的阅读体验和可维护性：对于协作者，能够清楚地知道每一个变量的类型、函数的入参和返回值类型，快速熟悉和使用代码；
• 代码提示：当你为变量声明了类型后，在使用变量的属性或方法时，idea（如 VSCode）会进行提示，如输入 obj. 时，idea 会将 obj 下的属性提示出来供你选择；
• api 接口字段说明：使用 TypeScript 为 API 接口的 参数 和 响应数据 声明类型和编写注释，清楚的知道这个接口如何使用，以及返回哪些数据，类似于一个简易的接口文档。

先前我写过一篇「TS 高级功法」，感兴趣的朋友可以阅读看一看。

2.2、制定编码书写规范

使用 ESLint、Prettier 工具能够约束常规的代码规范，但是有一些工具干预不了的编码注意事项，还需要我们一一制定。如下例举了几个在团队中常见的规范制定。

1. 单文件组件代码行数限制

比如，在单文件组件中，书写的代码尽量不要超过 200 行，如果超过 200 行时就得考虑进一步细化组件。

2. 变量、函数命名规范

在编程中，变量和函数的命名规范是非常重要的，它们直接影响代码的可读性、可维护性和协作效率。

命名通常需要遵循以下原则：

• 清晰易懂：变量和函数的名字应该能够清楚地表达其用途或功能，避免使用模糊或无意义的名称。
• 简洁明了：尽量使用简短但有意义的名字，避免过长或过于复杂的名称。
• 避免缩写 ：除非缩写是广泛认可的（如 id 表示 identifier），否则尽量避免使用缩写。

在前端，

• JavaScript 变量命名通常会采用 驼峰命名法（CamelCase） ，首字母小写，后续单词首字母大写，例如：userAge、userName；
• 对于 类定义、React 组件名称，也是采用 驼峰命名法（CamelCase） ，首字母 和 后续单词首字母都大写，例如：Person、Button。

另外再给大家推荐一个 VSCode 扩展插件 - Code Spell Checker，有时我们不注意会将变量命名单词书写错误，这个插件可以帮忙我们检查并提示出来。

3. 将字面量值声明为常量

以 本地存储字段 key 为例：在一些场景下我们需要将信息记录到本地缓存（sessionStorage、localStorage）中，关于缓存 key 的定义最好的做法是定义为一个变量常量，通过使用常量进行缓存 API 的读写操作。

这样做的好处是：如果说将来需要修改 key，只需修改一次这个变量就可以了。

如下示例：

// 将 cache key 声明为常量
const cacheKey = "app-theme";

const getAppThemeByCache = () => {
  return localStorage.getItem(cacheKey);
};

const setAppThemeByCache = (theme) => {
  localStorage.setItem(cacheKey);
};

2.3、代码 Review 审查和优化

代码 Review（代码审查） 是软件开发过程中一种重要的质量控制手段，通过组织团队成员进行代码 Review，来完善和落实代码符合我们制定的编码规范。这是软件开发非常有意义的一个环节。

代码 Review 的形式有：

• 提交时审查： 类似于开源项目。在代码提交后会产生一个 Pull request，只有项目负责人审阅通过后再将其合并到主分支上。
• 定期审查： 在项目完结后、项目的某个里程碑、或者固定的时间(每天、每个星期..). 团队成员组织在一起，回顾自己写的代码, 让其他成员进行审查。
• AI 辅助代码审查：现在 AI 技术盛行，利用 AI 工具来帮助我们分析书写的代码，进行指导和优化。

此外，将代码 Review 中发现的一些常见问题收录到一个文档中，在团队中逐步达成团队共识，为后续开发提供标准，也能帮助新成员更快地融入团队。

以下例举几个常见的代码优化问题：

1. 重复的对象链路上的属性访问

优化：利用对象解构，对于公共的链路属性（obj.a.b.c），只编写一次。

// 不推荐写法
const name = obj.a.b.c.name;
const age = obj.a.b.d.age;

// 推荐写法
const { name, age } = obj.a.b.c;

2. 一个函数的扁平化参数太多，导致调用时很难搞清楚每个参数的作用，以及参数的传递顺序。

优化：在函数参数很多时，定义函数可以写成配置对象 options，从对象中解构出参数。

// 不推荐写法
function fn(a, b, c, d, e, f, ...) {
  // ...
}

// 推荐写法
function fn(options) {
  const { a, b, c, d, e, f } = options;
}

3、工作流操作规范

3.1、任务分配管理 - 看板

作为前端 Leader 或项目负责人，需要将已规划排期好的 开发任务 ，按照 交付时间线 分配给每一位开发团队成员，按照这个任务分配完成和交付。

看板作为任务管理工具，它可以帮助我们了解项目的进度、资源的分配情况、任务的交付和完成状态，让管理工作变得更简单。

常见的项目研发看板工具：Worktile、Tower、PingCode、Teambition 等。

以 Worktile 为例，分配一个任务可以指定 负责人、任务的完成时间、任务的详细描述信息。

对于开发成员来说，需要根据当前自身的开发进度，及时去更新任务状态。

3.2、技术文档规范

技术文档是项目开发和维护过程中不可或缺的一部分。在产品介绍完需求以后，我们需要对要实现的功能进行：技术调研、架构设计、关键决策和方案讨论，并记录成一份可参考和回顾的技术文档。

技术文档内容组成部分：

• 封面：文档名称、发布时间、作者 等信息；
• 项目和功能背景介绍；
• 技术设计方案：如技术栈选型、绘制架构设计流程图 等内容；
• 方案讨论结果：记录参与技术设计方案可行性讨论的 参与人员、方案调整事项、结论。

技术文档的编写和存储，可以使用 飞书文档、石墨文档 等免费产品，也可以在公司部署一个 MarkDown 文档书写网站，将文档存储在 Git 仓库中。

3.3、Git 版本控制规范

在团队协作中，Git 的规范使用这一环节必不可少，它能够确保团队之间协作高效，利于分支的管理和维护，同时保证项目上线内容的完整性。

3.3.1、分支命名规范

在创建分支时，分支名称应清晰表达其用途。

例如分支的用途是 master 生产环境分支、dev 开发主分支、feature 功能分支、release 上线分支、还有 hotfix 紧急修复问题分支。此外分支名称还可以包含 创建人（名称缩写）、创建时间、所属分支、基于所属分支的哪个 commit 节点来创建分支 等信息。

分支命名示例：以 项目中集成支付宝支付 功能需求为例

# 格式：用途/创建人/所属分支/所属分支的 commit id/功能名称_时间
feature/cyl/master/e5c81b17/alipay_payment_20250312

3.3.2、提交信息规范

在提交代码时，commit message 的书写要做到一看便知它的用途、代码修改和影响范围，绝不是为了单纯提交代码而随意书写内容。

一个规范的 commit message 有利于我们：

• 更直观的提交历史，方便查找和追溯问题；
• 根据 commit 生成 Change log 文件生成版本升级文档。

commit message 规范包括三个部分：Header，Body 和 Footer。结构如下：

<类型>([可选的作用域]): <描述> - header
// 空一格
[可选的正文] - body
// 空一格
[可选的脚注] - footer

其中，Header 是必需的，Body 和 Footer 根据实际使用情况进行填写。

Header 部分只有一行，包括三个字段：type（必需）、scope（可选）和subject（必需）。

1. type

type 用于说明 commit 的类别，常见的应用常见有下面 7 类。

• feat：新功能（feature）
• fix：修补bug
• docs：文档（documentation）
• style：格式（不影响代码运行的变动）
• refactor：重构（即不是新增功能，也不是修改bug的代码变动）
• test：增加测试
• chore：构建过程或辅助工具的变动

2. scope：

scope用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。

3. subject：

subject是 commit 目的的简短描述，不超过50个字符。

书写示例：

# 推荐写法
git commit -m "fix(数据层): 修复提交表单后，字段数据未重置问题。"

# 反例
git commit -m "改bug"

3.3.3、分支管理规范

不同公司和不同规模的团队，在分支的管理策略上也各不相同，旨在帮助团队更高效地协作和管理项目迭代。

Git Flow 是一种流行的 Git 分支管理策略，我们可以在这个规范之上定制适合团队的分支管理策略。

常见的几种分支类型：

• 主分支（Master） ：用于存储稳定版本的代码，通常是项目的最终发布状态，即生产环境所运行的代码；
• 开发分支（Develop） ：作为日常开发的主分支，所有新功能和修复都从该分支创建；
• 功能分支（Feature） ：用于开发新功能，从 dev 分支创建，完成后合并回 dev；
• 发布分支（Release） ：用于准备新版本的发布，从 dev 分支创建，完成后合并到 master 和 dev；
• 补丁分支（Hotfix） ：用于紧急修复生产环境中的问题，从 master 分支创建，完成后合并到 master 和 dev。

工作流程主要分为以下几个阶段：

• 功能开发 ：从 dev 分支创建一个新的功能分支，在功能分支上开发完成后，合并回 dev。
• 上线分支准备 ：基于 master 切出一个 release 分支，将 dev 分支上的上线内容合并到 release 分支上进行通过性验证，验证通过后，合并到 master 分支进行升级。升级完成后还需打上 Tag 标记这次上线，便于追溯。
• 紧急修复 ：从 master 分支创建一个新的 hotfix 补丁分支。修复完成后，合并到 master 和 dev。

3.4、上线管理规范

上线管理规范一般是针对 项目负责人，遵循以下操作流程确保项目顺利上线。

1. 掌握上线计划和时间的安排，按照 Git 操作规范在上线前切出 release 分支；
2. 根据上线内容将相关分支合并到 release 分支上，确保上线的内容都已带上；
3. 在验证环境切换到 release 分支，让验证人员进行通过性验证；
4. 通过后合并到 master 分支，运维人员进行项目上线升级；
5. 升级成功以后，为本次上线节点标记上 Tag。

3.5、项目模板和构建工具规范

在团队技术栈成型以后，项目的目录结构、所用技术栈以及构建工具的配置，都应该保持统一，方便对每个项目仓库进行管理和维护。

这里推荐的做法是：定义一套项目目录结构和构建工具链配置的模板 + pnpm Monorepo 多项目管理工程 + CLI 脚手架，在团队落地一套这样的组合。

• 按照前端工程常见的模块进行划分目录结构，如 pages、components、styles、interface、api、utils、constants 等目录，同时定义好构建工具链的配置，以模板的形式存放在 Git 仓库；
• pnpm Monorepo 多项目管理工程可以让多个项目的技术栈、构建配置均使用同一套，同时也提升了多仓库维护上的便利；
• CLI 脚手架，则类似于 create-react-app，通过执行创建命令，clone 提供的 项目模板 来创建我们的项目。

3.6、包版本发布升级规范

在团队中落地的一些工具、插件库，我们会发布到 npm 包管理平台，安装在项目中使用。

对于 npm 包发布升级，需要遵循语义化版本控制，通常由三部分组成：主版本号.次版本号.修订号，例如 1.0.0。版本号的更新规则如下：

• 主版本号（Major） ：当引入不兼容的 API 修改时，主版本号递增，例如 1.0.0 → 2.0.0。
• 次版本号（Minor） ：当添加向后兼容的新功能时，次版本号递增，例如 1.0.0 → 1.1.0。
• 修订号（Patch） ：当进行向后兼容的缺陷修复时，修订号递增，例如 1.0.0 → 1.0.1。

对于预发布版本，通常用于测试阶段，版本号格式为 主版本号.次版本号.修订号-预发布版本，例如 1.0.0-alpha.1。常用的预发布标识包括 alpha(内部测试版本)、beta(公开测试版本) 和 rc(候选发布版本)。

我们可以使用 npm version 命令更新版本号：

npm version major   # 主版本号递增
npm version minor   # 次版本号递增
npm version patch   # 修订号递增
npm version prerelease --preid=beta  # 预发布版本递增

另外，如果是将包发布在 CDN 服务上（例如低代码远程物料），也许按照上面规则添加版本控制，避免使用上出现版本兼容问题。

示例 JQuery 版本 URL：

# v3.7.1
https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.min.js

4、UI 设计和产品功能交互规范

4.1、UI 设计图规范

UI 设计规范对于我们前端研发非常重要。如果 UI 没有设计规范，前后设计出来的样式、交互都不一致，在不同场景下相同交互的组件不能复用，使得我们不得不浪费时间，写很多定制化样式和组件。

UI 设计规范的意义在于：

• 提供团队协作效率(产品和开发)
• 提高组件的复用率. 统一的组件规范可以让组件更好管理
• 保持产品迭代过程中功能交互一致性

如果遇到以下情况，就需要及时与 UI 设计师进行沟通。

1. Icon 图标设计一致性：对于同一类图标（如 垃圾桶删除），UI 设计师在设计原型图时，应在整个项目中尽可能的使用一种形态，不要出现 都是垃圾桶形状 但细节有差异的现象，这会增加前端研发人员的项目维护成本。

2. UI 图上主题色的设计：应当按照约定的 主题色规范 进行设计，不要随意出现 主题色规范 之外的色值。

4.2、产品功能交互规范

假如你所在的公司是做 SAAS 产品，公司会有一套 产品化标准的用户交互体验 标准，在实际业务开发中应当考虑和按照这个标准去实现。

例如：

1. 对于 Button 按钮类的操作，移入、移出、点击 都要有背景色改变的效果，不能生硬；
2. 对于从 List Page 进入子页面的场景，再从子页面回退到 List Page 时，确保将列表恢复为进入子页面之前的滚动位置；
3. 对于提示类弹框，允许使用 ESC 快捷键或点击蒙层进行弹窗关闭；对于填写表单类弹框，只能点击取消按钮或提交表单后进行弹窗关闭；
4. 对于 Input，允许前、后、中间输入 1-多个空格，但是输入框中仅有空格，不能完成保存。

5、接口对接规范

接口对接规范是指前后端需要遵循 约定的规范化标准 来设计和对接数据。

例如：

1. 遵循 RESTful 风格来定义接口的请求方法 Method；

• GET，用于获取资源，不产生副作用，通过 URL 传递参数；
• POST，用于提交数据，创建新资源，通过请求体传递数据；
• PUT，用于更新资源，替换整个资源，通过请求体传递数据；
• DELETE，用于删除资源，通过URL传递资源标识；

2. 清晰的响应数据 code 定义；

在前端封装 request 时，可以通过 response data code 来处理 成功、无权限、操作失败 等多种情况；对于操作失败的情况，接口同时还应下发 error_message 错误原因，使用统一的错误处理机制（如 Toast 轻提示）反馈给用户。

3. 分页的约定；

有的团队喜欢将分页页码从 0 开始，有的则是从 1 开始，这一点我们需要前后端协商好，今后涉及分页的场景，统一按照一个标准设计和实现。

6、三方工具选型规范

在业务开发中，一些功能我们需要借助第三方工具来实现，比如 排序库、Markdown 语法解析为 HTML 字符串。

在选择第三方工具包时，需要综合考虑以下几个关键维度，以确保选型的合理性和项目的成功：

1. 知名度：

可以查看工具包在 GitHub 上的 Star 数量和 Fork 数量，高 Star 数通常意味着较高的用户基础和关注度。

2. 活跃度：

通过查看工具包在 Github 上的维护记录，以及 Issue 和 Pull Request 的活跃度，判断开发团队对用户反馈的重视程度。

3. 体积大小：

三方工具资源的体积影响着网站的加载速度，在确定使用一个库之前，应当关注它的体积对网站的加载影响有多大，是否支持按需加载和打包。

4. 学习成本：

对于一个工具包，它的文档、教程和社区资源越丰富，学习成本越低，反之只有源代码缺少一个完整用例的使用文档，这让我们上手变得很困难。

文末

内容挺长，感谢阅读。文章内容你觉得有用，可以点赞支持一下~

如果屏幕前的读者，你的团队中有更好或其他方面制定的规范，欢迎在评论区扩充你的观点，让更多人学习进步！