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 請求：

import request from 'umi-request';

request
  .get('/api/v1/xxx?id=1')
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

同時，也可將請求的url參數放在options,params中：

request.get('/api/v1/xxx', {
    params: {
      id: 1,
    },
  })
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

執行基本的post請求：

request
  .post('/api/v1/user', {
    data: {
      name: 'Mike',
    },
  })
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

umi-request的相關API:

可以通過向 umi-request 傳參來發起請求，在method中指定請求方式。

umi-request(url[, options])：

示例：

import request from 'umi-request';

request('/api/v1/xxx', {
  method: 'get',
  params: { id: 1 },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

request('/api/v1/user', {
  method: 'post',
  data: {
    name: 'Mike',
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

相關請求方法的別名，之后可以不用單獨在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])

示例：

import { extend } from 'umi-request';

const request = extend({
  prefix: '/api/v1',
  timeout: 1000,
  headers: {
    'Content-Type': 'multipart/form-data',
  },
});

之后這個get請求便可以使用extend中的公共配置。

request
  .get('/user')
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

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

請求參數的配置：request options 中的參數詳情：

 

 

 

 

 extend options的參數支持以上的所有參數。

 參數含義詳情：

{
  // 'method' 是創建請求時使用的方法
  method: 'get', // default

  // 'params' 是即將於請求一起發送的 URL 參數，參數會自動 encode 后添加到 URL 中
  // 類型需為 Object 對象或者 URLSearchParams 對象
  params: { id: 1 },

  // 'paramsSerializer' 開發者可通過該函數對 params 做序列化（注意：此時傳入的 params 為合並了 extends 中 params 參數的對象，如果傳入的是 URLSearchParams 對象會轉化為 Object 對象
  paramsSerializer: function (params) {
    return Qs.stringify(params, { arrayFormat: 'brackets' })
  },

  // 'data' 作為請求主體被發送的數據
  // 適用於這些請求方法 'PUT', 'POST', 和 'PATCH'
  // 必須是以下類型之一：
  // - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
  // - 瀏覽器專屬：FormData, File, Blob
  // - Node 專屬： Stream
  data: { name: 'Mike' },

  // 'headers' 請求頭
  headers: { 'Content-Type': 'multipart/form-data' },

  // 'timeout' 指定請求超時的毫秒數（0 表示無超時時間）
  // 如果請求超過了 'timeout' 時間，請求將被中斷並拋出請求異常
  timeout: 1000,

  // ’prefix‘ 前綴，統一設置 url 前綴
  // ( e.g. request('/user/save', { prefix: '/api/v1' }) => request('/api/v1/user/save') )
  prefix: '',

  // ’suffix‘ 后綴，統一設置 url 后綴
  // ( e.g. request('/api/v1/user/save', { suffix: '.json'}) => request('/api/v1/user/save.json') )
  suffix: '',

  // 'credentials' 發送帶憑據的請求
  // 為了讓瀏覽器發送包含憑據的請求（即使是跨域源），需要設置 credentials: 'include'
  // 如果只想在請求URL與調用腳本位於同一起源處時發送憑據，請添加credentials: 'same-origin'
  // 要改為確保瀏覽器不在請求中包含憑據，請使用credentials: 'omit'
  credentials: 'same-origin', // default

  // ’useCache‘ 是否使用緩存，當值為 true 時，GET 請求在 ttl 毫秒內將被緩存，緩存策略唯一 key 為 url + params + method 組合
  useCache: false, // default

  // ’ttl‘ 緩存時長（毫秒）， 0 為不過期
  ttl: 60000,

  // 'maxCache' 最大緩存數， 0 為無限制
  maxCache: 0,

  // 根據協議規范， GET 請求用於獲取、查詢服務端數據，在數據更新頻率不頻繁的情況下做必要的緩存能減少服務端的壓力，因為緩存策略是默認對 GET 請求做緩存，但對於一些特殊場景需要緩存其他類型請求的響應數據時，我們提供 validateCache 供用戶自定義何時需要進行緩存， key 依舊為 url + params + method
  validateCache: (url, options) => { return options.method.toLowerCase() === 'get' },

  // 'requestType' 當 data 為對象或者數組時， umi-request 會根據 requestType 動態添加 headers 和設置 body（可傳入 headers 覆蓋 Accept 和 Content-Type 頭部屬性）:
  // 1. requestType === 'json' 時, (默認為 json )
  // options.headers = {
  //   Accept: 'application/json',
  //   'Content-Type': 'application/json;charset=UTF-8',
  //   ...options.headers,
  // }
  // options.body = JSON.stringify(data)
  // 2. requestType === 'form' 時，
  // options.headers = {
  //   Accept: 'application/json',
  //   'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8',
  //   ...options.headers,
  // };
  // options.body = query-string.stringify(data);
  // 3. 其他 requestType
  // options.headers = {
  //   Accept: 'application/json',
  //   ...options.headers,
  // };
  // options.body = data;
  requestType: 'json', // default

  // ’parseResponse‘ 是否對請求返回的 Response 對象做格式、狀態碼解析
  parseResponse: true, // default

  // ’charset‘ 當服務端返回的數據編碼類型為 gbk 時可使用該參數，umi-request 會按 gbk 編碼做解析，避免得到亂碼, 默認為 utf8
  // 當 parseResponse 值為 false 時該參數無效
  charset: 'gbk',

  // 'responseType': 如何解析返回的數據，當 parseResponse 值為 false 時該參數無效
  // 默認為 'json', 對返回結果進行 Response.text().then( d => JSON.parse(d) ) 解析
  // 其他(text, blob, arrayBuffer, formData), 做 Response[responseType]() 解析
  responseType: 'json', // default

  // 'throwErrIfParseFail': 當 responseType 為 json 但 JSON.parse(data) fail 時，是否拋出異常。默認不拋出異常而返回 Response.text() 后的結果，如需要拋出異常，可設置 throwErrIfParseFail 為 true
  throwErrIfParseFail: false, // default

  // 'getResponse': 是否獲取源 Response， 返回結果將包含一層： { data, response }
  getResponse: false,// default

  // 'errorHandler' 統一的異常處理，供開發者對請求發生的異常做統一處理，詳細使用請參考下方的錯誤處理文檔
  errorHandler: function(error) { /* 異常處理 */ },

  // 'cancelToken' 取消請求的 Token，詳細使用請參考下方取消請求文檔
  cancelToken: null,
}

實例化請求實例之后，若還需要動態更新參數，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如下：

{
  // `data` 由服務器提供的響應, 需要進行解析才能獲取
  data: {},

  // `status` 來自服務器響應的 HTTP 狀態碼
  status: 200,

  // `statusText` 來自服務器響應的 HTTP 狀態信息
  statusText: 'OK',

  // `headers` 服務器響應的頭
  headers: {},
}

當 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);
});

錯誤處理：

import request, { extend } from 'umi-request';

const errorHandler = function(error) {
  const codeMap = {
    '021': '發生錯誤啦',
    '022': '發生大大大大錯誤啦',
    // ....
  };
  if (error.response) {
    // 請求已發送但服務端返回狀態碼非 2xx 的響應
    console.log(error.response.status);
    console.log(error.response.headers);
    console.log(error.data);
    console.log(error.request);
    console.log(codeMap[error.data.status]);
  } else {
    // 請求初始化時出錯或者沒有響應返回的異常
    console.log(error.message);
  }

  throw error; // 如果throw. 錯誤將繼續拋出.

  // 如果return, 則將值作為返回. 'return;' 相當於return undefined, 在處理結果時判斷response是否有值即可.
  // return {some: 'data'};
};

// 1. 作為統一錯誤處理
const extendRequest = extend({ errorHandler });

// 2. 單獨特殊處理, 如果配置了統一處理, 但某個api需要特殊處理. 則在請求時, 將errorHandler作為參數傳入.
request('/api/v1/xxx', { errorHandler });

// 3. 通過 Promise.catch 做錯誤處理
request('/api/v1/xxx')
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    return errorHandler(error);
  });

中間件機制，詳情請轉至：https://github.com/umijs/umi-request/blob/master/README_zh-CN.md