本文档详细介绍了公司内部的前端项目开发规范，包括项目架构、开发环境、开发规范、命名规则、版本管理和使用说明。项目基于Vue CLI 3.x构建，采用nodejs+webpack+vue+element-ui架构，使用axios进行HTTP请求，Vue CLI的eslint+prettier进行代码风格检查。开发规范涵盖组件化开发、结构和命名规范，同时强调代码提交和版本控制的注意事项。
前端项目说明
前言：注释说明
文档：各个编辑器的用户代码片段怎么设置
链接：http://note.youdao.com/noteshare?id=6340778e76ae1b4dd0171aac5848f8ab
前言：项目通用规则说明
1）一些重度级操作，例如删除，重置之类的操作，必须使用确认弹窗this.$confirm。
2）mixin.js文件里加了两个方法
openLoading(dom)：请求超过半秒没有回执，打开loading。参数为dom选择器，class用点，id用井号。
closeLoading()：请求收到回执，清除延时器，关闭loading。
3）mixin.js文件里加入了以下几个通用变量，减少开发过程中重复定义的工作量。视情况使用:
| 变量名称 | 类型 | 说明 |
|---|---|---|
| totalElements | Number | 分页总条数 |
| pageInfo | Object | 分页条件{page: 0,pageSize: 20} |
| searchParam | Object | 搜索条件 |
4）引入api.js文件里的方法，不再使用import * as api的方式，使用{}的方式，用什么引入什么，尽可能优化性能。
前言：项目css统一说明
1）原则上在项目中的css，不使用scoped属性。使用lang="scss"。
2) class命名规则使用BEM规范，BEM的命名规矩很容易记：
block-name__element-name--modifier-name，也就是模块名 + 元素名 + 修饰器名。
官网：https://bemcss.com/
当你想覆盖element-ui的class样式。千万不要直接用比如.el-form-item的方式去重写，
应该在父级给一个新的名字，利用子集选择器，比如.hangar-wrap .el-form-item这样的方式去覆盖样式。
3）原则上在项目中涉及到用字体大小，主题颜色，圆角，阴影等统一样式的时候，使用scss变量。尽量避免自己写死在css中（一些特定固定颜色除外）。具体参照element-variables.scss文件。
4）用于全局的class样式需要单独提出来，通过引入的方式，注入到app.vue文件中。
5）main.js中对element-ui的组件风格，大小进行了全局设置。原则上不需要单独设置某个控件的size。
6）placeholder灵活设置，不再像以往使用“请填写”，“请选择”字样。
前言：表格页规范说明
1）不要在开发过程中使用自己写的按钮。统一使用element-ui中的el-button。
2）列表对齐方式遵从以下规则：
*长度能保证一样的居中
*长度不一致的靠左对齐
*数字靠右对齐（单位写在列头）
3）使用容器布局的方式
4)搜索条件的排列规则：
*使用el-row和el-col布局方式，可以长短不一，但是一定要保证对齐
*搜索按钮始终放在最后一行的最右侧。具体页面具体调整,合理分配各个表单项所占的栅格，反正不允许让按钮单列一行
1. 项目架构
前端项目是采用nodejs+webpack+vue+element-ui架构的单页面应用，使用vue cli 3.x构建，项目依赖的组件如下
- 运行依赖
- MVVM核心框架
- vue
- vue-router
- vuex
- 消息总线
- vue-bus
- UI组件库
- element-ui
- HTTP库
- axios
- 自定义组件库
- hangar-vue-components
- 其他组件
- js-cookie
操作Cookie，用于存储令牌 - nprogress
轻量级的进度条插件 - normalize.css
保证HTML元素的默认样式跨浏览器一致性
- js-cookie
- MVVM核心框架
- 开发依赖
- Vue CLI 相关插件
- @vue/cli-plugin-babel
- @vue/cli-plugin-eslint
- @vue/cli-service
- vue-template-compiler
- ESLint 相关插件
- babel-eslint
- eslint
- eslint-plugin-vue
- @vue/eslint-config-prettier
- CSS相关插件
- node-sass
- postcss-cssnext
- postcss-import
- postcss-url
- saladcss-bem
- sass-loader
- Svg图标处理
- svg-sprite-loader
- Mock工具
- mockjs
- 接口生成
- grunt
构建的工具，调用swagger-vue - swagger-vue
根据swagger文档生成调用接口的插件
- grunt
- Vue CLI 相关插件
2. 开发环境
- 开发语言
ECMAScript 6 - Node.js
推荐v10.14.2以上版本
1）Node.js的安装配置请参考windows下安装Node.js
2）配置Node.js私服，地址为： http://110.249.209.86:8081/repository/npm/ - Vue CLI
推荐3.2.x版本，Vue CLI安装请参考Vue CLI 3.x安装 - Grunt
推荐v1.3.2以上版本，推荐全局安装，步骤如下：
1）已安装好Node.js
2）使用管理员身份打开命令行窗口
3）运行：npm install -g grunt-cli - IDE
推荐IDEA、WebStorm，并且安装Vue.js、Prettier（WebStorm已自带）插件- IDE设置
1）设置JavaScript语言级别
2）在项目目录执行npm install后设置Prettier插件的package
3）为保持代码的一致性，请使用.editorconfig文件进行编辑器的设置，采用的设置如下：
[*] charset=utf-8 end_of_line=crlf insert_final_newline=false indent_style=space indent_size=2 [*.{js,jsx,ts,tsx,vue}] trim_trailing_whitespace = true insert_final_newline = true - IDE设置
3. 开发规范
3.1 风格指南
请阅读官方的风格指南-Vue.js
3.2 基于组件化开发
- 什么是组件
组件是页面组成的一部分，它是一个具有独立的逻辑和功能或界面，同时又能根据规定的接口规则进行相互融化，变成一个完整的应用。
页面只不过是这样组件的容器，组件自由组合形成功能完整的界面，当不需要某个组件，或者想要替换某个组件时，可以随时进行替换和删除，而不影响整个应用的运行。
前端组件化的核心思想就是将一个巨大复杂的东西拆分成粒度合理的小东西。
- 组件化开发的好处
提高开发效率
方便重复使用
简化调试步骤
提升整个项目的可维护性
便于协同开发
高内聚，低耦合，达到分治与复用的目的。
- 组件化和模块化的区别
组件化是从产品功能角度进行分割，模块化是从代码实现角度进行分割，模块化是组件化的前提和基础。
- Vue组件化开发
单文件系统
基本组成结构：<template/><script/><style/>
组件注册方式：
1）公共组件全局注册
2）其余组件局部注册
3.3 结构规范
1）项目结构应基于Vue CLI脚手架生成的结构
.
| .browserslistrc nodejs目标浏览器配置
| .env.development 系统环境配置(开发环境)
| .env.production 系统环境配置(生成环境)
| .eslintrc.js eslint配置
| .prettierrc prettier配置
| babel.config.js babel配置
| Gruntfile.js Grunt构建配置
| package.json npm包配置文件，里面定义了项目的npm脚本，依赖包等信息
| pom.xml 前端Maven项目的配置，调用npm进行打包后打包成jar
| postcss.config.js postcss的配置文件
| README.md 项目说明文件
| vue.config.js Vue CLI的自定义配置，如需更多自定义配置请阅读https://cli.vuejs.org/config/
|
+---public 前端静态页面目录
| favicon.ico 图标
| index.html 前端入口页面
|
\---src 项目源码目录
| App.vue Vue入口根组件
| main.js Vue入口js文件
|
+---api 访问后端的接口目录
| api-docs.json 后端Swagger文档声明
| api.js 访问后端的接口，通过grunt generate-api生成
|
+---assets 资源目录
| |
| +---icons 图标目录
| | | index.js
| | |
| | \---svg SVG图标文件目录
| | *.svg
| |
| \---images 图片存放目录
| *.png
|
+---components 项目内公共组件目录
| \---SvgIcon Svg图标组件
| index.vue
|
+---directive 项目内公共指令目录
| \---permission 权限指令目录
| has-permission.js
| index.js
|
+---mock 接口模拟的目录
| api.js 模拟的后端接口
| index.js mock的配置
|
+---router 路由配置的目录
| index.js 路由的声明
| navigation-guards.js 路由导航守卫
|
+---store Vuex应用级数据
| | getters.js Vuex的getter声明
| | index.js Vuex的导出文件
| |
| \---modules Vuex模块
| app.js 应用数据
| permission.js 权限数据
| tab.js 多标签页数据
| user.js 用户数
|
+---styles 样式文件目录
| element-ui.scss element-ui的样式引用
| element-variables.scss element-ui的样式变量引用，可覆盖里面的变量实现自定义主题
| variables.scss 项目内定义的样式变量
| mixin.scss scss混入的定义
| index.scss 所有样式的导入文件(不导入element-ui.scss，避免重复打包)
| main-layout.scss 主界面布局样式
| form-page.scss 表单页公共样式
| list-page.scss 列表页面公共样式
| [*.scss] 其他样式文件
|
+---utils 工具类目录
| axios.js axios的全局定义，请求和响应的拦截，全局的错误处理
| dictionary.js 后端字典数据工具类
| enum.js 后端枚举数据工具类
| index.js 常用的工具类，同时导出了dictionary和enums
| result-code.js 全局状态码定义
| token.js 存取令牌的工具类
|
\---views 页面目录
| Home.vue 首页
| Login.vue 登录页面
| Redirect.vue 前端重定向公共页面
|
+---errors 错误页面目录
| 404.vue 404页面目录
|
+---layout 应用布局目录
| | Layout.vue 布局页面
| |
| +---components 布局组件目录
| | | index.js 布局组件导出文件
| | | MainPanel.vue 布局主面板
| | | TabPanel.vue 布局标签页签面板
| | | TopPanel.vue 布局头部面板
| | |
| | \---MenuPanel 菜单面板
| | index.vue 菜单页面组件
| | Item.vue 菜单项组件
| | Link.vue 外部连接组件
| | MenuItem.vue 菜单条目组件
| |
| \---mixin 布局的mixin方法目录
| index.js
|
|---system 系统管理模块目录
| +---departments 部门管理模块目录
| | index.vue
| |
| +---organizations 组织机构管理模块目录
| | index.vue
| |
| +---roles 角色管理目录
| | index.vue
| |
| \---users 用户管理目录
| index.vue
| UserForm.vue
|
\---[其他模块目录]
2）vue文件基本结构
<template>
<!--模板内容-->
</template>
<script>
export default {
components : {
},
data () {
return {
}
},
methods: {
},
mounted() {
}
}
</script>
<!--声明样式语言-->
<style lang="scss">
</style>
3）vue文件方法声明顺序
- components
- props
- data
- created
- mounted
- activited
- update
- beforeRouteUpdate
- metods
- filter
- computed
- watch
3.4 命名规范
3.4.1 目录命名
3.4.1.1 组件目录命名
1）组件统一放到components目录下属于components目录下的子目录，使用大写字母开头的PascalBase风格
2）全局通用的组件放在 /src/components下
3）业务页面中的组件，放在各自页面下的 ./components文件夹下
4）每个components文件夹下最多只有一层文件夹，且目录名称为组件的名称，文件夹下必须有index.vue或index.js，.vue文和子目录统一大写开头PascalBase风格
5）组件的名称、导入/导出，统一使用大写字母开头的PascalBase风格
3.4.1.2 非组件目录命名
组件以外的其他目录统一使用kebab-case的风格
3.4.2 文件命名
3.4.2.1 *.js文件命名命名规范
1）属于类的.js文件，除index.js外，使用PascalBase风格
2）其他类型的.js文件，使用kebab-case风格
3.4.2.2 *.vue文件命名规范
除index.vue之外，其他.vue文件统一用PascalBase风格
3.4.2.3 *.scss文件命名规范
统一使用kebab-case命名风格
4 版本管理
- IDE的项目文件(.idea,*.iml)请加入到版本控制的忽略列表，禁止提交到版本库
- 编译产生的目录(target、dist等)以及npm包本地安装相关的目录和文件(node_modules、package-lock.json)请加入到版本控制的忽略列表，禁止提交到版本库
- 提交时必须写清楚本次提交的变动内容，禁止不写注释的提交
- 提交到版本库中的代码必须是可以编译运行的代码，禁止将不可编译运行的代码提交到版本库
- 提交代码前请使用npm run lint进行代码风格的检查和格式化，保证符合编码规范的要求，禁止不符合规约的代码提交到版本库
- 合理使用版本控制的分支功能，迭代中的项目线上版本的发布应建立对应的分支并保持代码与发布版本的一致，
对线上版本的修改、BUG修复等应在分支上进行并及时合并到主干 - 尽可能的及时提交代码，每天或者每个功能完成应将代码提交到版本库
5. 使用说明
5.1 编码风格
1）项目已经配置了eslint+prettier的代码风格检查，可以运行npm run lint进行代码检查和格式化
2）我们在Vue CLI提供的默认配置基础之上，自定义的以下规则
- js代码必须以分号结尾
- 生产环境禁止console和debugger
- 单行代码最大长度为100
- 字符串常量使用单引号
3）IDEA中使用ALT+SHIFT+CTRL+P快捷键进行代码格式化
5.2 路由配置
1）所有页面路由在ruter/index.js进行配置
2）在router的mata属性声明该路由的配置属性，指出的属性包括如下：
- permission
权限代码，应与后端权限配置的代码保持一致 - icon
图标，对应菜单的图标 - title
路由的标题，在多标签布局中对应标签的标题 - closable
路由的标题，在多标签布局中是否可以关闭 - keepAlive
页面是否需要keepAlive
5.3 HTTP请求
1）与后端的HTTP请求采用axios实现
2）在utils/axios.js里面配置了全局的拦截器，配置了全局的Header以及全局的异常处理
3）为了代码的简洁性，对于正常响应结果进行了简化，直接返回response的data对象，使用时需要注意！
5.4 用户认证
1）项目采用OAuth2.0协议中的password模式与后端接口进行用户认证，认证时需要携带client_id和client_secret参数（由服务端配置并分配）
2）在api/auth.js里面提供了默认的认证接口实现，认证接口的地址以及client_id和client_secret在.env中进行配置
3）对于令牌的存储目前采用Cookie的方式，登录成功后会通过utils/token.js存储到Cookie中，并且在utils/axios.js进行了全局的Header设置，读取Cookie中存储的令牌
5.5 后端接口
项目提供了基于grunt的后端接口代码生成工具，使用方法如下：
1）复制后端接口的swagger文档的json内容到api/api-docs.json
2）在项目跟目录运行：grunt generate-api
3）在api目录会生成后端接口调用的api.js
4）后端接口更新时请重复以上步骤
注意：不要手工修改api.js的代码，重新生成是会被覆盖
5.6 权限管理
1）页面级的权限控制通过路由的导航守卫实现，在router/navigation-guards.js里面提供默认的导航守卫实现
2）页面元素级的控制通过指令实现，在directive/permission下提供里默认的权限指令any-permission和all-permission，可以自行扩展
5.7 页面布局
1）项目提供了默认的多标签的布局实现，可以根据项目实际情况进行调整
2）页面布局实现在layout目录，在标签页面需要引入mixin目录提供的方法处理页面关闭时keepAlive数据的销毁，如果页面需要关闭自己可以调用mixin提供的closeTab方法
5.8 Vuex应用级数据
在store目录提供了基于Vuex的应用级数据管理，具体请查看相关代码实现
5.9 样式
1）项目使用scss语法进行css预处理
2）组件的样式在组件内进行处理，项目全局的页面的样式在styles目录处理，应按照功能或模块放到不同的文件里面
3）不推荐使用样式的scope功能（不利于进行全局的覆盖）
4）为了避免样式冲突，项目CSS采用BEM命名规范，有关BEM的规范的介绍请点击这里
5）项目已经在postcss的配置中配置了saladcss-bem插件，可以在scss文件中使用BEM语法，示例如下
@b nav { /* b is for block */
@e item { /* e is for element */
display: inline-block;
}
@m placement_header {
background-color: red;
}
}
对应编译后的css如下：
.nav {}
.nav__item {
display: inline-block
}
.nav--placement_header {
background-color: red
}
5.9 Mock
在mock目录提供基于mockjs的后端接口模拟的简单示例，更高级的用法请自行研究
5.10 可复用组件
目前在公司的私服发布了hangar-vue-components的组件，
目前仅提供了以下组件：
- HcTable
基于element-ui的表格组件，封装了分页、服务器端数据请求 - HcSearchableTable
基于HcTable封装了查询条件表单，工具栏、表格组件
5.11 devServer
在vue.config.js中提供了默认的proxy代理设置，以解决开发时对后端接口访问的跨域问题
6 运行/打包
6.1 安装依赖
npm install
6.2 开发环境运行
npm run serve
6.3 生成环境打包
npm run build
6.4 生成前端项目文档
npm run docs
6.5 打包成jar
mvn package
扫一扫
1808
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
