网络组件库

@mg-ott/base-network 是大屏前端统一的网络组件库，支持网络请求重试、异常上报等能力。

按使用场景可分为以下 4 种：

• Vue、React、原生 js 框架
• uniapp 框架
• W2A 框架
• 微信小程序 框架

安装

使用 npm：

mgtv install @mg-ott/base-network

使用 script（全局创建了 createBaseNetwork 方法）：

<script src="//lib/base-network.js"></script>

使用

创建实例：

import createBaseNetwork from '@mg-ott/base-network';

const baseNetwork = createBaseNetwork({
  baseURL: 'https://nuc2.api.mgtv.com',
  timeout: 10000,
});

发起 GET 请求：

// get请求，第2个参数作为url参数
baseNetwork
  .get('/GetUserInfo', {
    ticket: '692C5567939832F7ABCF08DA768DC27A',
    invoker: 'jmcp',
  })
  .then((res) => {
    console.log('请求成功：', res);
  })
  .catch((err) => {
    console.log('请求失败：', err);
  });

发起 POST 请求：

// post请求，第2个参数作为body参数
baseNetwork
  .post('/GetUserInfo', {
    ticket: '692C5567939832F7ABCF08DA768DC27A',
    invoker: 'jmcp',
  })
  .then((res) => {
    console.log('请求成功：', res);
  })
  .catch((err) => {
    console.log('请求失败：', err);
  });

API

创建请求实例

createBaseNetwork(createBaseNetworkConfig): BaseNetwork

const baseNetwork = createBaseNetwork({
  /** 平台类型: web, wx, weex, uni, mgtv */
  platform: 'web'

  /** 自动加在 `url` 前面，除非 `url` 是一个绝对 URL。 */
  baseURL: "https://nuc2.api.mgtv.com",

  /** 即将被发送的自定义请求头 */
  headers: {'X-Requested-With': 'XMLHttpRequest'},

  /** 超时时间 */
  timeout: 10000,

  /** 返回的数据格式，默认json（wx、uni、mgtv支持） */
  dataType: 'json'

  /** 服务器响应的数据类型（web、wx、uni支持，web默认json，wx、uni默认text） */
  responseType: 'text',

  /** 域名重试配置，根据域名指定，指定参数可以为数组，可以为数字 */
  retryConfig: {
    "nuc.api.mgtv.com": [
      "https://nuc2.api.mgtv.com",
      "https://nuc3.api.mgtv.com",
    ],
    // "nuc.api.mgtv.com": 2,
  },

  // 业务错误码配置
  bizConfig: {
    /** 错误码key */
    codeKey: "code",
    /** 错误码正常值，支持用数组配置多个 */
    codeNormal: 0,
    // codeNormal: [0, 1],
    /** 业务异常原因key */
    msgKey: "msg",
    /** 业务异常追踪号key */
    traceKey: "seqid",
    /** 根据域名指定错误码配置 */
    byDomain: {
      "nuc.api.mgtv.com": {
        codeKey: "code",
        codeNormal: 0,
      },
    },
  },

  // 错误上报配置
  errorReportConfig: {
    /** 错误上报地址 */
    url: "https://crash.data.v2.mgtv.com/dispatcher.do",
    /** 错误上报参数，需要返回对象 */
    params: function () {
      return {
        ptype: 3,
        did: "123",
        mac: "6488FF19668B",
        uuid: "",
        isdebug: 0,
        mf: "",
        mod: "",
        sver: "",
        aver: "",
        pver: "",
        wver: "zt-test-h5/1.0",
        operator: "",
        pagename: "",
        act: "error",
        logtype: "error",
        bid: "21.13.20",
      };
    },
  },
});

实例方法

以下是BaseNetwork实例的方法，指定的配置 config 将与创建实例的配置合并且覆盖。

baseNetwork.get(url, params, config);

baseNetwork.post(url, data, config);

baseNetwork.put(url, data, config);

baseNetwork.delete(url, params, config);

baseNetwork.patch(url, data, config);

baseNetwork.head(url, params, config);

baseNetwork.options(url, params, config);

baseNetwork.jsonp(url, params);

请求配置

实例方法只有 url 是必需的，params 为 URL 参数，data 是作为请求主体被发送的数据。

实例方法的 config 支持的属性如下：

• baseURL
• headers
• timeout
• dataType
• responseType
• retryConfig
• bizConfig
• errorReportConfig

响应结构

单个请求的响应包含以下信息:

{
  /** 服务器响应内容 */
  data: {},

  /** 服务器响应内容文本格式 */
  responseText: '',

  /** 服务器响应的 HTTP 状态码 */
  status: 200,

  /** 服务器响应的头 */
  headers: {},

  /** 当次请求的配置信息 */
  config: {},

  /** 网络请求实例（区分平台） */
  request: {},

  /** 开发者服务器返回的 cookies，格式为字符串数组 */
  cookies: [],

  /** 服务器返回的http状态码，异常时才有 */
  responseStatus: '',

  /** 是否错误，0:成功，1:业务异常，-1:网络异常 */
  hasError: 0,
}

网络请求重试

当且仅当网络异常时触发，默认关闭，需要根据域名指定是否重试，支持数字和数组（数组项为重试域名）。

网络请求重试打开方式

创建实例时：

const baseNetwork = createBaseNetwork({
  retryConfig: {
    'nuc.api.mgtv.com': ['https://nuc2.api.mgtv.com', 'https://nuc3.api.mgtv.com'],
    // "nuc.api.mgtv.com": 2,
  },
});

单词请求时：

baseNetwork.get(
  '/GetUserInfo',
  {
    ticket: '692C5567939832F7ABCF08DA768DC27A',
    invoker: 'jmcp',
  },
  {
    retryConfig: {
      'nuc.api.mgtv.com': ['https://nuc2.api.mgtv.com', 'https://nuc3.api.mgtv.com'],
      // "nuc.api.mgtv.com": 2,
    },
  },
);

错误上报

单次请求发生网络异常或业务异常时触发上报，默认关闭，配置errorReportConfig即可打开上报。

网络异常（2050203）

当接口请求出现的网络异常时，且配置了errorReportConfig时，则自动触发网络异常上报。

可能出现网络异常的场景如下：

• 无法拿到 HTTP 状态码（比如跨域、超时、中止等原因）
• 拿到 HTTP 状态码不为 200

业务异常（2050204）

请求后端接口时，服务端报的各类业务异常（不包括用户网络异常情况），需要同时配置 errorReportConfig 和 bizConfig打开上报。

业务异常上报时机：

需要前端开发根据当前业务场景判别上报。

不需要上报：

• 该异常需要代码逻辑处理
• 该异常为不需要前端处理的非正常业务场景（比如验证码过期等）

需要上报：

• 若该异常前端无法处理（比如二维码参数失效，前端无法拿到完整的二维码参数，导致后续流程无法继续）
• 前后端解耦异常