前端标准化之旅

作者：京东零售 陈艳春

本文主要是介绍前端研发的一些标准化规范，良好的代码规范，不仅能够让代码简洁清晰，还可以减少 bug 的出现，更能够让看代码的人赏心悦目，本文主要从命名规范、语法规范、后端系统开发规范、版本更新规范、上线邮件申请规范、项目启动规范来、文件目录规范七方面介绍，文档内如有错漏之处，敬请大家指正，会及时做出调整；也希望各位能够提出更宝贵意见和建议，使文档更加完善。当然如果感觉有可借鉴之处，欢迎大家采纳。

引言

前端标准化是我们践行前端工程化中重要的一部分，为什么要标准化呢？首先我们开发是需要多人开发的，每一个开发者都有各自的编码喜好和习惯，就是因为这个不同的编码习惯和喜好增加了我们项目的维护成本，所以每个项目或者团队需要明确统一的标准。

以下是我积累的一些前端规范以及一些个人建议：

一．命名规范

好的命名是通俗易懂，见名知意，即看 css 能很清晰明了的看出 html 的结构，优雅的 js 命名，可以看出每个 func 所处理的事情，清晰的文件和文件夹命名规范，有助于理解项目结构，以下介绍下我们日常积累的一些命名规范。

1. 文件夹使用短横杠命名法 (`xxx-xxx`)，vue、js、scss 等文件使用小写加中划线命名法 (`xxx-xxx`)

2. 组件开发规范

（1）根节点 class 必须是 "cp-xxx" 开头，xxx 对应的是组件的名称，组件里面的 class 以 cp-xxx 形式命名 class, 尽量不要使用 scoped。

（2）业务组件可以放在当前业务目录的 component 文件夹，import 导入时用 bcp-xxx 开头已和公共组件加以区分，其他规范和公共组件保持一致。

3. 方法命名：小写 + 驼峰 (xxxXxYy)，

4. 组件里面的 `name` 都必须使用 `Pascal` 命名法，组件使用名称类似 `xxx-xxx` 这样。

5. 路由跳转地址，不要直接写死链接地址，使用路由链接地址对应的 name 进行跳转。

6. css 命名规范：

1）样式：

a) 全局样式：app-*

b) 页面样式：pg-* pg-marking (marking 是模块)

c) 组件样式：cp-*

d) 样式属性顺序规范：js 有好的写法，推荐语法写法和不推荐语法写法

2）状态：

a) 全局样式：.show, .hide (全局状态命名尽量简单，不要有过多前缀)

b) 页面样式：pg-*_active (页面样式尽量只能在当前页面使用，必须添加前缀)

c) 组件样式：cp-*_active (组件样式尽量只能在当前组件使用，必须添加前缀)

d) 禁止使用 scoped，无论是在全局、页面还是组件内

7. 枚举值定义：全局事件名、本地存储的 key 值等需要抽离出单独的文件进行统一管理， 避免冲突。

二．语法规范

语法规范是为了提高工作效率，兼容性优良，页面性能优化，代码简洁、明了、有序，尽可能的减少服务器的负载，保证最快的解析速度。

1. 根据当前 eslint 的规范编写代码。

2. 尽可能的少用可变变量，能用 const 的就不要使用 let，完全不使用 var。

3. 拥抱 ES6：（举一些例子，顺带学习回顾下）

（1）赋值简写：`{data: data}` 可以写成 `{ data }`

（2）函数简写：`{data: function () {}}` 可以写成 `{data () {}}`

（3）对象取值：const {a,b,c,d,e} = obj || {}

（4）合并数据：

代替

（5）拼接字符串：

代替

 

（6）if 判断条件合集：

代替

（7）列表搜索

代替

（8）获取对象属性值

代替

（9）添加对象属性

代替

（10）输入框非空判断

代替

4. 使用 ES6 的箭头函数需要注意：

（1） ** 函数体内的 `this` 对象就是定义时所在的对象，而不是使用时所在的对象。**

（2） 不可以当做构造函数。也就是说，不可以使用 `new` 命令，否则会抛出一个错误。

（3）不可以使用 `arguments` 对象，该对象在函数体内不存在。如果要用，可以使用 `rest` 参数代替。（`rest` 参数使用自行查看《ES6 标准入门》）。

（4）不可以使用 `yield` 命令，因此箭头函数不能用作 `Generator` 函数。

（5）非必要情况，不要再元素上写 `style`。

三．后台系统开发规范

以下主要是针对后端开发系统的一些开发规范，主要是将整个网站统一风格，以达到更好的性能优化。

1. 二级菜单，一律加上面包屑

2.“重置” 按钮 一律是重置查询条件，不进行数据查询

3.input 一律加上 placeholder

4. 展示的 table，有些数据没有的话，要使用 - 展示

5. 数据至少大于等于 1 条时，才会显示分页

6.table 列表里面，在接口请求过程中一律加上 isLoading

7. 搜索结果为空，要加上空页面

8. 全局 loading：（需要加 loading 就在请求接口时，加上 isLoading:true）

需要使用的情况：

（1）进入页面记载数据

（2）提交表单

（3）接口是非幂等性的情况。

不需要使用的情况：

（1）打开弹窗时需要请求接口的

（2）接口是幂等性、响应快，且接口成功响应后要重新加载数据的情况

9. 列表分页默认 size:20，pageSizes:[20,50,100]，若是弹框内分页，默认 size:10，pageSizes:[10,30,50]

10. 翻页查询，比方说翻到第五页，点击查询，应该从 pageNo = 1 开始

四．版本号更新规范

版本规范的意义，是让开发者一眼查看到本项目的更新次数，以及本次更新的日期，开发人员，开发分支，能够快速的定位问题，了解项目迭代版本的内容。

X.Y.Z （主版本号。次版本号。修订号）

1. 版本号必须采用 X.Y.Z 的格式，其中 X、Y、Z 为非负的整数，且禁止在数字前方补零。X 是主版本号、Y 是次版本号、Z 为修订号。每个元素必须以数值来递增。

2. 修订号：当涉及原有页面修改，比如新增按钮、修改文案、bug 修复时递增.

3. 次版本号：当涉及新增一定（少量）功能模块，比如新增栏目、新增页面时递增。次版本号递增时，修订号必须归 0。

4. 主版本号：当涉及功能模块有较大的变动，比如增加多个功能模块或是整体架构发生变化时递增。主版本号递增时，次版本号和修订号必须归 0。

5. Changelog 写在项目的 README.md 里，采用倒序排列，即最新的写在最上边，模板如下：

### 2.0.0

- 更新主题：技师看板

- 更新时间：2022-02-23

- 开发人员：xxx

- 开发分支：dev-20220223-cyc -board

```

1、增加技师看板新页面

```

6. Changelog 和 package.json 里的版本号要同步更新

五：上线规范：

1. 上线时间规范

每周的周二和周四为上线日，这样就为研发和产品制定了一个规范，不用考虑每天加班熬夜上线，避免产品因 “项目紧急” 的缘由让研发临时上线，从而减少研发的压力。

2. 上线邮件申请规范

比如今天上线有 A 项目、B 项目、C 项目等等多个项目的时候，如果每个人上线的同学提交一个审批邮件，对于领导来说需要每天审批很多邮件，所以此时我们不得不制定一个标准。

目前的上线审批流程为：每周二和周四需求大的人负责发送当天的上线邮件申请，负责人提前收集好上线的需求，分支，review 人，流程步骤等信息。汇总一起发送邮件，此时领导只需要回复一个上线邮件即可。具体模版，如下：

 

六．项目启动规范

项目启动对于新入职员工，以及新人还是有一定的挑战的，特别是一些项目需要配置相关的 host，package.json 文件里面一般只是基础的启动，不会提示配置 host 等，此时就需要我们制定一个规范，比如在 README.md 文件下写上具体的启动步骤，以及每个环境需要配置的 host，具体如下：

有了以上的启动引导是不是不管谁开发都方便了很多，只要按照上面的步骤一步一步的进行，就不需要初次开发该项目的人员去找相关开发帮忙启动项目，并且也附加了登录账号等信息，大大提高人效数倍。

七：文件目录规范：

一个项目，有一个好的目录结构那是必不可少的。当我们项目越来越大时或者多人协作开发时，我们就更应该有一个清晰的目录结构。好的项目目录结构能够给我们带来诸多的好处，比如：每个功能或模块单独管理、代码的可读性增强、代码的可维护性增强、易于多人协作之间的沟通、接下来我将分享一下我在平时项目中总结的目录结构，当然这只是我个人的实践，欢迎大家提出更好的意见。

|---public

|---index.html（入口 html）

|---src

|---assets（静态资源）

|---css（全局样式）

|---js（全局 js）

|---images（静态图片）

|---components（基础组件）

|---hocs（业务组件）

|---layout（全局布局）

|---service（axios 接口封装）

|---store（vuex）

|---views/pages（页面）

|---App.vue

|---main.js（入口 js）

|---.editorconfig（编辑器配置）

|---.eslintrc（代码规范的配置）

|---.gitignore（Git 仓库忽略掉的文件或目录）

|---babel.config.js（babel 编译的配置）

|---package.json（项目配置文件）

|---README.md（项目描述）

|---vue.config.js（配置文件）