exceed v1.7.8

Exceed

最简的完成GET / POST / FILE 动作的API管理工具

特点

• 环境切换，可自定义环境（一般使用local/dev/pre/prod）
• 字符串模板与传参同时存在，允许使用 /a/b/1 类型的路由进行API调用

API

初始化

const exceed = new Exceed({
  csrf: false, // 用于表明是否使用csrf
  ENV: 'local' // 用于设置初始环境, 默认为production,
  urlencode: false // 用于对所有请求的url路径做urlencode，默认为false
});

const exceed = new Exceed({
  csrf: {
    token: '_ctoken_'
  }, // 如启用则会从cookie中读取相应值作为csrf token 使用
  ENV: 'local' // 用于设置初始环境
});

API管理

const INTERFACE = [
  {
    "name": "test", // 无特殊含义的name，作为约定写上用于分辨API
    "id": "test1", // 唯一id，不可重复，作为调用依据
    "method": "GET", // 调用方法，可以是 GET / POST / FILE
    "urls": {
      "production": "http://127.0.0.1:3000/getWithoutParam" // 调用的URL 
    }
  }, {
    id: 'test2',
    method: 'get',
    urls: {
      production: 'http://127.0.0.1:3000/{{action}}' // 使用模板的URL，可使用params传参来替换模板中的值
    }
  }, {
    id: 'test3',
    method: 'file',
    urls: {
      production: 'http://127.0.0.1:3000/postWithFile'
    }
  }, {
    id: 'test5',
    type: 'jsonp',
    crossOrigin: true,
    jsonpCallback: 'foo',
    urls: {
      production: 'http://127.0.0.1:3000/jsonpTest' 
    }
  }
];
// 详细配置见 INTERFACE配置一览(在文档底部)

exceed.use(INTERFACE)

API调用

不含参数直接调用

exceed
  .fetch({
    api: 'test1',
  })
  .then((res) => {
    // 调用结果
  })
  .fail((err) => {
    // 调用失败结果
  });

含参数直接调用

exceed
  .fetch({
    api: 'test1',
    data: {
      withParam: 1 // POST同样通过data进行传参，不过会包裹在body中
    }
  })
  .then((res) => {
    // 调用结果
  })
  .fail((err) => {
    // 调用失败结果
  });

带模板的含参数直接调用

exceed
  .fetch({
    api: 'test2',
    data: {
      withParam: 1 // POST同样通过data进行传参，不过会包裹在body中
    },
    params: {
      action: 'ddd' // 此处用于替换模板中的字符串
    }
  })
  .then((res) => {
    // 调用结果
  })
  .fail((err) => {
    // 调用失败结果
  });

文件上传

const FILE = xxx.txt;
exceed
  .fetch({
    api: 'test2',
    file: FILE // 直接文件上传即可
    data: {
      withParam: 1 // 此处作为POST body传参
    }
  })
  .then((res) => {
    // 调用结果
  })
  .catch((err) => {
    // 由于使用fetch进行上传，错误处理函数名称变为catch
    // 调用失败结果
  });

jsonp

exceed.fetch({
    api: 'test5',
    jsonpCallback: 'callback' // callback name, default to 'callback'
})
  .then(function (resp) {
    // 调用结果
    console.log(resp.content);
  })
  .fail(function (err, msg) {
    // 调用失败结果
    console.log(msg);
  })

interceptors

1. 请求型拦截器

requestParams是组合了请求数据和APIMAP中定义的url数据的集合，config是初始化Exceed的全局配置.

exceed.interceptors.request.push((requestParams, config) => {
    requestParams.headers =  {
        'X-My-Custom-Header': 'SomethingImportant'
    };
    // 具体可配置参数有INTERFACE配置以及fetch时传入的data
})

2. 成功响应拦截器（目前不支持文件类型）

成功响应拦截器可修改返回的内容，会修改在then中返回的数据。

responseData是返回的数据，config是请求的参数(不可修改), originRequest是原始的xhr对象(只读)

exceed.interceptors.response.success.push((responseData, config， originRequest) => {
  
})

3. 失败响应拦截器（目前不支持文件类型）

在返回的状态码不为2xx，或返回的数据转换失败， 或返回的请求出现异常等情况会触发失败响应拦截器。 失败响应拦截器可修改传入的内容，会修改在fail中返回的数据，或是在then中传入的失败处理函数。

response为请求失败的xmlHttpReqest对象, msg为返回的失败消息(通常为数据转换失败的提示信息), t为特殊情况的返回, config是请求时的参数(不可修改)

exceed.interceptors.response.error.push((response, msg, t, config) => {
  
})

• 注意事项1： 如若返回的response中的状态码为0，同时readyState为4的时候，那么是请求发生了302跳转，此时无法检测到正常的response，但会进入到拦截器和fail函数中。

INTERFACE配置一览

仅method不为file时支持， method为file时仅支持url字段

• url
• method http方法
• headers http头(默认{})
• type 支持html, xml, json或者jsonp,用于设置资源，比如返回的数据是json则将type设置为json
• contentType 设置Contet-Type，比如application/json
• crossOrigin 用于设置浏览器跨域，默认为false (如需要带cookie请设置withCredentials为true)
• jsonpCallback 用于设置一个jsonp的请求的callback函数名，如果不设置callback函数名将会随机生成(不推荐)

支持的浏览器

使用file方法则仅支持带有fetch的浏览器:

• IE 11+
• Edge 14+
• chrome 49+
• firefox 50+

如不使用file方法则兼容较好，支持浏览器:

• IE6+
• Chrome 1+
• Safari 3+
• Firefox 1+
• Opera