前端开发规范

what

我把开发规范分成三个大类：

代码层面规范
接口规范
git 规范

从范围来看，代码层面规范是针对个人的；接口规范针对前后端开发团队；git规范针对的是整个开发测试团队。

规范分类

关于代码规范

一般来说，一个项目大多是由多人合作开发的，即使目前是由个人开发的项目，也要提前想到后续也会交接给其他人；在团队中，我们一直都需要相互协作，其中代码的协作在开发过程中显得尤为重要。代码规范其实就是一个团队的成员，基于各类开发文档，并且结合了团队日常的业务需求，以及团队在日常开发过程中总结提炼出来的经验，制定而成的编写代码的规则，是需要团队成员一起遵循和维护的。

关于接口规范

所谓接口就是程序之间进行数据交互的媒介，通过访问接口可以获得需要的数据。好的接口规范能约束开发人员，能降低前后端人员之间的沟通协调，能避免后期联调带来的一系列问题。

关于git规范

git规范是项目代码或者文件的提交规范；通常我们使用git的一大原因就是它的可追溯性，有明确的提交人，提交时间，提交描述等信息，提交日志明确清晰，在项目review的时候，可以有效地定位责任人。

why

促进团队合作
减少 bug 处理
降低维护成本
有助于代码审查
有助于自身的成长

how

代码层面

通用的代码规范

目录命名

全小写
单词间使用短横线连接
使用模块-子模块这种命名方式

注释

单行注释：一般写在需要注释代码的上一行；
多行注释：一般写在函数或模块的上方
文件注释：一般写在文件开头

变量命名

变量命名时使用小驼峰；
类名使用大驼峰；
方法名使用小驼峰并采用动宾结构；
常量命名全大写并使用下划线连接；

变量命名

代码风格

空格还是 tab
单引号还是双引号
大括号要不要换行
函数名后面要不要空格
…

这些格式方面的规则，其实很繁琐，而且又不容易统一；即使团队能统一出一个结果，自己写了这么久的风格还要改变去适应团队风格，是还蛮累的，一时半会儿都不能适应，所以我会建议直接选用代码格式化工具eslint / prettier；

这俩工具都内置有代码风格格式，同时也支持自定义规则覆盖默认规则（不建议）；

IDE 使用：安装插件，以 vscode 为例；

项目使用：安装依赖包，在项目配置中启用，以Vue项目为例；

HTML

语义化

HTML5 代码规范

文档类型：推荐使用 HTML5 的文档类型声明，<!DOCTYPE html>；
属性名：全小写，短横线分隔；
引号：属性值使用双引号；
…

CSS

类名书写规范：BEM 规范
属性书写顺序，最佳实践：
- 布局定位属性：display / position / float / clear / visibility / overflow
- 自身属性：width / height / margin / padding / border / background
- 文本属性：color / font / text-decoration / text-align / vertical-align / white- space / break-word
- 其他属性（CSS3）：content / cursor / border-radius / box-shadow / text-shadow / background:linear-gradient …

BEM规范 Element

JS

Vue

Vue 官方风格指南

接口规范

目前主流的 Web 服务交互方案有三种，REST，SOAP 以及 XML-RPC，目前我们使用的是 RESTful 风格，REST 倾向于用更加简单轻量的方法设计和实现，但是 REST 并没有一个明确的标准，而更像是一种设计的风格。

RESTful 有以下特点：

每一个 URI 代表 1 种资源；

// 针对user表，只有一个路径
// 资源路径不应该包含动词，只应该有资源名（不绝对）
const url = 'https://api.xxx.com/path/user';

客户端使用 GET、POST、PUT、DELETE4 个表示操作方式的动词对服务端资源进行操作：GET 用来获取资源，POST 用来新建资源（也可以用于更新资源），PUT 用来更新资源，DELETE 用来删除资源；

const getUser = {
  method: 'GET',
  url: 'https://api.xxx.com/path/user'
};
const addUser = {
  method: 'POST',
  url: 'https://api.xxx.com/path/user'
};
const updateUser = {
  method: 'PUT',
  url: 'https://api.xxx.com/path/user'
};
const deleteUser = {
  method: 'DELETE',
  url: 'https://api.xxx.com/path/user'
};

在接口路径上添加版本号；

// 发布时采用增量发布
const getUserV1 = {
  method: 'GET',
  url: 'https://api.xxx.com/path/v1/user'
};
const getUserV2 = {
  method: 'GET',
  url: 'https://api.xxx.com/path/v2/user'
};

客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。通俗点讲就是需要传入查询参数；

// 带参数的请求，请求参数为userid=123
const getUser = {
  method: 'GET',
  url: 'https://api.xxx.com/path/user/123'
};
// 多参数请求，参数为username=abc, age=10
const getUser = {
  method: 'GET',
  url: 'https://api.xxx.com/path/user/username/abc/age/10'
};

响应，其中响应状态码code参数有多个可选值，一般200+表示正常响应，300+表示参数错误，400+表示资源或者权限错误；

// 响应参数格式
const response = {
  code: 200,
  msg: 'response message',
  data: {
    // ...
  }
};

分页过滤信息，有时遇到数据量比较多的情况，就需要采用分段式传输的方法；

// 若记录数量很多，服务器不可能返回全部记录给用户
// API应该提供分页参数及其它筛选参数，过滤返回结果

// 指定第几页，以及每页的记录数
const getProducts = {
  method: 'GET',
  url: '/v1/products?page=1&pageSize=20'
};

// 指定返回结果按照哪个属性排序，以及排序顺序
const getSortedProducts = {
  method: 'GET',
  url: '/v1/products?sortBy=name&order=asc'
};

一致性原则

字段尽量不冗余；
接口更新时尽量做到与原始提交的数据结构差不多；
时间日期这些公共参数要保持格式一致；

接口文档

尽量都有接口在线测试，目前使用Swagger UI来在线测试接口

git 提交规范

目前使用较多的 git commit message 规范是 angular 规范，是由谷歌 angularJS 团队使用的，有参考手册，还有配套工具，使用起来也比较方便。

规范的执行方案如下图：

Git提交格式

提交格式

提交格式要求

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

type

type	des
feat	新增功能
fix	修复 bug
docs	文档类修改
style	代码格式类修改
refactor	代码重构
perf	优化
test	测试类
chore	依赖库或构件工具类
revert	回退

scope（可选的）

修改范围；

subject

summary，修改的简短描述；

body（可选的）

详细描述

footer（可选的）

适用于改动后的代码与上一版本不兼容，或关闭 issue，这两种情况需要填写

工具

提交工具 commitizen，帮助我们生成 commit message；
生成 CHANGELOG.md 工具conventional-changelog，把 Git Commit Message 的消息自动生成 CHANGELOG.md；
Message 检查工具validate-commit-msg，是否有 “不符合” 规范的内容，可以在 GitHook 中使用；

开发规范讲解