# 入门指南
# 简介
该框架为类sass系统基础开发框架，我们提供很多开箱即用的功能。框架从浙江使用到现在(2020-2-22)，经历了接近八个月的用户考验，可用性和稳定性已经比较成熟。
目前为了进一步提高开发效率，对所有常用组件再次进行打磨封装，主要解决效率和一致性。这次框架更新将为未来所有后台管理系统
类型项目提供标准模板。
# 如何开始项目
- gitlab 地址
fork项目到本地，安装依赖并运行项目。
TIP
最好通过fork形式进行项目拉取，非开发用户没有提交代码权限，采用克隆方式只能在本地运行。
# 项目结构
│ App.vue //入口(挂载)组件
│ config.default.js //全局配置文件
│ main.js //入口js文件
│
├─api
│ api.js //请求拦截，全局请求设置
│
├─assets //静态资源目录(与public相比，此目录资源会被wwebpack解析为依赖)
│ ├─css
│ ├─imgs
│ └─js
│
├─components //公共组件目录
│ │ index.js //配置文件，可以免除组件注册
│ │
│ ├─common //自定义的第三方组件
│ │
│ └─vendor //第三方组件(echarts之类)
│
├─directive //全局指令
│
├─lib //工具函数(工具库)
│ utils.js
│
├─logs //错误日志上报功能
│ index.js
│
├─mixin //全局混入，在全局范围使用
│ │ index.js
│ │
│ ├─computed //全局计算属性
│ │ index.js
│ │
│ ├─filters //全局filter
│ │ index.js
│ │
│ ├─methods //全局方法
│ │ index.js
│ │
│ └─props //全局props
│ index.js
│
├─mock //mock相关功能
│
├─pages //所有业务存在界面
│ ├─layout //布局页面
│ │ │ index.vue
│ │ │
│ │ ├─content
│ │ │ content.vue
│ │ │
│ │ └─header
│ │ header.vue
│ │ step.js
│ │
│ ├─login //登录注册相关界面
│ │ login.vue
│ │
│ └─model //业务模块
│ └─a
│ a.vue
│
├─router //路由模块
│ index.js
│
├─scss //scss相关,参考ui规范
│ │ index.scss
│ │
│ ├─global
│ │ _global.scss
│ │ _mend.scss
│ │
│ ├─helpers
│ │ _functions.scss
│ │ _mixin.scss
│ │
│ ├─utils
│ │ _utils.scss
│ │
│ └─variables
│ _variables.scss
│
└─store //全局store
index.js
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
# 目录简介
为了简化开发上手难度，我们对外屏蔽实现细节，如果你对实现细节感兴趣，可以参考 架构详解。现在我们只需要关注src目录下的代码结构。
api目录 -----------------ajax请求，提供请求和返回拦截相关钩子
assets目录---------------静态资源目录，存放一些静态图片或者css资源(webpack会处理这个目录下面文件)
components目录-----------公共组件目录(图片上传组件，富文本组件等)
directive目录------------全局指令(后台同事可以忽略该目录)
lib目录------------------第三方js文件(主要为签名文件，公共类库)
logs目录-----------------前端日志系统(可忽略)
mixin目录----------------前端全局注入(指令，方法，filter，计算属性)
mock目录-----------------前端本地mock功能，可提供ajax拦截mock数据()
pages目录----------------所有业务逻辑全部在该目录下面
router目录---------------前端路由
scss目录-----------------前端样式
store目录----------------vuex
App.vue文件--------------入口vue文件(全局挂载点)
config.default文件-------配置文件，大量功能基于配置
main文件-----------------主入口文件，主要用于初始化一些东西
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# api目录
# 简介
这个目录用于处理前后端交互，提供数据请求和数据屏蔽了具体实现细节，开发者可以直接在组件中使用。api目录详解
项目整个ajax请求基于axios，这也是目前社区比较成熟的实现方案。
# 用法
# GET请求
//无参数请求
this.axios.get("/api/goods").then(res => {
console.log(res); //返回值
}).catch(err => {
this.$errorThrow(err, this); //错误处理
});
//携带参数,最终路径 /api/goods?price=20&name=粽子
const params = {
price: 20,
name: "粽子"
};
this.axios.get("/api/goods", { params }).then(res => {
console.log(res); //返回值
}).catch(err => {
this.$errorThrow(err, this); //错误处理
}).finally(() => {
this.loading = false; //做一些收尾工作
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
TIP
get请求传参只允许以查询字符串形式，http规范
# POST请求
//无参数请求
this.axios.post("/api/goods").then(res => {
console.log(res); //返回值
}).catch(err => {
this.$errorThrow(err, this); //错误处理
});
//携带参数
const params = {
price: 20,
name: "粽子"
};
this.axios.post("/api/goods", params).then(res => {
console.log(res); //返回值
}).catch(err => {
this.$errorThrow(err, this); //错误处理
}).finally(() => {
this.loading = false; //做一些收尾工作
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
TIP
注意13行传参方式与get请求的区别，post请求默认以json格式传输数据，数据存放于Request Body
# PUT请求
//无参数请求
this.axios.put("/api/goods").then(res => {
console.log(res); //返回值
}).catch(err => {
this.$errorThrow(err, this); //错误处理
});
//携带参数
const params = {
price: 20,
name: "粽子"
};
this.axios.put("/api/goods", params).then(res => {
console.log(res); //返回值
}).catch(err => {
this.$errorThrow(err, this); //错误处理
}).finally(() => {
this.loading = false; //做一些收尾工作
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
TIP
除get请求以外，所有请求数据均以request body方式承载。
# DELETE请求
//无参数请求
this.axios.delete("/api/goods").then(res => {
console.log(res); //返回值
}).catch(err => {
this.$errorThrow(err, this); //错误处理
});
//携带参数, /api/goods?id=3
const params = {
id: "3"
};
this.axios.delete("/api/goods", { params }).then(res => {
console.log(res); //返回值
}).catch(err => {
this.$errorThrow(err, this); //错误处理
}).finally(() => {
this.loading = false; //做一些收尾工作
});
//携带参数, requestBody
const params = {
id: "3"
};
this.axios.delete("/api/goods", { data: params }).then(res => {
console.log(res); //返回值
}).catch(err => {
this.$errorThrow(err, this); //错误处理
}).finally(() => {
this.loading = false; //做一些收尾工作
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
TIP
delete方式以request body方式请求数据与前面几种方式略微有所不同，23行标注了delete以requestBody方式请求数据。
# 注意
项目中所有请求都应该采用上述请求方式进行请求，包括一些文件下载和pdf预览，这样做的目的是为了让所有请求都可以被错误日志捕获到，有利于后期错误定位和代码维护。http规范
# assets 目录
# 简介
用于存放一些静态资源，例如：css，js，图片这种静态资源，需要注意该目录下文件会被webpack进行打包，会被file-loader加载。现阶段应用于一些无法转换为字体图标的图片。
# 用法
├─assets
│ ├─imgs
│ └─bg.png
│ ├─css
│ └─index.css
2
3
4
5
// 在template中使用图片
<img :src="require('@/assets/imgs/bg.png')" alt="背景图片">
2
// 在main.js中引用css文件
import "@/assets/css/index.css"
2
TIP
@在webpack中配置为路径的别名，在当前系统中，@代表src目录，这是一个非常有用的特性，你可以不用使用../../xxx之类的相对路径来寻找文件。相关参考
# 注意
小图片或者一些静态资源推荐存放于assets目录，不推荐存放在public目录下面。
# components 目录
# 简介
存放全局公共组件，可以非常方便的进行组件复用。实现细节require.context
# 用法
//目录结构
├─components
│ ├─common
│ └─g-a.vue
│ ├─vender
│ └─g-charts.js
2
3
4
5
6
//以g开头的文件，会自动注册为全局组件，无需显式引用，直接将 g 替换为 s 即可使用
<template>
<div>
<s-a></s-a>
<s-charts :options="options"></s-charts>
</div>
</template>
2
3
4
5
6
7
# 注意
只有g-开头，并且以 .js或.vue结尾的文件才可以自动注册为全局组件，使用的时候需要将g-替换为s-。
# directive 目录
# 简介
存放全局公共组件，可以非常方便的进行组件复用。vue指令
# 用法
//目录结构
├─directive
│ ├─drag.js
│
2
3
4
//drag指令让元素可以拖动
<template>
<div v-drag class="w-100 h-100 bg-red"></div>
</template>
2
3
4
# 注意
指令可以进行dom元素相关操作，在某些条件下使用会让开发变得非常方便。
# lib 目录
# 简介
工具函数库，提供大量方便的函数，部分函数命名规范遵照lodash。库函数的目标是进一步降低js开发难度。
# 用法
//目录结构
├─lib
│ ├─array
│ └─unique.js
│
│ └─index.js
2
3
4
5
6
//unique方法用于去重扁平数组或者指定条件的嵌套数组
import unique from "@/lib/array/unique" //或者 import { unique } from "@/lib"
const arr = [{id: 1}, {id: 2}, {id: 1}];
unique(arr, "id"); // [{id: 1}, {id: 2}]
2
3
4
# log 目录
# 简介
前端日志，需要独立的后台日志接收系统进行日志存储，若无前端日志需求则可以忽略当前目录。
# 用法
this.axios.get("/system/menu/system").then(res => {
//res
}).catch(err => {
this.$errorThrow(err, this); //日志上报
});
2
3
4
5
# 注意
前端日志是一个比较庞大的体系，是整个前端生命周期必不可少的环节，在未来我们将提供更加方便的前端错误捕获机制。
# mixin 目录
# 简介
将computed(计算属性) filters(过滤器) methods(方法) props以全局方式混入vue组件中，大大提高了代码的复用。混入
# 用法
//目录结构
├─mixin //全局混入，在全局范围使用
│ │ index.js
│ │
│ ├─computed //全局计算属性
│ │ index.js
│ │
│ ├─filters //全局filter
│ │ index.js
│ │
│ ├─methods //全局方法
│ │ index.js
│ │
│ └─props //全局props
│ index.js
2
3
4
5
6
7
8
9
10
11
12
13
14
15
//使用全局methods
<script>
export default {
methods: {
foo() {
this.getAncestorComponent("select"); //依次往上查找名称为 `select`的组件
}
}
};
</script>
2
3
4
5
6
7
8
9
10
# 注意
全局混入会影响每一个创建的组件，你应该非常明确这些混入是否会导致副作用,
# mock 目录
# 简介
提供数据mock，目前通过拦截 axios请求来进行本地mock，这种方式不会发送真实数据到数据库。mock本身会有一定学习成本，在业务系统实际开发过程中受限于后端
接口文档，在这类开发中实际使用率极低。我们正在想办法从api文档入手，提供一套比较完善的在线mock操作，方便前端同事调用。
# 用法
mock需要学习一定的mock语法，本章不具体介绍用法，未来希望以线上mock形式来更加真实的模拟数据。Mock
# 注意
目前提供mock功能通过拦截ajax请求进行前端模拟，在一定程度上无法真实体现出前后端交互的过程，同时mock在实践中由于需要花费一定程度开发实践，所以实际使用率很低。
# pages(route) 目录
# 简介
目录用于存放业务页面，pages目录下文件夹和文件的命名需要严格遵守规定。关于目录书写规范可以参考 文件文件夹命名规范。
vue路由参考
# 用法
一个完整路由应该包含的内容
interface Route {
path: "a-d-create", //路由地址
name: "新增计划", //路由名称
meta: {
title: "新增计划", //用于显示在tabs上面的标题
bread: [
{ to: "", title: "计划管理" }, //面包屑导航， to字符串不为空则可以跳转到相应位置
{ to: "", title: "计划草稿" },
{ to: "/v1/a/a-d-create", title: "新增计划" }
],
developer: {
name: "cc" //开发者信息(推荐使用自己姓名的拼音)
},
keyword: [], //用于搜索时显示相关路由信息
couldBeMenu: true, //这个路由是否能成为左侧菜单
couldShowGoBackTip: true, //是否展示返回上级按钮
couldCache: true, //页面是否允许被缓存,注意：页面可以被缓存，则无法存在多个tab
couldBeMulti: false, //页面是否允许存在多个tab
permission: [], //权限保留字段，未来页面权限将在这里面存取
},
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 注意
pages目录需要非常注意的就是文件夹和文件的命名要求，在大型后台管理系统中，规范的文件命名将会大大节省开发时间。
# scss 目录
│ index.scss //入口文件
│
├─global
│ _global.scss //全局变量
│ _mend.scss //覆盖第三方库的css
│
├─helpers
│ _functions.scss //自定义函数
│ _mixin.scss //自定义混合
│
├─utils
│ _utils.scss //工具css
│
└─variables
_variables.scss //scss变量
2
3
4
5
6
7
8
9
10
11
12
13
14
15
参考 UI规范