數據交互 axios 的使用

Axios 是一個基於 promise 的 HTTP 庫，能夠用在瀏覽器和 node.js 中。

##Axios

npm version
build status
code coverage
npm downloads
gitter chat

Axios 是一個基於 promise 的 HTTP 庫，能夠用在瀏覽器和 node.js 中。

Features
從瀏覽器中建立 XMLHttpRequests
從 node.js 建立 http 請求
支持 Promise API
攔截請求和響應
轉換請求數據和響應數據
取消請求
自動轉換 JSON 數據
客戶端支持防護 XSRF
瀏覽器支持
**    **    **    **    **    **
Latest ✔    Latest ✔    Latest ✔    Latest ✔    Latest ✔    8+ ✔
Browser Matrix

安裝
使用 npm:

$ npm install axios
使用 bower:

$ bower install axios
使用 cdn:

<script src="https://unpkg.com/axios/dist/axios.min.js"></script>
Example
執行 GET 請求

// 爲給定 ID 的 user 建立請求
axios.get('/user?ID=12345')
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  });

// 可選地，上面的請求能夠這樣作
axios.get('/user', {
    params: {
      ID: 12345
    }
  })
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  });
執行 POST 請求

axios.post('/user', {
    firstName: 'Fred',
    lastName: 'Flintstone'
  })
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  });
執行多個併發請求

function getUserAccount() {
  return axios.get('/user/12345');
}

function getUserPermissions() {
  return axios.get('/user/12345/permissions');
}

axios.all([getUserAccount(), getUserPermissions()])
  .then(axios.spread(function (acct, perms) {
    // 兩個請求如今都執行完成
  }));
axios API
能夠經過向 axios 傳遞相關配置來建立請求

axios(config)
// 發送 POST 請求
axios({
  method: 'post',
  url: '/user/12345',
  data: {
    firstName: 'Fred',
    lastName: 'Flintstone'
  }
});
axios(url[, config])
// 發送 GET 請求（默認的方法）
axios('/user/12345');
請求方法的別名
爲方便起見，爲全部支持的請求方法提供了別名

axios.request(config)
axios.get(url[, config])
axios.delete(url[, config])
axios.head(url[, config])
axios.post(url[, data[, config]])
axios.put(url[, data[, config]])
axios.patch(url[, data[, config]])
NOTE
在使用別名方法時， url、method、data 這些屬性都沒必要在配置中指定。

併發
處理併發請求的助手函數

axios.all(iterable)
axios.spread(callback)
建立實例
可使用自定義配置新建一個 axios 實例

axios.create([config])
var instance = axios.create({
  baseURL: 'https://some-domain.com/api/',
  timeout: 1000,
  headers: {'X-Custom-Header': 'foobar'}
});
實例方法
如下是可用的實例方法。指定的配置將與實例的配置合併

axios#request(config)
axios#get(url[, config])
axios#delete(url[, config])
axios#head(url[, config])
axios#post(url[, data[, config]])
axios#put(url[, data[, config]])
axios#patch(url[, data[, config]])
請求配置
這些是建立請求時能夠用的配置選項。只有 url 是必需的。若是沒有指定 method，請求將默認使用 get 方法。

{
  // `url` 是用於請求的服務器 URL
  url: '/user',

  // `method` 是建立請求時使用的方法
  method: 'get', // 默認是 get

  // `baseURL` 將自動加在 `url` 前面，除非 `url` 是一個絕對 URL。
  // 它能夠經過設置一個 `baseURL` 便於爲 axios 實例的方法傳遞相對 URL
  baseURL: 'https://some-domain.com/api/',

  // `transformRequest` 容許在向服務器發送前，修改請求數據
  // 只能用在 'PUT', 'POST' 和 'PATCH' 這幾個請求方法
  // 後面數組中的函數必須返回一個字符串，或 ArrayBuffer，或 Stream
  transformRequest: [function (data) {
    // 對 data 進行任意轉換處理

    return data;
  }],

  // `transformResponse` 在傳遞給 then/catch 前，容許修改響應數據
  transformResponse: [function (data) {
    // 對 data 進行任意轉換處理

    return data;
  }],

  // `headers` 是即將被髮送的自定義請求頭
  headers: {'X-Requested-With': 'XMLHttpRequest'},

  // `params` 是即將與請求一塊兒發送的 URL 參數
  // 必須是一個無格式對象(plain object)或 URLSearchParams 對象
  params: {
    ID: 12345
  },

  // `paramsSerializer` 是一個負責 `params` 序列化的函數
  // (e.g. https://www.npmjs.com/package/qs, http://api.jquery.com/jquery.param/)
  paramsSerializer: function(params) {
    return Qs.stringify(params, {arrayFormat: 'brackets'})
  },

  // `data` 是做爲請求主體被髮送的數據
  // 只適用於這些請求方法 'PUT', 'POST', 和 'PATCH'
  // 在沒有設置 `transformRequest` 時，必須是如下類型之一：
  // - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
  // - 瀏覽器專屬：FormData, File, Blob
  // - Node 專屬： Stream
  data: {
    firstName: 'Fred'
  },

  // `timeout` 指定請求超時的毫秒數(0 表示無超時時間)
  // 若是請求話費了超過 `timeout` 的時間，請求將被中斷
  timeout: 1000,

  // `withCredentials` 表示跨域請求時是否須要使用憑證
  withCredentials: false, // 默認的

  // `adapter` 容許自定義處理請求，以使測試更輕鬆
  // 返回一個 promise 並應用一個有效的響應 (查閱 [response docs](#response-api)).
  adapter: function (config) {
    /* ... */
  },

  // `auth` 表示應該使用 HTTP 基礎驗證，並提供憑據
  // 這將設置一個 `Authorization` 頭，覆寫掉現有的任意使用 `headers` 設置的自定義 `Authorization`頭
  auth: {
    username: 'janedoe',
    password: 's00pers3cret'
  },

  // `responseType` 表示服務器響應的數據類型，能夠是 'arraybuffer', 'blob', 'document', 'json', 'text', 'stream'
  responseType: 'json', // 默認的

  // `xsrfCookieName` 是用做 xsrf token 的值的cookie的名稱
  xsrfCookieName: 'XSRF-TOKEN', // default

  // `xsrfHeaderName` 是承載 xsrf token 的值的 HTTP 頭的名稱
  xsrfHeaderName: 'X-XSRF-TOKEN', // 默認的

  // `onUploadProgress` 容許爲上傳處理進度事件
  onUploadProgress: function (progressEvent) {
    // 對原生進度事件的處理
  },

  // `onDownloadProgress` 容許爲下載處理進度事件
  onDownloadProgress: function (progressEvent) {
    // 對原生進度事件的處理
  },

  // `maxContentLength` 定義容許的響應內容的最大尺寸
  maxContentLength: 2000,

  // `validateStatus` 定義對於給定的HTTP 響應狀態碼是 resolve 或 reject  promise 。若是 `validateStatus` 返回 `true` (或者設置爲 `null` 或 `undefined`)，promise 將被 resolve; 不然，promise 將被 rejecte
  validateStatus: function (status) {
    return status >= 200 && status < 300; // 默認的
  },

  // `maxRedirects` 定義在 node.js 中 follow 的最大重定向數目
  // 若是設置爲0，將不會 follow 任何重定向
  maxRedirects: 5, // 默認的

  // `httpAgent` 和 `httpsAgent` 分別在 node.js 中用於定義在執行 http 和 https 時使用的自定義代理。容許像這樣配置選項：
  // `keepAlive` 默認沒有啓用
  httpAgent: new http.Agent({ keepAlive: true }),
  httpsAgent: new https.Agent({ keepAlive: true }),

  // 'proxy' 定義代理服務器的主機名稱和端口
  // `auth` 表示 HTTP 基礎驗證應當用於鏈接代理，並提供憑據
  // 這將會設置一個 `Proxy-Authorization` 頭，覆寫掉已有的經過使用 `header` 設置的自定義 `Proxy-Authorization` 頭。
  proxy: {
    host: '127.0.0.1',
    port: 9000,
    auth: : {
      username: 'mikeymike',
      password: 'rapunz3l'
    }
  },

  // `cancelToken` 指定用於取消請求的 cancel token
  // （查看後面的 Cancellation 這節瞭解更多）
  cancelToken: new CancelToken(function (cancel) {
  })
}
響應結構
某個請求的響應包含如下信息

{
  // `data` 由服務器提供的響應
  data: {},

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

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

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

  // `config` 是爲請求提供的配置信息
  config: {}
}
使用 then 時，你將接收下面這樣的響應：

axios.get('/user/12345')
  .then(function(response) {
    console.log(response.data);
    console.log(response.status);
    console.log(response.statusText);
    console.log(response.headers);
    console.log(response.config);
  });
在使用 catch 時，或傳遞 rejection callback 做爲 then 的第二個參數時，響應能夠經過 error 對象可被使用，正如在錯誤處理這一節所講。

配置的默認值 / defaults
你能夠指定將被用在各個請求的配置默認值

全局的 axios 默認值
axios.defaults.baseURL = 'https://api.example.com';
axios.defaults.headers.common['Authorization'] = AUTH_TOKEN;
axios.defaults.headers.post['Content-Type'] = 'application/x-www-form-urlencoded';
自定義實例默認值
// 建立實例時設置配置的默認值
var instance = axios.create({
  baseURL: 'https://api.example.com'
});

// 在實例已建立後修改默認值
instance.defaults.headers.common['Authorization'] = AUTH_TOKEN;
配置的優先順序
配置會以一個優先順序進行合併。這個順序是：在 lib/defaults.js 找到的庫的默認值，而後是實例的 defaults 屬性，最後是請求的 config 參數。後者將優先於前者。這裏是一個例子：

// 使用由庫提供的配置的默認值來建立實例
// 此時超時配置的默認值是 `0`
var instance = axios.create();

// 覆寫庫的超時默認值
// 如今，在超時前，全部請求都會等待 2.5 秒
instance.defaults.timeout = 2500;

// 爲已知須要花費很長時間的請求覆寫超時設置
instance.get('/longRequest', {
  timeout: 5000
});
攔截器
在請求或響應被 then 或 catch 處理前攔截它們。

// 添加請求攔截器
axios.interceptors.request.use(function (config) {
    // 在發送請求以前作些什麼
    return config;
  }, function (error) {
    // 對請求錯誤作些什麼
    return Promise.reject(error);
  });

// 添加響應攔截器
axios.interceptors.response.use(function (response) {
    // 對響應數據作點什麼
    return response;
  }, function (error) {
    // 對響應錯誤作點什麼
    return Promise.reject(error);
  });
若是你想在稍後移除攔截器，能夠這樣：

var myInterceptor = axios.interceptors.request.use(function () {/*...*/});
axios.interceptors.request.eject(myInterceptor);
能夠爲自定義 axios 實例添加攔截器

var instance = axios.create();
instance.interceptors.request.use(function () {/*...*/});
錯誤處理
axios.get('/user/12345')
  .catch(function (error) {
    if (error.response) {
      // 請求已發出，但服務器響應的狀態碼不在 2xx 範圍內
      console.log(error.response.data);
      console.log(error.response.status);
      console.log(error.response.headers);
    } else {
      // Something happened in setting up the request that triggered an Error
      console.log('Error', error.message);
    }
    console.log(error.config);
  });
可使用 validateStatus 配置選項定義一個自定義 HTTP 狀態碼的錯誤範圍。

axios.get('/user/12345', {
  validateStatus: function (status) {
    return status < 500; // 狀態碼在大於或等於500時纔會 reject
  }
})
取消
使用 cancel token 取消請求

Axios 的 cancel token API 基於 cancelable promises proposal，它還處於第一階段。

可使用 CancelToken.source 工廠方法建立 cancel token，像這樣：

var CancelToken = axios.CancelToken;
var source = CancelToken.source();

axios.get('/user/12345', {
  cancelToken: source.token
}).catch(function(thrown) {
  if (axios.isCancel(thrown)) {
    console.log('Request canceled', thrown.message);
  } else {
    // 處理錯誤
  }
});

// 取消請求（message 參數是可選的）
source.cancel('Operation canceled by the user.');
還能夠經過傳遞一個 executor 函數到 CancelToken 的構造函數來建立 cancel token：

var CancelToken = axios.CancelToken;
var cancel;

axios.get('/user/12345', {
  cancelToken: new CancelToken(function executor(c) {
    // executor 函數接收一個 cancel 函數做爲參數
    cancel = c;
  })
});

// 取消請求
cancel();
Note : 可使用同一個 cancel token 取消多個請求

Semver
Until axios reaches a 1.0 release, breaking changes will be released with a new minor version. For example 0.5.1, and 0.5.4 will have the same API, but 0.6.0 will have breaking changes.

Promises
axios 依賴原生的 ES6 Promise 實現而被支持.
若是你的環境不支持 ES6 Promise，你可使用 polyfill.

TypeScript
axios includes TypeScript definitions.

import axios from 'axios';
axios.get('/user?ID=12345');
Resources
Changelog
Upgrade Guide
Ecosystem
Contributing Guide
Code of Conduct
Credits
axios is heavily inspired by the $http service provided in Angular. Ultimately axios is an effort to provide a standalone $http-like service for use outside of Angular.

升級指南
Upgrade Guide
0.13.x -> 0.14.0
TypeScript Definitions
The axios TypeScript definitions have been updated to match the axios API and use the ES2015 module syntax.

Please use the following import statement to import axios in TypeScript:

import axios from 'axios';

axios.get('/foo')
  .then(response => console.log(response))
  .catch(error => console.log(error));
agent Config Option
The agent config option has been replaced with two new options: httpAgent and httpsAgent. Please use them instead.

{
  // Define a custom agent for HTTP
  httpAgent: new http.Agent({ keepAlive: true }),
  // Define a custom agent for HTTPS
  httpsAgent: new https.Agent({ keepAlive: true })
}
progress Config Option
The progress config option has been replaced with the onUploadProgress and onDownloadProgress options.

{
  // Define a handler for upload progress events
  onUploadProgress: function (progressEvent) {
    // ...
  },

  // Define a handler for download progress events
  onDownloadProgress: function (progressEvent) {
    // ...
  }
}
0.12.x -> 0.13.0
The 0.13.0 release contains several changes to custom adapters and error handling.

Error Handling
Previous to this release an error could either be a server response with bad status code or an actual Error. With this release Promise will always reject with an Error. In the case that a response was received, the Error will also include the response.

axios.get('/user/12345')
  .catch((error) => {
    console.log(error.message);
    console.log(error.code); // Not always specified
    console.log(error.config); // The config that was used to make the request
    console.log(error.response); // Only available if response was received from the server
  });
Request Adapters
This release changes a few things about how request adapters work. Please take note if you are using your own custom adapter.

Response transformer is now called outside of adapter.
Request adapter returns a Promise.
This means that you no longer need to invoke transformData on response data. You will also no longer receive resolve and reject as arguments in your adapter.

Previous code:

function myAdapter(resolve, reject, config) {
  var response = {
    data: transformData(
      responseData,
      responseHeaders,
      config.transformResponse
    ),
    status: request.status,
    statusText: request.statusText,
    headers: responseHeaders
  };
  settle(resolve, reject, response);
}
New code:

function myAdapter(config) {
  return new Promise(function (resolve, reject) {
    var response = {
      data: responseData,
      status: request.status,
      statusText: request.statusText,
      headers: responseHeaders
    };
    settle(resolve, reject, response);
  });
}
See the related commits for more details:

Response transformers
Request adapter Promise
0.5.x -> 0.6.0
The 0.6.0 release contains mostly bug fixes, but there are a couple things to be aware of when upgrading.

ES6 Promise Polyfill
Up until the 0.6.0 release ES6 Promise was being polyfilled using es6-promise. With this release, the polyfill has been removed, and you will need to supply it yourself if your environment needs it.

require('es6-promise').polyfill();
var axios = require('axios');
This will polyfill the global environment, and only needs to be done once.

axios.success/axios.error
The success, and error aliases were deprectated in 0.4.0. As of this release they have been removed entirely. Instead please use axios.then, and axios.catch respectively.

axios.get('some/url')
  .then(function (res) {
    /* ... */
  })
  .catch(function (err) {
    /* ... */
  });
UMD
Previous versions of axios shipped with an AMD, CommonJS, and Global build. This has all been rolled into a single UMD build.

// AMD
require(['bower_components/axios/dist/axios'], function (axios) {
  /* ... */
});

// CommonJS
var axios = require('axios/dist/axios');
生態系統
Ecosystem
This is a list of axios related libraries and resources. If you have a suggestion on what to add, please don’t hesitate to submit a PR.

Libraries
moxios - Mock axios requests for testing
axios-response-logger - Axios interceptor which logs responses
axios-mock-adapter — Axios adapter that allows to easily mock requests
redux-axios-middleware - Redux middleware for fetching data with axios HTTP client
axios-vcr - Record and Replay Axios requests
@3846masa/axios-cookiejar-support - Add tough-cookie support to axios
vue-axios - A small wrapper for integrating axios to Vuejs

本文做者： IIsKei
本文連接： http://www.iskei.cn/posts/12277.html
版權聲明： 本博客全部文章除特別聲明外，均採用 CC BY-NC-SA 4.0 許可協議。轉載請註明出處！