请求 MNaas API 网关服务的 JS SDK。
当前版本: 1.0.0
快速入门
引入
目前仅支持源码引入的方式。请复制代码至您的工程目录下。
假设您已将名为 mtopee.js 的文件放入 src 文件中，以下方式均可使用 mtopee 的变量：
注：下列示例的路径目录可能与您工程的路径不同，请注意文件路径
通过 html 文件的 script 元素引入，同时 mtopee.js 会注册全局变量 mtopee。
假设您的工程基于 ES6 语法，也可通过 Module 引入。
importmtopee from'./src/mtopee'
假设您的工程基于 RequireJS 和 AMD 规范，可通过 require 方法引入。
require(["./src/mtopee.js"],function(mtopee){
...
});
请求
在您的页面中加入以下代码既可以发起 MNaas请求了。
mtopee.request({
api:'mopen.hotline.xspacehotlinemtopservicerservice.inithotlineconfig',// 请求 API 名称
v:'1.0',// 请求 API 版本
data:{},// API 服务接收的数据
appKey:'4272',// 标示来源通道
url:'api-xspace.daily.taobao.net'// 设置请求地址(可用作环境切换或指定请求域名)
}).then(function(ret){
// 成功回调
console.log(ret);
}).catch(function(ret){
// 失败回调
console.log(ret);
})
使用指南
一. 请求方式
MNaas 网关服务的 url 一般为专有域名。前端页面在请求 MNaas 服务时，会受到浏览器跨域策略的影响。mtopee.js 在处理跨域问题时，可使用 JSONP 或 CORS 的跨域方案，默认使用 CORS 方案。
可通过修改 mtopee request 方法中的 dataType 参数切换跨域方案，下文将详细介绍请求参数。本节主要讲述如何选择跨域方案。
跨域方案
优势
缺点
JSONP
浏览器兼容性良好，可处理 302 重定向请求
不支持POST请求、配置复杂
CORS
配置简单
受浏览器兼容影响，不可处理 302 重定向请求
使用 CORS 方案，配置请求域名后，允许其他页面域名跨域访问即可。
使用 JSONP 方案，由于 cookie 同源 策略(登录或其他信息 cookie)需要传入给服务端时，若页面域名较多则需要多次配置请求域名。
若您的业务有2个以上接入域名时，我们推荐您使用 CORS 方案，如需兼容更多的低版本浏览器我们建议您使用 JSONP 方案。
如果您的 MNaas 服务会下发 302 的重定向操作，例如登录302定向同步等，建议使用 jsonp 请求。
由于接入层 url 对长度有限制，较长数据情况建议使用 POST 请求。
假设您需要发起 MNaas请求的页面域名为h5.mnaastest.com
JSONP 接入联系 MNaas 服务端同学允许 mnaastest.com 访问 MNaas服务。
申请一个类似 api.m.mnaastest.com 用于转发 MNaas请求的域名。 (和页面主域名相同，可同步页面cookie)
联系 MNaas 同学将域名加入白名单
将 api.m.mnaastest.com cname 至 MNaas 服务的接入域名。
设置 lib-mtop.js
// 方式一：
mtopee.config.mtopDomain='api.m.mnaastest.com';
// 方式二：
mtopee.request({
...options,
dataType:'jsonp',// 必须，默认发起 CORS 请求
url:'api.m.mnaastest.com'
}).then().catch();
CORS 接入联系 MNaas 服务端同学允许 mnaastest.com 通过 CORS 请求访问 MNaas 服务。
// 方式一：
mtopee.config.mtopDomain='api.m.mnaastest.com';
// 方式二：
mtopee.request({
...options,
url:'api.m.mnaastest.com'
}).then().catch();
登录 cookie 信息处理
通用情况下，H5 的登录信息是储存在 cookie 中的。若需要 MNaas 服务验证用户登录信息，首先需要 MNaas 服务可获取到 cookie 信息。
JSONP 请求 url 和页面主域名一致时，可共享主域下的所有 cookie (例如 *.test.com)。
CORS 请求可取得请求 url 下所有的 cookie。
二. 请求参数
mtopee.js 通过 request 方法发起请求，并使用 Promise 操作
mtopee.request(options).then(function(ret){}).catch(function(ret){});
设置 options 说明如下：
参数
类型或选值
必须
说明
api
String
必须
请求 API
v
String
必须
请求 API 版本
data
JSON String / Object
必须
请求数据
appKey
String
必须
标示请求应用。
url
String
必须
MNaas 的服务地址。
type
String(GET / POST)
非必须
标示请求类型。默认值为’GET’。注：JSONP 方式只有 ‘GET’ 请求!
dataType
String(jsonp / json )
非必须
标示请求方式，默认值为’json’。’json’为 CORS 跨域请求。’jsonp’为 JSONP 跨域请求。
timeout
Number
非必须
标示超时时间(单位ms)。默认值为20000
headers
Object
非必须
可以为 dataType 为 ‘json’ 的请求设置请求头。例如：{‘Cache-Control’: ‘no-store’}。jsonp 请求无自定义 header
jsonpIncPrefix
String / Number
非必须
更改 jsonp callback 组合名称，用于区分业务或场景。例如：设置 ‘test’ 时，jsonp callback 名称将变成 ‘mtopeejsonptest1’ (后面数字位递增);
自定义参数传输
您传入的 options 在 H5 请求时都会通过 url 参数的形式传给服务端。例如，在 param 中加入了 ttid 时：
mtopee.request({ttid:'H5testId',...param});
可通过此方式和服务端传输更多自定义参数。
三. config 说明
可通过 mtopee.config 来修改 mtopee 配置
lib.mtop.config[KEY]=VALUE;
KEY 取值说明如下
配置
类型
说明
mtopDomain
String
等同于上表请求参数中的 url。可给未设置 url 的请求统一配置请求域名。注：优先级低于参数 url。
doLogin
Function
处理登录的钩子函数。下文会有详细说明。
四. 返回说明
返回数据为 Object 对象，包含：
键值
来源
说明
api
服务返回
请求 API
v
服务返回
请求 API 版本
ret
服务返回
请求结果。格式： code::message
data
服务返回
数据返回
retType
前端sdk自动附加参数
返回类型。-1：出错，0：成功，1：令牌过期，2：登录过期
失败返回示例如下：
{
"api":"mtop.user.getUserSimple",
"v":"1.0",
"ret":"FAIL_SYS_SESSION_EXPIRED::SESSION失效",
"data":{},
"retType":2
}
成功返回示例如下：
{
"api":"mtop.user.getUserSimple",
"v":"1.0",
"ret":"SUCCESS::调用成功",
"data":{
"userNumId":"xxxx",
"nick":"xxx"
},
"retType":0
}
请求结果判断
1. 根据 ret 字段判断。建议使用此方式，可读取 服务端返回错误。functionhandler(retJson){
varret=retJson.ret;
if(ret.indexOf('SUCCESS')>-1){
// 请求成功
}else{
// 请求失败
}
}
2. retType 判断functionhandler(retJson){
if(retJson.retType===0){
// 请求成功
}else{
// 请求失败
}
}
五. 重试逻辑
mtopee.js 遇到下列情况时，会发起重试请求，即 Network 中会看到多次 MNaas请求
情况
说明
失败返回，并包含”TOKEN_EMPTY”
请求缺少 COOKIE TOKEN 信息时，服务端会写新的 COOKIE ，重发请求即可
失败返回，并包含”TOKEN_EXOIRED”
请求 COOKIE TOKEN 信息过期时，服务端会写新的 COOKIE ，重发请求即可
六. 登录验证请求
由于对接的登录服务不同，当 MNaas请求返回需要登录的错误时，sdk 会调用配置的登录 hook 。
未配置时回调函数会得到对应的错误。可根据登录业务的实现执行不同的操作。
mtop.config.doLogin=function(retry){
// this 为发起请求的 MTOP 对象
location.href="//login.xxx";// 方式一：跳转登录页，再 redirect 到当前页面刷新。
retry.call(this);// 方式二：完成登录后但无刷新页面时，可使用 retry 的方法重新发起请求。
};
同时也支持为单次请求配置登录方法：
mtop.request({
...params,
doLogin:function(retry){
// todo
}
}).then(function(resJson){
// 成功回调
},function(resJson){
// 失败回调
});
开发指南
一. 本地调试须知
由于 MNaas 有较高的安全校验，本地调试测试时，需要修改您本地 host 配置。
假设您已完成 MNaas 接入，并且您的页面域名为 test.mnaastest.com 通过 acs.m.mnaastest.com 发起 MNaas请求。开始本地调试前，您需要
注：文中出现的mnaastest.com是伪域名，请替换成您的业务域名
修改config 配置，也可用于切换环境：
// 方式一：使用 config 配置
mtopee.config.mtopDomain='acs.m.mnaastest.com';
// 方式二：设置 url 参数
mtopee.request({
...options,url:'acs.m.mnaastest.com'
}).then(function(ret){
}).catch(function(ret){
})
1.调试 JSONP 请求" class="reference-link">1.调试 JSONP 请求
默认为 JSONP 跨域请求，通过访问 local.mnaastest.com 至您的页面便可以进行调试
2.调试 CORS(XHR) 请求该域名在 MNaas 服务端信任白名单内
端口必须为 80，否则跨域
由于未配置端口，本地测试也需要使用80端口。
二. 常见错误码说明
1. FAIL_SYS_ILLEGAL_ACCESS::非法请求
h5客户端生成的签名与服务器生成的签名不匹配时，会出现此错误。
常见原因本地调试使用 IP 请求。方案请见 文档本地调试 部分。
页面域名未配置 MNaas 访问权限，问题域名需接入 MNaas 服务。
2. FAIL_SYS_DOMAIN_NOT_ALLOWED::该域名不允许访问
页面域名未配置 MNaas 服务白名单时，通过 CORS 跨域请求会出现此错误。联系服务端同学配置白名单。
3. FAIL_SYS_SESSION_EXPIRED::SESSION失效
用户会话失效时，会出现此错误。
常见原因用户未登录：页面请求需要登录的 API 但访问页面的用户并未登录。方案请见 文档登录验证请求 部分。
MNaas 服务未获取到登录 cookie 信息：请保证 MNaas 请求的域名有登录的 cookie 信息，可通过 Request header 中的 cookie 字段排查。
登录状态过期。方案请见 文档登录验证请求 部分。
4. FAIL_SYS_API_NOT_FOUNDED::请求API不存在
调用的 MNaasAPI 不存在，会出现此错误。
常见原因API 不存在，请在 MNaas管理平台中搜索问题 API 是否存在。
API 未设置 h5 访问，请在API详情中，通过允许访问入口项查看是否有 h5。
环境请求错误，未上线的 API 是不能直接请求线上 MNaas 服务的。
5. FAIL::缺少必填的参数
请求中业务必传参数字段缺失
6. ABORT::接口异常退出
MNaas 请求 http-code 非 200 到 300 及 304 时会返回此错误。一般为服务端请求出现故障，可见浏览器中的请求错误信息
三. 中间件开发指南
mtopee.js + middlewares(目前 mtopee.js 自带 emoji 字符过滤中间件。由于emoji字符仍在扩展，服务端和前度的字符集可能不同导致验签失败) 的开发模式基本可以覆盖大部分对于 MNaas定制的需求。
mtopee.js 在执行期间分为2个生命周期，一个是发送请求前的”构造请求阶段“，另一个是请求回来后的”处理返回阶段“。
1. 开发模板
一般有以下2种模板：
// 模板一：只处理 "构造请求阶段" 逻辑。
;(function(){
if(!mtopee){
return;
}
functionmiddleware1(next){
varthat=this;// 当前 Mtop 对象
varparams=this.params;// 用户输入的参数
varoptions=this.options;// 请求的相关配置
// todo "构造请求阶段" 逻辑
next();
}
mtopee.middlewares.push(middleware1);
})();
// 模板二：处理 "构造请求阶段" 和 "处理返回阶段" 逻辑。
;(function(){
if(!mtopee){
return;
}
functionmiddleware2(next){
varthat=this;// 当前 Mtop 对象
varparams=this.params;// 用户输入的参数
varoptions=this.options;// 请求的相关配置
// todo "构造请求阶段" 逻辑
returnnext().then(function(){
// todo "处理返回阶段" 逻辑
});
};
mtopee.middlewares.push(middleware2);
})();
params 和 options 是 mtopee.js 中2个非常重要的对象变量。params 中储存了用户调用时的入参，对应生成的 MNaas对象所有的标记配置则存于 options 中。运行入参 next 方法可进入下一步处理，如需在”处理返回阶段”增加处理逻辑，则需返回新的 Promise 插入至返回处理流中。最后执行 mtopee.middlewares.push(xxx) 将写好的 middleware 推入中间件状态的运行时中(执行顺序同样为“构造请求阶段”先进先执行，”处理返回阶段“先进后执行)。
注：未运行入参 next 时，则相当于中断了 mtopee.js 的处理流。
2. 引入方式
中间件代码放在 mtopee.js 之后，mtopee.request(param) 调用之前即可。
3. “构造请求阶段”说明
middlewares 在“构造请求阶段”运行时，mtopee.js 已经完成了所有构造 MNaas请求的相关逻辑。在此阶段，主要通过修改 options 中的配置来实现一些特殊逻辑。
常用 options 的配置如下：
配置
类型
说明
使用场景
path
String
H5 的请求地址
修改请求地址
querystring
Object
会从 Object 转换成 Query String 拼接至 H5 的请求地址之后。
新增、删除或修改请求参数。
postdata
Object
传输的 data
新增、删除或修改请求 data。
注：可以在 options 上新增独有的标记配置。如果需要对当前请求修改，请直接修改 path 内容。
4. “处理返回阶段”说明
middlewares 在“处理返回阶段”运行时，mtopee.js 已经完成对返回结果的校验。在此阶段，主要通过校验或修改 options 中的 retJson 来实现一些特殊逻辑。
functionmiddleware(next){
varthat=this;// 当前 Mtop 对象
varparams=this.params;// 用户输入的参数
varoptions=this.options;// 请求的相关配置
// "构造请求阶段" 逻辑 ...
returnnext().then(function(){
varretJson=options.retJson;
varret=retJson.ret;
if(ret.indexOf('xxxxx')>-1){
// todo 特殊逻辑处理
}
});
};
一般主要对 ret 进行分析或加工，常见 ret 有 “SUCCESS::调用成功”、”FAIL_SYS_TOKEN_EMPTY::令牌为空”、”FAIL_SYS_SESSION_EXPIRED::SESSION失效”等。以 LoginRequest 的中间件为例，当检测到 SESSION 相关错误时，就需要拉起登录框并等待用户完成登录操作，再重试发起新的 MNaas请求。
returnnext().then(function(){
varretJson=options.retJson;
varret=retJson.ret;
if(retinstanceofArray){
ret=ret.join(',');
}
if(ret.indexOf('SESSION_EXPIRED')>-1){
returngoLoginAsync().then(function(){
// 执行 retry 逻辑
returnthat.__sequence([
that.__processToken,
that.__processRequestUrl,
that.__loginHook,
that.middlewares,
that.__processRequest
]);
});
}
});
触发重试逻辑，只需返回新的 __sequence 执行队列即可。
changelog
1.0.0获取MTOP请求信息
3102
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
