umi request 请求资源库详解

umi-request:

网络请求库，基于fetch封装，兼具fetch 和 axios 的所有特点，具有缓存，超时，字符编码处理，错误处理等常用功能。

1 支持url 参数自动序列化。

2 post 数据提交方式简化。

3 api超时支持。

4 api请求缓存支持。

5 支持处理gbk.(gbk 一种字符集)。

6 类axios的request和response拦截器（interceptors）支持。

7 统一的错误处理方式。

8 类koa洋葱机制的use中间件机制支持。

9 类axios的取消处理。（cancel Token）.

10 支持Node环境发送http请求。

相较于fetch和axios 而言具有更多的功能，支持取消请求，中间件，超时，缓存等功能。

上手的基本示例：

首先，执行get 请求：

 1 import request from \'umi-request\';
 2 
 3 request
 4   .get(\'/api/v1/xxx?id=1\')
 5   .then(function(response) {
 6     console.log(response);
 7   })
 8   .catch(function(error) {
 9     console.log(error);
10   });

同时，也可将请求的url参数放在options,params中：

 1 request.get(\'/api/v1/xxx\', {
 2     params: {
 3       id: 1,
 4     },
 5   })
 6   .then(function(response) {
 7     console.log(response);
 8   })
 9   .catch(function(error) {
10     console.log(error);
11   });

执行基本的post请求：

 1 request
 2   .post(\'/api/v1/user\', {
 3     data: {
 4       name: \'Mike\',
 5     },
 6   })
 7   .then(function(response) {
 8     console.log(response);
 9   })
10   .catch(function(error) {
11     console.log(error);
12   });

umi-request的相关API:

可以通过向 umi-request 传参来发起请求，在method中指定请求方式。

umi-request(url[, options])：

示例：

 1 import request from \'umi-request\';
 2 
 3 request(\'/api/v1/xxx\', {
 4   method: \'get\',
 5   params: { id: 1 },
 6 })
 7   .then(function(response) {
 8     console.log(response);
 9   })
10   .catch(function(error) {
11     console.log(error);
12   });
13 
14 request(\'/api/v1/user\', {
15   method: \'post\',
16   data: {
17     name: \'Mike\',
18   },
19 })
20   .then(function(response) {
21     console.log(response);
22   })
23   .catch(function(error) {
24     console.log(error);
25   });

相关请求方法的别名，之后可以不用单独在method中配置请求方式。

request.get(url[, options])

request.post(url[, options])

request.delete(url[, options])

request.put(url[, options])

request.patch(url[, options])

request.head(url[, options])

request.options(url[, options])

如果有些配置多个请求当中都有使用到，则可以通过extend创建一个umi-request实例，将公共的配置放置在实例中。则可以实现配置的简化：extend([options])

示例：

1 import { extend } from \'umi-request\';
2 
3 const request = extend({
4   prefix: \'/api/v1\',
5   timeout: 1000,
6   headers: {
7     \'Content-Type\': \'multipart/form-data\',
8   },
9 });

之后这个get请求便可以使用extend中的公共配置。

1 request
2   .get(\'/user\')
3   .then(function(response) {
4     console.log(response);
5   })
6   .catch(function(error) {
7     console.log(error);
8   });

其他的请求方式同理。例如：post delete put patch head options 等。

请求参数的配置：request options 中的参数详情：

extend options的参数支持以上的所有参数。

参数含义详情：

  1 {
  2   // \'method\' 是创建请求时使用的方法
  3   method: \'get\', // default
  4 
  5   // \'params\' 是即将于请求一起发送的 URL 参数，参数会自动 encode 后添加到 URL 中
  6   // 类型需为 Object 对象或者 URLSearchParams 对象
  7   params: { id: 1 },
  8 
  9   // \'paramsSerializer\' 开发者可通过该函数对 params 做序列化（注意：此时传入的 params 为合并了 extends 中 params 参数的对象，如果传入的是 URLSearchParams 对象会转化为 Object 对象
 10   paramsSerializer: function (params) {
 11     return Qs.stringify(params, { arrayFormat: \'brackets\' })
 12   },
 13 
 14   // \'data\' 作为请求主体被发送的数据
 15   // 适用于这些请求方法 \'PUT\', \'POST\', 和 \'PATCH\'
 16   // 必须是以下类型之一：
 17   // - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
 18   // - 浏览器专属：FormData, File, Blob
 19   // - Node 专属： Stream
 20   data: { name: \'Mike\' },
 21 
 22   // \'headers\' 请求头
 23   headers: { \'Content-Type\': \'multipart/form-data\' },
 24 
 25   // \'timeout\' 指定请求超时的毫秒数（0 表示无超时时间）
 26   // 如果请求超过了 \'timeout\' 时间，请求将被中断并抛出请求异常
 27   timeout: 1000,
 28 
 29   // ’prefix‘ 前缀，统一设置 url 前缀
 30   // ( e.g. request(\'/user/save\', { prefix: \'/api/v1\' }) => request(\'/api/v1/user/save\') )
 31   prefix: \'\',
 32 
 33   // ’suffix‘ 后缀，统一设置 url 后缀
 34   // ( e.g. request(\'/api/v1/user/save\', { suffix: \'.json\'}) => request(\'/api/v1/user/save.json\') )
 35   suffix: \'\',
 36 
 37   // \'credentials\' 发送带凭据的请求
 38   // 为了让浏览器发送包含凭据的请求（即使是跨域源），需要设置 credentials: \'include\'
 39   // 如果只想在请求URL与调用脚本位于同一起源处时发送凭据，请添加credentials: \'same-origin\'
 40   // 要改为确保浏览器不在请求中包含凭据，请使用credentials: \'omit\'
 41   credentials: \'same-origin\', // default
 42 
 43   // ’useCache‘ 是否使用缓存，当值为 true 时，GET 请求在 ttl 毫秒内将被缓存，缓存策略唯一 key 为 url + params + method 组合
 44   useCache: false, // default
 45 
 46   // ’ttl‘ 缓存时长（毫秒）， 0 为不过期
 47   ttl: 60000,
 48 
 49   // \'maxCache\' 最大缓存数， 0 为无限制
 50   maxCache: 0,
 51 
 52   // 根据协议规范， GET 请求用于获取、查询服务端数据，在数据更新频率不频繁的情况下做必要的缓存能减少服务端的压力，因为缓存策略是默认对 GET 请求做缓存，但对于一些特殊场景需要缓存其他类型请求的响应数据时，我们提供 validateCache 供用户自定义何时需要进行缓存， key 依旧为 url + params + method
 53   validateCache: (url, options) => { return options.method.toLowerCase() === \'get\' },
 54 
 55   // \'requestType\' 当 data 为对象或者数组时， umi-request 会根据 requestType 动态添加 headers 和设置 body（可传入 headers 覆盖 Accept 和 Content-Type 头部属性）:
 56   // 1. requestType === \'json\' 时, (默认为 json )
 57   // options.headers = {
 58   //   Accept: \'application/json\',
 59   //   \'Content-Type\': \'application/json;charset=UTF-8\',
 60   //   ...options.headers,
 61   // }
 62   // options.body = JSON.stringify(data)
 63   // 2. requestType === \'form\' 时，
 64   // options.headers = {
 65   //   Accept: \'application/json\',
 66   //   \'Content-Type\': \'application/x-www-form-urlencoded;charset=UTF-8\',
 67   //   ...options.headers,
 68   // };
 69   // options.body = query-string.stringify(data);
 70   // 3. 其他 requestType
 71   // options.headers = {
 72   //   Accept: \'application/json\',
 73   //   ...options.headers,
 74   // };
 75   // options.body = data;
 76   requestType: \'json\', // default
 77 
 78   // ’parseResponse‘ 是否对请求返回的 Response 对象做格式、状态码解析
 79   parseResponse: true, // default
 80 
 81   // ’charset‘ 当服务端返回的数据编码类型为 gbk 时可使用该参数，umi-request 会按 gbk 编码做解析，避免得到乱码, 默认为 utf8
 82   // 当 parseResponse 值为 false 时该参数无效
 83   charset: \'gbk\',
 84 
 85   // \'responseType\': 如何解析返回的数据，当 parseResponse 值为 false 时该参数无效
 86   // 默认为 \'json\', 对返回结果进行 Response.text().then( d => JSON.parse(d) ) 解析
 87   // 其他(text, blob, arrayBuffer, formData), 做 Response[responseType]() 解析
 88   responseType: \'json\', // default
 89 
 90   // \'throwErrIfParseFail\': 当 responseType 为 json 但 JSON.parse(data) fail 时，是否抛出异常。默认不抛出异常而返回 Response.text() 后的结果，如需要抛出异常，可设置 throwErrIfParseFail 为 true
 91   throwErrIfParseFail: false, // default
 92 
 93   // \'getResponse\': 是否获取源 Response， 返回结果将包含一层： { data, response }
 94   getResponse: false,// default
 95 
 96   // \'errorHandler\' 统一的异常处理，供开发者对请求发生的异常做统一处理，详细使用请参考下方的错误处理文档
 97   errorHandler: function(error) { /* 异常处理 */ },
 98 
 99   // \'cancelToken\' 取消请求的 Token，详细使用请参考下方取消请求文档
100   cancelToken: null,
101 }

实例化请求实例之后，若还需要动态更新参数，umi-request中的extendOptions方法供用户进行更新。

const request = extend({ timeout: 1000, params: { a: \'1\' } });
// 默认参数是 { timeout: 1000, params: { a: \'1\' }}

request.extendOptions({ timeout: 3000, params: { b: \'2\' } });
// 此时默认参数是 { timeout: 3000, params: { a: \'1\', b: \'2\' }}

响应结构：

响应对象Response如下：

 1 {
 2   // `data` 由服务器提供的响应, 需要进行解析才能获取
 3   data: {},
 4 
 5   // `status` 来自服务器响应的 HTTP 状态码
 6   status: 200,
 7 
 8   // `statusText` 来自服务器响应的 HTTP 状态信息
 9   statusText: \'OK\',
10 
11   // `headers` 服务器响应的头
12   headers: {},
13 }

当 options.getResponse === false 时, 响应结构为解析后的 data：

request.get(\'/api/v1/xxx\', { getResponse: false }).then(function(data) {
  console.log(data);
});

当 options.getResponse === true 时，响应结构为包含 data 和 Response 的对象：

request.get(\'/api/v1/xxx\', { getResponse: true }).then(function({ data, response }) {
  console.log(data);
  console.log(response.status);
  console.log(response.statusText);
  console.log(response.headers);
});

错误处理：

 1 import request, { extend } from \'umi-request\';
 2 
 3 const errorHandler = function(error) {
 4   const codeMap = {
 5     \'021\': \'发生错误啦\',
 6     \'022\': \'发生大大大大错误啦\',
 7     // ....
 8   };
 9   if (error.response) {
10     // 请求已发送但服务端返回状态码非 2xx 的响应
11     console.log(error.response.status);
12     console.log(error.response.headers);
13     console.log(error.data);
14     console.log(error.request);
15     console.log(codeMap[error.data.status]);
16   } else {
17     // 请求初始化时出错或者没有响应返回的异常
18     console.log(error.message);
19   }
20 
21   throw error; // 如果throw. 错误将继续抛出.
22 
23   // 如果return, 则将值作为返回. \'return;\' 相当于return undefined, 在处理结果时判断response是否有值即可.
24   // return {some: \'data\'};
25 };
26 
27 // 1. 作为统一错误处理
28 const extendRequest = extend({ errorHandler });
29 
30 // 2. 单独特殊处理, 如果配置了统一处理, 但某个api需要特殊处理. 则在请求时, 将errorHandler作为参数传入.
31 request(\'/api/v1/xxx\', { errorHandler });
32 
33 // 3. 通过 Promise.catch 做错误处理
34 request(\'/api/v1/xxx\')
35   .then(function(response) {
36     console.log(response);
37   })
38   .catch(function(error) {
39     return errorHandler(error);
40   });

中间件机制，详情请转至：https://github.com/umijs/umi-request/blob/master/README_zh-CN.md