uni-app：关于小程序开发规范与架构设计的理解

前言

相关资料地址：

• uni-app 官方地址
• uview-ui 官方地址
• uni-app开发微信小程序——从工具下载到运行项目

1、忽略文件管理

根目录添加【.gitignore】文件，复制一下需要忽略的目录或文件。当项目需要在git上面管理的话，一定要在首次创建提交前提交到git，否则会出现忽略无效的情况。

unpackage
.hbuilderx
node_modules

如果出现设置忽略无效的情况，参照文档：git如何停止追踪未被追踪的文件和已被追踪的文件。

打开终端，主要执行命令如下：

// 1、切到对应的项目目录下面
cd /Users/xxx/xxx

// 2、对已追踪的文件，先清除原文件的缓存
git rm -r --cached .

// 3、重新提交推送生效文件
git add .
git commit -m “重新建立忽略文件追踪关系”
git push

2、API配置与管理

1、所有内容来自uVIew官方文档。
2、请求协议底层架构，使用的是【uview-ui】框架的【uview-ui/request】实现。

2.1、请求协议管理

1、说明文档：
1.1、请求类型有：get、post、put、delete，以及上传下载等请求。
1.2、配置参数：一次配置，全局通用的:$u.http.setConfig()。
1.3、请求拦截和响应拦截(如配置，每次请求都会执行)：此两个拦截，是可选配置的。

2、项目应用
2.1、该小程序的配置参数和拦截器位置见：【api/http.interceptor.js】
2.2、配置参数设置：baseUrl（域名）、dataType（解析格式）、header（请求头）
2.3、请求拦截设置（token）：Authorization、Cookie
2.4、响应拦截设置（token）：数据回调、异常处理、loading、toast

【api/http.interceptor.js】文件，内容示例如下：

// 这里的vm，就是我们在vue文件里面的this，所以我们能在这里获取vuex的变量，比如存放在里面的token
// 同时，我们也可以在此使用getApp().gData，如果你把token放在getApp().gData的话，也是可以使用的

const install = (Vue, vm) => {
	Vue.prototype.$u.http.setConfig({
		baseUrl: process.uniEnv.baseUrl,
		dataType: 'json',
		header: {
			'content-type': 'application/json;charset=UTF-8'
		}
	});
	// 请求拦截，配置Token等参数
	Vue.prototype.$u.http.interceptor.request = (config) => {
		// 如果不带token，可以在头部传入时候写入token即可
		if (!config.header.token && vm.$store.state.vuex_token) {
			config.header.Authorization = 'Bearer ' + '注入token';
			config.header.Cookie = 'JSESSIONID=' + '注入sessionId' +
				";ClientVersion=6.50";
		}
		return config;
	}
	// 响应拦截，判断状态码是否通过
	Vue.prototype.$u.http.interceptor.response = (res, header) => {
		// 判断是否不需要提示
		let isShowToast = true
		if (header && header['zm-show-toast'] == 'false') {
			isShowToast = false
		}
		
		// #ifdef MP-WEIXIN
		// 兼容微信接口返回的状态使用flag
		if (res.flag === false || res.flag === true) {
			if (res.flag === true) {
				res.code = 10000
			} else {
				res.code = 0
			}
			res.message = res.msg
			res.body = res.data
		}
		// #endif

		if (res.returncode == '10000' || res.code == 10000) {
			return res.body
		}
		if (res.returncode == '403' || res.code == 403) {
			// 403 权限不足
			uni.showModal({
				title: '提示',
				content: res.message,
				showCancel: false,
				success: function(res) {
					if (res.confirm) {
						vm.$store.dispatch('logout', vm).then((res) => {
							uni.reLaunch({
								url: '/pages/auth'
							})
						})
					}
				}
			});
			return false
		}

		if (res.returncode == '104' || res.code == 104) {
			// access token过期
			uni.showModal({
				title: '提示',
				content: '登录失效, 请重新登录',
				showCancel: false,
				success: function(res) {
					if (res.confirm) {
						vm.$store.dispatch('logout', vm).then((res) => {
							uni.reLaunch({
								url: '/pages/auth'
							})
						})
					}
				}
			});
			return false
		}
		if (isShowToast) {
			vm.$u.toast(res.message || '请求失败!');
		}
		return false
	}
}

export default {
	install
}

文件在【main.js】引用：

const app = new Vue({
	...App
})

// http拦截器，将此部分放在new Vue()和app.$mount()之间，才能App.vue中正常使用
import httpInterceptor from '@/api/http.interceptor.js';
Vue.use(httpInterceptor, app);

app.$mount()

2.2、网络环境切换管理

1、由于本项目需要切换网络环境实现调试和应用、同时同一个网络环境也涉及到多个域名，因此需要对域名进行专项管理。
2、在管理类【env】实现，在【.env.js】中实现网络环境切换。

如【.env.js】文件，内容如下：

let env = 'test' // dev test rc prod 编译时候切换网络环境，需要修改该值

if (env === 'dev') {
	//开发环境
	var ENV_CONFIG = require('@/env/.env.dev.js');
} else if (env === 'test') {
	//测试环境
	var ENV_CONFIG = require('@/env/.env.test.js');
} else if (env === 'rc') {
	//rc环境
	var ENV_CONFIG = require('@/env/.env.rc.js');
} else if (env === 'prod') {
	//生产环境
	var ENV_CONFIG = require('@/env/.env.prod.js');
}

//给环境变量process.uniEnv赋值  使用 process.uniEnv.baseUrl
if (ENV_CONFIG) {
	process.uniEnv = {};
	for (let key in ENV_CONFIG) {
		process.uniEnv[key] = ENV_CONFIG[key];
	}
}

如【.env.test.js】文件，内容如下：

const config = {
    baseUrl: 'http://baidu.com',// 主域名
	// xmUrl: 'http://test1-baidu.com',// 私网 - 内部测试用
	xmUrl: 'https://test-baidu.cn',// 外网映射 - 审核使用
	bfUrl: 'http://alpha-baidu.cn',
	wxUrl: 'http://wx.baidu.com:8080',
	wxServer:'https://wxserver.baidu.cn/WeiXinServer',
	environment: 'test' // dev test rc prod
}

module.exports = config;

文件在【main.js】引用：

import '@/env/.env.js'

2.3、API集中管理

1、参照官方文档：API集中管理。
2、文档中：准备工作、说明、引入、使用，已经描述的很清楚，这里不再赘述。
如【http.mine.api.js】文件，内容如下：

// 创建 User 模块方法，方法内的方法共享 vm 对象
let Mine = (vm) => {
	return {
		// 获取xxx信息
		getAxxxRequest: (params) => {
			const header = {
				'content-type': 'application/x-www-form-urlencoded'
			}// 请求头content-type不设置，默认utf-8格式
			return vm.$u.post(process.uniEnv.xmUrl + '/xxx/xxx/v1.0', params, {})
		},
		
		// 设置xxx信息
		setBxxxRequest: (params) => {
			const header = {
				'content-type': 'application/x-www-form-urlencoded'
			}// 请求头content-type不设置，默认utf-8格式
			return vm.$u.post(process.uniEnv.xmUrl + '/xxx/xxx', params, header)
		},
	}
}

// 此处第二个参数vm，就是我们在页面使用的this，你可以通过vm获取vuex等操作，更多内容详见uView对拦截器的介绍部分：
// https://uviewui.com/js/http.html#%E4%BD%95%E8%B0%93%E8%AF%B7%E6%B1%82%E6%8B%A6%E6%88%AA%EF%BC%9F
const install = (Vue, vm) => {
	vm.$u.mineApi = Mine(vm)
}

// 抛出当前模块
export default {
	install
}

文件在【main.js】引用：

const app = new Vue({
	...App
})

import mineApi from '@/api/http.mine.api.js';
Vue.use(mineApi, app);

app.$mount()

注意引用的位置，需要在new Vue得到Vue实例之后。

总结：
1、API管理：【api/xxx】目录下。
2、环境配置：【env/xxx】目录下。

3、分包管理

1、在【pages.json】文件下添加分包，样式如下：

	"subPackages": [{
		// 分包1：我的模块
		"root": "pages/mine",
		"pages": [
			{
				// 我的 - 首页
				"path": "index",
				"style": {
					"navigationStyle": "custom"
				}
			}
		]
	},{
		// 分包2：游客模块
		"root": "pages/tourist",
		"pages": [{
				// 游客 - 首页
				"path": "index",
				"style": {
					"navigationStyle": "custom"
				}
			}
		]
	}],

2、在添加分包的时候，最好相对应的其他内容也一起做分类处理，方便管理。如：新增api协议文件、pages分包下新增static文件（公共的icon还是要放在公共区域）等。

4、【uni_modules】引入第三方组件

为提高开发效率，很多组件我们可以借用他人封装好的轮子。借助本项目引用的组件，进行说明：

4.1、uview-ui 框架

1、uview-ui的安装
2、功能：是一款全面兼容nvue的uni-app生态框架，全面的组件和便捷的工具。
3、注意：配置easycom组件不会实时生效，配置完后，您需要重启HX或者重新编译项目才能正常使用uView的功能。我验证了一下，重启HX好几次才有效，有强迫症的这点需要注意一下。
4、多种导入方式：

4.1、uView2.0下载插件ZIP，解压后直接导入项目目录中。或者去github上下载导入。
4.2、uView2.0右边栏点击【使用HBuilder导入插件】，将自动导入到【uni_modules】文件目录中。
4.3、uView-npm方式安装。注意直接在【HBuilder】左下角找到【终端】打开，再根据命令行安装，将自动安装到【node_modules】文件目录中。

• 注：推荐使用第二种方式。

5、拓展：什么是uni_modules？为什么有了node_modules，还需要再发明一个uni_modules的轮子？

4.2、qiun-data-charts

1、关键词检索：秋云 ucharts echarts 高性能跨全端图表组件
2、功能说明：高性能图表组件

4.3、z-paging

1、关键词检索：z-paging
2、功能说明：下拉刷新、上拉加载更多

5、图片资源管理

1、图片资源统一用【[email protected]】大小就可以。
2、图片压缩：每个图片资源添加都需要压缩一次图片资源，可以节省很大的空间，压缩地址：tinypng。

3、图片命名规则：

规则1（对应功能模块使用的）：
分包功能模块（主包：如签到，分包1：如设置，分包2：如游客模式）
_图片类型（图标：icon，背景|大图：view）
_应用页面
功能
状态（位置、点击、高亮等状态）
.png

示例：sign_icon_home_scan_click.png、sign_view_home_back_top.png

规则2（多包共用的）：
common
cn（common的简写）
_图片类型（图标：icon，背景|大图：view）
功能
状态（位置、点击、高亮等状态）
.png

示例：cn_icon_scan_click.png

4、图片资源是否上传服务器：如果图标资源太大，上传服务器，用链接显示。如果只是几k的小图标，直接放本地，便于开发维护。
5、添加分包的时候，最好在对应页面路径中新建一个的static文件，存放该分包特有的图片资源。

关于图片资源文件的存储：
由于小程序的资源大小限制，需要把大图放在cdn上，其具体的备份文件为static_backup 对应的是static的文件。
其访问路径为：https://static.ztjy.cn/prod/ztjy-qw/static指向的就是对应的备份文件夹static_backup。
比如：文件夹下：left_arrow.png 图片可用 https://static.ztjy.cn/prod/ztjy-qw/static/static/left_arrow.png 访问。
如：[email protected] 对应：https://static.ztjy.cn/prod/ztjy-qw/static/static/add%402x.png

• 注意：一定需要把对应的图片上传到cdn上后，再放入到static_backup文件夹做备份。

• 注意：图片资源上传管理，最好有专人负责、统一管理，不仅便于图片资源管理，还有利于区分图片资源在哪个小程序中应用（假如有多个小程序的话）。