接口文档说明（小程序）
## 说明
在456微营销系统中，为方便接口测试、修改、调用以及复用性，所以把接口分为五个部分，分别为 域名、终端、模块、接口名、传参
#### 域名：
为方便开发测试以及不影响线上项目的运营，搭建了一个同线上环境相同的测试服务器，一般都是要求在测试服务器上开发通过再上传到正式服务器运营。而且小程序正式环境是要做域名校验的，所以要注意两个域名之间的切换，以避免因微信审核耽误上线时间。
测试域名： `http://105.trtr.cn`
正式域名： `https：//xcx.trtr.cn`
***
#### 终端：
根据不同的用户群体以及设备类型分为三种类型，分别是 移动端`Wap`、小程序端`Wxapp`以及管理后台`User`。
***
#### 模块：
为便于管理以及开发效率，根据功能类型划分各个模块，如 投票模块`Voteimg`、砍价模块`Bargain`、拼团模块`Tuan`、电商模块`Ceshop`等。
***
#### 接口名：
后端语言中"类"的名称，一般与 域名、终端、模块、接口名以及传参 组成一个完整的 请求地址，用于前后端交互，发起（接收）数据的作用。
***
#### 传参：
与服务器交互中所需参数，用于明确具体需求，为简化开发，将参数分为两种：
一种为固定参数，即在当前模块中所有请求接口都需要的参数，具有普遍性
另一种是普通参数，在各个接口都不相同，是唯一的，不具有普遍性
## 举例：
假设有这么一个接口：`https://xcx.trtr.cn/index.php?g=Wxapp&m=Ceshop&a=login`
#### 请求参数
| 参数名 | 数据类型 | 说明 |
| :-- | :--: | - |
| token | String | 公众号在微信平台的唯一公钥ID，也是区分不同用户（小程序）的唯一标识 |
| code | String | 小程序登录的code值，通过 wx.login 方法获取 |
根据以上规则可以把此接口拆分为五个部分即：
| 名称 | 值 | 说明 |
| - | :--: | - |
| 域名 | https://xcx.trtr.cn | 服务器访问地址 |
| 终端 | g=Wxapp | g 是 group 的缩写，用于代表终端类型 |
| 模块 | m=Ceshop | m 是 module 的缩写，用于代表模块名 |
| 接口名 | a=login | a 是 ajax 的缩写，用于代表接口名 |
| 传参 | token、code | 又可以根据token的特性，将其划分为固定参数 |
>i index.php 是一个入口文件名称（路由），可以理解成大门，我们往服务器中拿数据或是推送数据，都需要经过这里，可以固定下来，轻易不会变动。
#### 初衷
好了，说了这么说，其实就是为了方便开发封装一个接口地址的函数，以下仅是一个示例，并非固定格式，各位有兴趣的可以按照自己的习惯封装自己的方法。
## 代码示例
```Javascript
/**
* 建议把url函数封装在 app.js 主体中，便于其通过 getApp() 调用
* @param str {String} 接口名称
* @param obj {Object} 参数
* @variable token/sid {String} 因token和sid参数的通用性，故封装在接口中以get形式传参
**/
function url(str, obj){
var url = 'https://xcx.trtr.cn',
//为了方便在测试与正式环境之间切换
//url = 'http://105.trtr.cn',
sid = this.globalData.sid,
token = this.globalData.token,
uri = str.split('/');
url += '/index.php?';
if (uri.length == 1) {
url = url + 'g=Wxapp&m=Ceshop&a=' + str;
} else if (length == 2) {
url += 'g=Wxapp&m=' + uri[0] + '&a=' + uri[1];
} else {
url += 'g=' + uri[0] + '&m=' + uri[1] + '&a=' + uri[2];
}
for (var i in obj) {
url += '&' + i + '=' + obj[i];
}
if (sid) url += "&sid=" + sid;
url += '&token=' + token;
return url;
}
```
#### 为避免做多余的错误处理，经统一返回格式，作出以下请求封装
```Javascript
/**
* @param url {String/Array} 接口名
* @param param {Object} 传参
* @param fn {Function} 请求成功的回调
* @param method {String} 请求方式，目前仅支持get和post请求
* @param failFn {Function} 请求失败的回调
* @return res {Object} 请求返回对象
* @return res.data.status {Number} 状态码（0：成功，1：失败）
* @return res.data.msg {String/Object} 返回值
**/
function request(url, param, fn, method, failFn){
let urls;
if (typeof arguments[1] == 'function') {
param = {};
fn = arguments[1];
if (typeof arguments[2] == 'function') {
method = 'GET';
failFn = arguments[2];
}
}
if (typeof arguments[3] == 'function') {
method = 'GET';
failFn = arguments[2];
}
if (typeof url == 'string'){
urls = this.url(url, method == 'post' ? '' : param);
}else{
urls = this.url(url[0], url[1]);
}
wx.request({
method: method || 'get',
url: urls,
data: method == 'post' ? param : '',
success: function(res) {
wx.hideLoading();
if (res.data.status != 0) {
//这个乱入的errcode是请求官方接口返回的错误码，这就没办法，只能做个兼容处理
wx.showModal({
title: res.data.errcode ? '错误码：' + res.data.errcode : '温馨提示',
content: res.data.errmsg || res.data.msg,
showCancel: false
})
return false;
}
fn && fn(res);
},
fail: function(res) {
wx.hideLoading();
if (failFn){
failFn(res);
}else{
wx.showModal({
title: '温馨提示',
content: '哎呀，网络开小差了！',
showCancel: false
})
}
}
})
}
```
#### 调用示例
看完上面封装的 `request` 函数，可能有些细心的爱思考的小伙伴会纠结一个问题，那就是 为什么参数`url`会有两种数据类型，不明明就是一个接口名吗？String类型好理解，Array类型是个什么鬼？
好的，其实这个只是为了针对某个特殊情况作出的一个处理，就是 当接口请求方式是post时，却要传一个get形式的参数，emmmm ... 有点诡异吧，话不多说，请看示例
```Javascript
//以下是在 app.js 中的某个函数里，_this 代表的是 app
/**
* @param code {String} 用户在当前小程序中的身份识别
* @param user {Object} 用户公开信息（头像、名称、地址等）
* 由于一系列的历史原因，导致后台不好更改传参的获取方式，才导致的这种很**的情况，便针对于此情形作出以下兼容处理
**/
_this.request(['login', { code: res.code }], user, function (res) {
_this.globalData.sid = res.data.sid;
fn && fn(res);
}, 'POST');
```
以下是借用 [获取门店列表](https://easydoc.top/doc/39935978/k5QepJMO/aCmEQUd7) 接口作的示例：
```Javascript
//以下对象就当做是在某个页面的 page 中吧
let app = getApp();
{
getAgentList: function(){
var _this = this,
param = {
page: 1,
lat: 28.23529,
lng: 112.93134,
token: 'hghbsm1406013577',
agent_id: 0
};
/** Start
你需要的代码块 ......
End **/
wx.loading('正在加载...');
app.request('agent_list', param, function(res){
var list = res.data.msg.list;
//门店列表获取到了，就这样吧，接下来你爱干嘛干嘛
});
}
}
```