前端标准化之旅

时间:2023-02-20 11:11:08

作者:京东零售 陈艳春

本文主要是介绍前端研发的一些标准化规范,良好的代码规范,不仅能够让代码简洁清晰,还可以减少 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(配置文件)