原文地址：https://github.com/axios/axios/blob/master/README.md

http://www.cnblogs.com/libin-1/p/6607945.html

axios

axios 是一个基于Promise 用于浏览器和 nodejs 的 HTTP client。

特征

从浏览器创建 XMLHttpRequests
从node.js 发出 http 请求
支持 Promise API
拦截请求(request) 和响应(response)
转换请求和响应数据
终止请求
自动转换 JSON 数据
Client 端支持防范 XSRF

浏览器兼容性


Latest ✔	Latest ✔	Latest ✔	Latest ✔	Latest ✔	11 ✔

安装

用 npm:

$ npm install axios

用 bower:

$ bower install axios

用 cdn:

<script src="https://unpkg.com/axios/dist/axios.min.js"></script>

样例

执行一个GET 请求

const axios = require('axios');

// 向具有给定ID的用户发出请求
axios.get('/user?ID=12345')
  .then(function (response) {
    // 响应 success
    console.log(response);
  })
  .catch(function (error) {
    // 响应 error
    console.log(error);
  })
  .then(function () {
    // always executed
  });

// 上面的请求也可以通过下面params传递参数的方式实现
axios.get('/user', {
    params: {
      ID: 12345
    }
  })
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  })
  .then(function () {
    // always executed
  });  

// 想使用async/await吗? 添加`async`关键字到你的函数/方法前面就行
async function getUser() {
  try {
    const response = await axios.get('/user?ID=12345');
    console.log(response);
  } catch (error) {
    console.error(error);
  }
}

注意: async/await 是 ECMAScript 2017 的一部分，不支持Internet Explorer和旧版浏览器，因此请谨慎使用。

执行一个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'
  }
});
// GET请求远程图片
axios({
  method:'get',
  url:'http://bit.ly/2mTM3nY',
  responseType:'stream'
})
  .then(function (response) {
    response.data.pipe(fs.createWriteStream('ada_lovelace.jpg'))
  });

axios(url[, config])

// 发送一个GET请求 (GET请求是默认请求方式)
axios('/user/12345');

请求方法别名

为了方便起见，已经为所有支持的请求方法起了别名。

axios.request(config)

axios.get(url[, config])

axios.delete(url[, config])

axios.head(url[, config])

axios.options(url[, config])

axios.post(url[, data[, config]])

axios.put(url[, data[, config]])

axios.patch(url[, data[, config]])

注意

当使用别名方法时，不需要在在config中指定 url, method, 和 data 属性。

并发

帮助函数处理并发请求

axios.all(iterable)

axios.spread(callback)

创建实例

你可以使用自定义配置创建一个 axios 的新实例。

axios.create([config])

const 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#options(url[, config])

axios#post(url[, data[, config]])

axios#put(url[, data[, config]])

axios#patch(url[, data[, config]])

axios#getUri([config])

请求配置

以下是用于发请求的可用配置项，只有 url 是必须的，默认的请求方式是GET 。

{
  // `url` 是用来请求的服务器URL
  url: '/user',

  // `method` 是发请求时的请求方式
  method: 'get', // 默认是get

  // `baseURL` 会被加到`url`前面，除非`url`已经写全了。
  // 它可以方便的为axios实例设置`baseURL`，然后传递相关联的URLs给实例对应的方法
  baseURL: 'https://some-domain.com/api/',

  // `transformRequest`允许请求数据在发送到服务器之前对其进行更改
  // 仅适用于'PUT', 'POST', 'PATCH'
  // 数组中的最后一个函数必须返回一个string或者Buffer、ArrayBuffer、FormData或Stream的实例
  // 你可以修改headers对象.
  transformRequest: [function (data, headers) {
    // Do whatever you want to transform the data

    return data;
  }],

  // `transformResponse` 允许数据在传到then/catch之前对其进行更改
  transformResponse: [function (data) {
    // Do whatever you want to transform the data

    return data;
  }],

  // `headers` 发送自定义headers
  headers: {'X-Requested-With': 'XMLHttpRequest'},

  // `params` URL参数，必须做位一个普通对象或者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
  // - Browser only: FormData, File, Blob
  // - Node only: Stream, Buffer
  data: {
    firstName: 'Fred'
  },

  // `timeout` 指定请求超时的时间，单位：毫秒
  // 如果请求的时间超过`timeout`, 请求即被中止
  timeout: 1000, // default is `0` (no timeout)

  // `withCredentials` 跨站点访问是否适用证书
  withCredentials: false, // 默认不使用

  // `adapter` 允许自定义处理请求，这使得测试更容易。
  // 返回一个promise并提供一个有效的响应 (see lib/adapters/README.md).
  adapter: function (config) {
    /* ... */
  },

  // `auth` 使用HTTP认证, 并提供凭据。
  // 设置一个带`Authorization'的header，覆盖任何现有的用`headers`参数设置的`Authorization'自定义headers.
  auth: {
    username: 'janedoe',
    password: 's00pers3cret'
  },

  // `responseType` 服务器将响应的数据类型，包括'arraybuffer', 'blob', 'document', 'json', 'text', 'stream'
  responseType: 'json', // default

  // `responseEncoding` 用于解码响应的编码方式
  // 注: 忽略`responseType`的'stream'，或者客户端请求
  responseEncoding: 'utf8', // default

  // `xsrfCookieName` 用作 xsrf 令牌的值的cookie的名称
  xsrfCookieName: 'XSRF-TOKEN', // default

  // `xsrfHeaderName` 携带xsrf令牌值的http header的名称
  xsrfHeaderName: 'X-XSRF-TOKEN', // default

  // `onUploadProgress` 允许处理上传的进度事件
  onUploadProgress: function (progressEvent) {
    // Do whatever you want with the native progress event
  },

  // `onDownloadProgress` 允许处理下载的进度事件
  onDownloadProgress: function (progressEvent) {
    // Do whatever you want with the native progress event
  },

  // `maxContentLength` 定义允许的http响应内容的最大bytes
  maxContentLength: 2000,

  // `validateStatus` 对于一个给定的HTTP响应状态码，是resolve 还是reject 这个promise。如果`validateStatus`返回`true` (或者 `null`,`undefined`), 这个promise will be resolved; 否则，这个promise will be rejected.
  validateStatus: function (status) {
    return status >= 200 && status < 300; // default
  },

  // `maxRedirects` 在node.js中要遵循的重定向的最大数量。
  // 如果设为0，不会有重定向，默认5
  maxRedirects: 5, // default

  // `socketPath` 定义一个在node.js里面用的UNIX Socket。
  // e.g. '/var/run/docker.sock' 是发送请求到docker后台.
  // 只能指定`socketPath`和`proxy`中的一个。
  // 如果都被指定，按`socketPath`的生效。
  socketPath: null, // default

  // `httpAgent` and `httpsAgent` 在node.js中，分别执行http和https请求时使用的自定义代理。
  // 允许配置类似`keepAlive`这样在默认情况下不启用的选项。
  httpAgent: new http.Agent({ keepAlive: true }),
  httpsAgent: new https.Agent({ keepAlive: true }),

  // 'proxy' 定义代理服务器的主机名和端口。
  // 你也可以用常规的`http_proxy`和`https_proxy`环境变量来定义你的代理。
  // 如果给你的代理配置使用环境变量，你也可以定义一个不代理的`no_proxy`环境变量，内容是一个以逗号分隔的域名列表。
  // 设成`false`就禁用代理，忽略环境变量。
  // `auth`表示HTTP Basic auth会被用于连接到代理，并提供凭证。
  // 这将设置一个`Proxy-Authorization` header，覆盖先前`headers`参数里面设置的`Proxy-Authorization` 自定义headers。
  proxy: {
    host: '127.0.0.1',
    port: 9000,
    auth: {
      username: 'mikeymike',
      password: 'rapunz3l'
    }
  },

  // `cancelToken` 指定可用于取消请求的取消令牌
  // (详情参阅下面的消除部分)
  cancelToken: new CancelToken(function (cancel) {
  })
}

响应模式

请求的响应包含以下信息

{
  // `data` 提供服务器的响应
  data: {},

  // `status` 来自服务器响应的HTTP状态码
  status: 200,

  // `statusText` 来自服务器响应的HTTP状态消息
  statusText: 'OK',

  // `headers` 来自服务器响应的headers，所有header names都是小写
  headers: {},

  // `config` 提供了`axios`请求的配置
  config: {},

  // `request` 生成这个响应的请求
  // 这是node.js中最后的客户端请求实例(重定向)和浏览器XMLHttpRequest实例
  request: {}
}

使用 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或用拒绝回调作为 then的第二个参数时，响应将可以通过 error 对象来解释处理错误的部分.

配置默认值

你可以给每一个请求指定默认配置。

全局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';

自定义实例默认值

// 创建实例时设置默认配置
const instance = axios.create({
  baseURL: 'https://api.example.com'
});

// 实例创建后改变默认配置
instance.defaults.headers.common['Authorization'] = AUTH_TOKEN;

配置优先级顺序

配置将按优先顺序改变，顺序是 lib/defaults.js 库中的默认值，然后是实例的 defaults属性，最后 config 请求的参数。后者的配置优先于前者生效。这里有一个例子：

// 使用库提供的配置默认值创建实例
// 此时，timeout值为`0`，这是库的默认值
const instance = axios.create();

// 重写timeout的库默认值
// 现在所有请求将在timeout前等待2.5秒
instance.defaults.timeout = 2500;

// 重写这个请求的timeout，因为知道它需要很长时间
instance.get('/longRequest', {
  timeout: 5000
});

拦截器

你可以拦截请求或者响应在他们被 then or catch 处理之前。

// 添加请求拦截器
axios.interceptors.request.use(function (config) {
    // Do something before request is sent
    return config;
  }, function (error) {
    // Do something with request error
    return Promise.reject(error);
  });

// 添加响应拦截器
axios.interceptors.response.use(function (response) {
    // Do something with response data
    return response;
  }, function (error) {
    // Do something with response error
    return Promise.reject(error);
  });

当你需要删除拦截器时就能删掉。

const myInterceptor = axios.interceptors.request.use(function () {/*...*/});
axios.interceptors.request.eject(myInterceptor);

你可以将拦截器添加到axios的自定义实例。

const 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 if (error.request) {
      // 请求已发出，但是没有收到响应。
      // `error.request` 是浏览器中的一个XMLHttpRequest实例
      // 和node.js中的一个http.ClientRequest实例
      console.log(error.request);
    } else {
      // 设置触发错误的请求时发生了错误
      console.log('Error', error.message);
    }
    console.log(error.config);
  });

您可以使用validateStatus配置选项定义自定义HTTP状态码错误范围。

axios.get('/user/12345', {
  validateStatus: function (status) {
    return status < 500; // 仅当状态代码大于或等于500时拒绝
  }
})

消除

您可以使用 取消令牌取消请求。

axios 取消令牌 API 基于撤销的可取消承诺提议.

您可以使用 CancelToken.source 工厂创建一个取消令牌，如下所示：

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

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

axios.post('/user/12345', {
  name: 'new name'
}, {
  cancelToken: source.token
})

// cancel the request (the message parameter is optional)
source.cancel('Operation canceled by the user.');

您还可以通过将执行器函数传递给 CancelToken 构造函数来创建取消令牌：

const CancelToken = axios.CancelToken;
let cancel;

axios.get('/user/12345', {
  cancelToken: new CancelToken(function executor(c) {
    // 一个执行器函数接收一个取消函数作为参数
    cancel = c;
  })
});

// cancel the request
cancel();

注意：您可以使用相同数量的取消令牌取消对应的请求。

使用 application/x-www-form-urlencoded 格式

默认情况下，axios将JavaScript对象序列化为JSON。发送数据时想用 application/x-www-form-urlencoded格式来代替，你可以在下列选项中选一种。

浏览器

在浏览器中，您可以使用 URLSearchParams API ，如下所示：

const params = new URLSearchParams();
params.append('param1', 'value1');
params.append('param2', 'value2');
axios.post('/foo', params);

请注意，不是所有浏览器都支持 URLSearchParams (详见 caniuse.com)，但有一个 polyfill 全都可用(确保填补全局变量).

或者，您可以使用qs库对数据进行编码：

const qs = require('qs');
axios.post('/foo', qs.stringify({ 'bar': 123 }));

或以另一种方式 (ES6),

import qs from 'qs';
const data = { 'bar': 123 };
const options = {
  method: 'POST',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  data: qs.stringify(data),
  url,
};
axios(options);

Node.js

在node.js中，可以使用 querystring 模块，如下所示：

const querystring = require('querystring');
axios.post('http://something.com/', querystring.stringify({ foo: 'bar' }));

你也可以使用 qs 库.

注意

如果您需要对嵌套对象进行字符串化，那么 qs 库是首选，因为querystring方法已经有了解决方案 (https://github.com/nodejs/node-v0.x-archive/issues/1665).

Semver

在axios1.0发布版之前，重大更新将使用新的小版本号发布。例如0.5.1，0.5.4将具有相同的API，但0.6.0将具有重大更新。

Promises

axios 基于本地 ES6 Promise 实现是被支持的. 如果您的环境不支持 ES6 Promises, 您可以使用 polyfill.

TypeScript

axios 包含TypeScript 定义.

import axios from 'axios';
axios.get('/user?ID=12345');

资源

Credits

axios在很大程度上受到 Angular 提供的 [ $http service](https://docs.angularjs.org/api/ng/service/$ http) 服务的启发。最终，axios努力提供一个在Angular外使用的独立的$http-like服务。

License

MIT

axios官方文档——中文版