全部产品
云市场

JS接入

更新时间:2018-09-13 10:33:20

请求 MNaas API 网关服务的 JS SDK。

当前版本: 1.0.0

快速入门

引入

目前仅支持源码引入的方式。请复制代码至您的工程目录下。

假设您已将名为 mtopee.js 的文件放入 src 文件中,以下方式均可使用 mtopee 的变量:

注:下列示例的路径目录可能与您工程的路径不同,请注意文件路径

  1. 通过 html 文件的 script 元素引入,同时 mtopee.js 会注册全局变量 mtopee。

    1. <script src="./src/mtopee.js"></script>
  2. 假设您的工程基于 ES6 语法,也可通过 Module 引入。

    1. import mtopee from './src/mtopee'
  3. 假设您的工程基于 RequireJS 和 AMD 规范,可通过 require 方法引入。

    1. require(["./src/mtopee.js"], function (mtopee) {
    2. ...
    3. });

请求

在您的页面中加入以下代码既可以发起 MNaas请求了。

  1. mtopee.request({
  2. api: 'mopen.hotline.xspacehotlinemtopservicerservice.inithotlineconfig', // 请求 API 名称
  3. v: '1.0', // 请求 API 版本
  4. data: {}, // API 服务接收的数据
  5. appKey: '4272', // 标示来源通道
  6. url: 'api-xspace.daily.taobao.net' // 设置请求地址(可用作环境切换或指定请求域名)
  7. }).then(function(ret){
  8. // 成功回调
  9. console.log(ret);
  10. }).catch(function(ret){
  11. // 失败回调
  12. console.log(ret);
  13. })

使用指南

一. 请求方式

MNaas 网关服务的 url 一般为专有域名。前端页面在请求 MNaas 服务时,会受到浏览器跨域策略的影响。mtopee.js 在处理跨域问题时,可使用 JSONPCORS 的跨域方案,默认使用 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 接入

  1. 联系 MNaas 服务端同学允许 mnaastest.com 访问 MNaas服务。
  2. 申请一个类似 api.m.mnaastest.com 用于转发 MNaas请求的域名。 (和页面主域名相同,可同步页面cookie)
  3. 联系 MNaas 同学将域名加入白名单
  4. api.m.mnaastest.com cname 至 MNaas 服务的接入域名。
  5. 设置 lib-mtop.js
  1. // 方式一:
  2. mtopee.config.mtopDomain = 'api.m.mnaastest.com';
  3. // 方式二:
  4. mtopee.request({
  5. ...options,
  6. dataType: 'jsonp', // 必须,默认发起 CORS 请求
  7. url: 'api.m.mnaastest.com'
  8. }).then().catch();

CORS 接入

  1. 联系 MNaas 服务端同学允许 mnaastest.com 通过 CORS 请求访问 MNaas 服务。
  1. // 方式一:
  2. mtopee.config.mtopDomain = 'api.m.mnaastest.com';
  3. // 方式二:
  4. mtopee.request({
  5. ...options,
  6. url: 'api.m.mnaastest.com'
  7. }).then().catch();

通用情况下,H5 的登录信息是储存在 cookie 中的。若需要 MNaas 服务验证用户登录信息,首先需要 MNaas 服务可获取到 cookie 信息。

JSONP 请求 url 和页面主域名一致时,可共享主域下的所有 cookie (例如 *.test.com)。

CORS 请求可取得请求 url 下所有的 cookie。

二. 请求参数

mtopee.js 通过 request 方法发起请求,并使用 Promise 操作

  1. 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 时:

  1. mtopee.request({ttid: 'H5testId', ...param});

您将会看到类似如下 MNaas 请求:https://h5api.m.taobao.com/h5/xxx/1.0/?dataType=jsonp&ttid=H5testId&…

可通过此方式和服务端传输更多自定义参数。

三. config 说明

可通过 mtopee.config 来修改 mtopee 配置

  1. 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:登录过期

失败返回示例如下:

  1. {
  2. "api": "mtop.user.getUserSimple",
  3. "v": "1.0",
  4. "ret": "FAIL_SYS_SESSION_EXPIRED::SESSION失效",
  5. "data": {},
  6. "retType": 2
  7. }

成功返回示例如下:

  1. {
  2. "api": "mtop.user.getUserSimple",
  3. "v": "1.0",
  4. "ret": "SUCCESS::调用成功",
  5. "data": {
  6. "userNumId": "xxxx",
  7. "nick": "xxx"
  8. },
  9. "retType": 0
  10. }

请求结果判断

1. 根据 ret 字段判断。建议使用此方式,可读取 服务端返回错误。
  1. function handler(retJson) {
  2. var ret = retJson.ret;
  3. if(ret.indexOf('SUCCESS') > -1){
  4. // 请求成功
  5. }else{
  6. // 请求失败
  7. }
  8. }
2. retType 判断
  1. function handler(retJson) {
  2. if(retJson.retType === 0){
  3. // 请求成功
  4. }else{
  5. // 请求失败
  6. }
  7. }

五. 重试逻辑

mtopee.js 遇到下列情况时,会发起重试请求,即 Network 中会看到多次 MNaas请求

情况 说明
失败返回,并包含”TOKEN_EMPTY” 请求缺少 COOKIE TOKEN 信息时,服务端会写新的 COOKIE ,重发请求即可
失败返回,并包含”TOKEN_EXOIRED” 请求 COOKIE TOKEN 信息过期时,服务端会写新的 COOKIE ,重发请求即可

六. 登录验证请求

由于对接的登录服务不同,当 MNaas请求返回需要登录的错误时,sdk 会调用配置的登录 hook 。

未配置时回调函数会得到对应的错误。可根据登录业务的实现执行不同的操作。

  1. mtop.config.doLogin = function (retry) {
  2. // this 为发起请求的 MTOP 对象
  3. location.href = "//login.xxx"; // 方式一:跳转登录页,再 redirect 到当前页面刷新。
  4. retry.call(this); // 方式二:完成登录后但无刷新页面时,可使用 retry 的方法重新发起请求。
  5. };

同时也支持为单次请求配置登录方法:

  1. mtop.request({
  2. ...params,
  3. doLogin: function(retry){
  4. // todo
  5. }
  6. }).then(function(resJson) {
  7. // 成功回调
  8. }, function (resJson) {
  9. // 失败回调
  10. });

开发指南

一. 本地调试须知

由于 MNaas 有较高的安全校验,本地调试测试时,需要修改您本地 host 配置。

假设您已完成 MNaas 接入,并且您的页面域名为 test.mnaastest.com 通过 acs.m.mnaastest.com 发起 MNaas请求。开始本地调试前,您需要

注:文中出现的 mnaastest.com 是伪域名,请替换成您的业务域名

  1. // 方式一:使用 config 配置
  2. mtopee.config.mtopDomain = 'acs.m.mnaastest.com';
  3. // 方式二:设置 url 参数
  4. mtopee.request({
  5. ...options, url: 'acs.m.mnaastest.com'
  6. }).then(function(ret){
  7. }).catch(function(ret){
  8. })

1.调试 JSONP 请求" class="reference-link">1.调试 JSONP 请求

默认为 JSONP 跨域请求,通过访问 local.mnaastest.com 至您的页面便可以进行调试

2.调试 CORS(XHR) 请求

访问 local.mnaastest.com 同时您需要注意:

  • 该域名在 MNaas 服务端信任白名单内
  • 端口必须为 80,否则跨域

由于未配置端口,本地测试也需要使用80端口。

二. 常见错误码说明

1. FAIL_SYS_ILLEGAL_ACCESS::非法请求

h5客户端生成的签名与服务器生成的签名不匹配时,会出现此错误。

常见原因
  1. 本地调试使用 IP 请求。方案请见 文档本地调试 部分。
  2. 页面域名未配置 MNaas 访问权限,问题域名需接入 MNaas 服务。

2. FAIL_SYS_DOMAIN_NOT_ALLOWED::该域名不允许访问

页面域名未配置 MNaas 服务白名单时,通过 CORS 跨域请求会出现此错误。联系服务端同学配置白名单。

3. FAIL_SYS_SESSION_EXPIRED::SESSION失效

用户会话失效时,会出现此错误。

常见原因
  1. 用户未登录:页面请求需要登录的 API 但访问页面的用户并未登录。方案请见 文档登录验证请求 部分。
  2. MNaas 服务未获取到登录 cookie 信息:请保证 MNaas 请求的域名有登录的 cookie 信息,可通过 Request header 中的 cookie 字段排查。
  3. 登录状态过期。方案请见 文档登录验证请求 部分。

4. FAIL_SYS_API_NOT_FOUNDED::请求API不存在

调用的 MNaasAPI 不存在,会出现此错误。

常见原因
  1. API 不存在,请在 MNaas管理平台中搜索问题 API 是否存在。
  2. API 未设置 h5 访问,请在API详情中,通过允许访问入口项查看是否有 h5。
  3. 环境请求错误,未上线的 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种模板:

  1. // 模板一:只处理 "构造请求阶段" 逻辑。
  2. ;(function () {
  3. if (!mtopee) {
  4. return;
  5. }
  6. function middleware1(next) {
  7. var that = this; // 当前 Mtop 对象
  8. var params = this.params; // 用户输入的参数
  9. var options = this.options; // 请求的相关配置
  10. // todo "构造请求阶段" 逻辑
  11. next();
  12. }
  13. mtopee.middlewares.push(middleware1);
  14. })();
  15. // 模板二:处理 "构造请求阶段" 和 "处理返回阶段" 逻辑。
  16. ;(function () {
  17. if (!mtopee) {
  18. return;
  19. }
  20. function middleware2(next) {
  21. var that = this; // 当前 Mtop 对象
  22. var params = this.params; // 用户输入的参数
  23. var options = this.options; // 请求的相关配置
  24. // todo "构造请求阶段" 逻辑
  25. return next().then(function () {
  26. // todo "处理返回阶段" 逻辑
  27. });
  28. };
  29. mtopee.middlewares.push(middleware2);
  30. })();

paramsoptions 是 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 来实现一些特殊逻辑。

  1. function middleware(next) {
  2. var that = this; // 当前 Mtop 对象
  3. var params = this.params; // 用户输入的参数
  4. var options = this.options; // 请求的相关配置
  5. // "构造请求阶段" 逻辑 ...
  6. return next().then(function () {
  7. var retJson = options.retJson;
  8. var ret = retJson.ret;
  9. if (ret.indexOf('xxxxx') > -1) {
  10. // todo 特殊逻辑处理
  11. }
  12. });
  13. };

一般主要对 ret 进行分析或加工,常见 ret 有 “SUCCESS::调用成功”、”FAIL_SYS_TOKEN_EMPTY::令牌为空”、”FAIL_SYS_SESSION_EXPIRED::SESSION失效”等。以 LoginRequest 的中间件为例,当检测到 SESSION 相关错误时,就需要拉起登录框并等待用户完成登录操作,再重试发起新的 MNaas请求。

  1. return next().then(function () {
  2. var retJson = options.retJson;
  3. var ret = retJson.ret;
  4. if (ret instanceof Array) {
  5. ret = ret.join(',');
  6. }
  7. if (ret.indexOf('SESSION_EXPIRED') > -1) {
  8. return goLoginAsync().then(function () {
  9. // 执行 retry 逻辑
  10. return that.__sequence([
  11. that.__processToken,
  12. that.__processRequestUrl,
  13. that.__loginHook,
  14. that.middlewares,
  15. that.__processRequest
  16. ]);
  17. });
  18. }
  19. });

触发重试逻辑,只需返回新的 __sequence 执行队列即可。

changelog

1.0.0

  • 获取MTOP请求信息