前端开发规范梳理

2689字约9分钟

前端优化

2024-05-09

前端开发规范是确保团队协作、代码可维护性和项目一致性的重要文档。以下是一份前端开发规范梳理，欢迎参考和补充。

一个良好的开发规范，至少要做到以下方面，如果没有做到，还增加了了一些额外的工作量，可以直接放弃该规范。

提高代码可读性，使代码更加易于维护
提高团队协作效率，减少沟通成本，提高效率
提高代码质量，减少bug

运行环境

当前大环境下，很多项目都是前后端分离，而且大部分项目都使用 Vue 或者 React 等框架开发，由于每个项目中使用了不同的框架版本和包版本。因此我们要确保每个项目运行在最佳版本的环境中。

Node.js版本：日常开发中保证 Node.js 版本与当前项目的最佳版本一致。

由于不同项目使用的 Node.js 版本不同，需要我们频繁切换版本，我们可以借助 nvm或n 等工具来管理 Node.js 版本。
Mac: 推荐使用 n 作为Node版本管理 Node.js版本管理器 - n
Windows: 推荐使用 nvm 作为Node版本管理）Node.js版本管理器 - nvm

使用锁文件：锁定项目依赖包版本。

使用 package-lock.json（npm）或 yarn.lock（yarn）文件锁定依赖版本，确保所有开发者使用相同的依赖版本。并且还能避免一些依赖冲突问题导致的项目启动失败。
如果需要使用 package-lock.json 或者 yarn.lock ，需要在 .gitignore 文件中取消 package-lock.json 和 yarn.lock 文件。

Git 提交规范

Git Commit Message 规范在现在的团队多人协作开发中越来越重要，已经成为一种新的标准实践。尤其是在一些大型项目和追求高质量和可维护性的项目中。遵循一定的规范，能为我们带了很多好处。

按照规范的提交信息有助于确保每个提交的信息都是清晰且一致的，使得其他同事能够迅速理解提交的目的和影响。
清晰的提交信息减少了需要额外沟通的情况，因为大部分信息都可以从提交记录中直接获取。
使用特定的类型（如 feat, fix, docs）可以传达提交的性质，帮助团队识别哪些是新功能，哪些是修复，哪些是文档更新等。

规范总示例：

[TYPE]:[相关需求或者BUG编号][修改或者新增模块-具体操作]

以下为一些示例：

// BUG修复
git commit -m '[fix]:[BUG_20201205_01][用户列表-修复搜索错误]'

// 新功能
git commit -m '[feat]:[202012_05_01][用户列表-新增用户]'

// 样式修改
git commit -m '[style]:[202012_05_01][全局样式-顶部导航栏统一化]'

前端常用TYPE：

TYPE类型	释义	示例
`init`	项目初始化	`[init]:[][XX项目初始化]`
`feat`	添加或优化新功能	`[feat]:[Feat_20221001_01][新增角色添加功能-页面开发]`
`fix`	修复BUG相关	`[fix]:[BUG_20221001_01][角色列表-新增角色修复]`
`refactor`	代码重构	`[refactor]:[][全局方法-文档导出优化]`
`style`	样式改动	`[style]:[][全局样式-全局主题色调整]`
`docs`	文档更改	`[docs]:[][README修改]`
`build`	构建相关的更改	`[build]:[][构建配置修改]`

Git可视化工具

推荐使用 Sourcetree 作为Git可视化工具，它可以提供直观的界面和功能，方便团队协作。

命名规范

所有命名推荐使用语义话命名，命名要具有描述性，禁止使用拼音或者拼音缩写，禁止使用中文命名。可以使用规范缩写。

例如：my-project、assets/styles/base.css
错误示范：ceshi、page1.vue

项目命名

项目名：小写字母，多个单词用中划线连接。

例如：my-project
错误示范：MyProject、my_project

文件命名

文件名：小写字母，多个单词用中划线连接。

文件扩展名：根据文件类型使用相应的扩展名，例如：.html 、.css 、.js 、.png 、.jpg 等。

例如：index.html、user-profile.vue、api-service.js
错误示范：Index.html、userProfile.vue、apiservice.js

HTML 规范

文档结构

文档类型：使用 HTML5 的文档类型 <!DOCTYPE html>。

字符编码：在 <head> 中使用 <meta charset="UTF-8"> 指定字符编码。

指定语言：在 <html> 标签中使用 lang 属性指定文档的语言。

文档内容：确保文档包含 html、head 和 body 三个基本部分。

示例：

<!DOCTYPE html>
<html lang="en">
  <head>
      <meta charset="UTF-8">
  </head>
  <body>
      <!-- 页面内容 -->
  </body>
</html>

元素属性

元素属性：所有元素和属性必须使用小写字母，属性值必须用双引号括起来。

语义话标签：使用语义化标签，如 <header>、<nav>、<main>、<footer>、section等。

必要属性：为所有 <img> 标签添加 alt 属性，为所有 <a> 标签添加 href 属性。

正确示范：

<img src="image.jpg" alt="Image description">
<a href="https://example.com">Link</a>

错误示范：

<img src='image.jp'>
<a href="#">Link</a>

代码格式

缩进换行：使用两个空格进行缩进。在适当的位置添加换行，使代码更易读。

代码注释：在代码中添加必要的注释，解释当前模块内容。

避免过度嵌套：避免过度嵌套，保持代码简洁。

示例：

<!-- 头部导航 -->
<header>
  <nav>
    <ul>
      <li><a href="#">Home</a></li>
      <li><a href="#">About</a></li>
      <li><a href="#">Contact</a></li>
    </ul>
  </nav>
</header>
<!-- 主题内容 -->
<main>
  <section>
    <h1>Page Title</h1>
    <p>This is a paragraph.</p>
  </section>
</main>
<!-- 底部信息 -->
<footer>
  <p>© 2021 My Website</p>
</footer>

CSS 规范

文件结构

外部样式表：使用外部样式表，将样式与 HTML 内容分离。禁止使用内联样式。

正确示范：

<link rel="stylesheet" href="styles.css">

错误示范：

<div style="color: red;">This is a red text</div>

组织文件：将样式表按功能或模块进行组织，避免将所有样式都放在一个文件中。

css/
├── main.css
├── layout.css
├── components.css

命名规范

类名：使用小写字母，多个单词用中划线连接。

ID 名：使用大写驼峰命名法。和类名区分开。

其他：less 或者 scss 中，变量、混合、函数等命名使用大写驼峰命名法。

示例：

/* 类名 */
.header {
  /* 样式 */
}

/* ID 名 */
#myId {
  /* 样式 */
}

/* 变量 */
$primaryColor: #333;

/* 混合 */
@mixin flexCenter {
  display: flex;
  justify-content: center;
  align-items: center;
}

语义话命名：所有命名推荐使用语义话命名，命名要具有描述性。

/* 不推荐 */
.w100 {
    width: 100px;
}

/* 推荐 */
.mini-box{
    width: 100px;
}

代码格式

缩进：使用两个空格进行缩进。并且每个属性占一行。

代码注释：在代码中添加必要的注释，解释当前模块内容。

属性顺序：按照功能分组，将样式属性按照功能分组，定位属性、盒子模型属性、文本属性、背景属性等。

具体顺序：
- 定位属性：position、top、right、bottom、left、z-index
- 盒子模型属性：display、flex、float、width、height、margin、padding、border
- 文本属性：font、color、text-align、line-height
- 背景属性：background、background-color、background-image
- 其他属性：opacity、transition、animation

使用缩写：对于可以缩写的属性，使用缩写形式。

示例：

/* 不推荐 */
.box {
  margin-top: 10px;
  margin-right: 20px;
  margin-bottom: 10px;
  margin-left: 20px;
}

/* 推荐 */
.box {
  margin: 10px 20px;
}

去除0值单位：对于值为0的属性，去除单位。

示例：

/* 不推荐 */
.box {
  margin: 0px;
}

/* 推荐 */
.box {
  margin: 0;
}

避免嵌套过多：避免嵌套过多，保持代码简洁。

选择器

避免使用通配符选择器：会匹配所有元素，影响性能。

避免标签选择器：尽量使用类选择器，避免使用标签选择器。提高可复用性和可维护性。

/* 不推荐 */
h1 {
    color: red;
}

/* 推荐 */
.title {
    color: red;
}

推荐子选择器：使用子选择器，避免使用后代选择器。使用子选择器可以提高选择器的精确度，避免不必要的匹配。

/* 不推荐 */
.container .item {
    color: red;
}
/* 推荐 */
.container > .item {
    color: red;
}

兼容性

使用前缀：对于需要兼容的属性，使用浏览器前缀，如 -webkit-、-moz-、-o-、-ms-。

/* 使用前缀 */
.box {
    -webkit-transform: rotate(45deg);
    -moz-transform: rotate(45deg);
    -o-transform: rotate(45deg);
    -ms-transform: rotate(45deg);
    transform: rotate(45deg);
}

JavaScript 规范

命名规范

变量函数：使用小写字母开头的驼峰命名法。例如：pageSize、getUserList()。

如果是方法函数，则使用动词开头。例如：getUserList()、updateUser()、deleteUser()。
常用动词：增加（add）、删除（delete）、修改（update）、获取（get）、设置（set）、创建（create）、保存（save）、提交（submit）、取消（cancel）、关闭（close）、打开（open）、显示（show）、隐藏（hide）、重置（reset）、刷新（refresh）、加载（load）、上传（upload）、下载（download）、打印（print）、导入（import）、导出（export）等。

常量命名：全部大写，单词间用下划线隔开。例如：MAX_SIZE、USER_TYPE。

类命名：使用大写字母开头的驼峰命名法。

避免使用缩写：变量名和函数名应尽量使用完整的单词，避免使用缩写。除非是非常常见的缩写，如 URL、HTML 等。

代码格式

统一缩进：使用两个空格进行缩进。

单独空行：不同逻辑，不同功能，不同模块之间，使用单独空行进行分隔。提高代码可读性。

字符串：全部使用单引号，避免使用双引号。

代码规范

ES6 语法：优先使用 ES6 语法，如箭头函数、模板字符串、解构赋值等等。

使用 let 和 const 声明变量，避免使用 var。

// 不推荐
var name = 'John';

// 推荐
let name = 'John';
const age = 30;

箭头函数：使用箭头函数来简化函数声明。提高代码简洁性和可读性。

字面量：使用字面量来创建对象和数组，避免使用构造函数。

// 不推荐
const obj = new Object();
const arr = new Array();
// 推荐
const obj = {};
const arr = [];

禁止eval：禁止使用 eval() 函数，避免安全风险和性能问题。

使用大括号：在控制语句（如 if、for、while 等）中使用大括号，即使只有一行代码。

// 推荐
if (condition) {
  doSomething();
}

避免多层嵌套：条件判断和循环最多嵌套三层，避免多层嵌套。

this 转换：this 的命名转换统一使用 self 表示。

is开头布尔值：布尔值变量，以 is 开头，如：isLogin、isError。

删除 console：生产环境删除 console.log、console.error 等调试代码。

错误处理

使用 try...catch 在可能抛出错误的代码块中进行错误处理。

try {
  // 可能会抛出错误的代码
} catch (error) {
  // 错误处理
}