axios官方文档——中文版_axios官网文档

原文地址：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

浏览器兼容性

安装

用 npm:

$ npm install axios
1

用 bower:

$ bower install axios
1

用 cdn:

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

样例

执行一个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);
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

注意: 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);
  });
1
2
3
4
5
6
7
8
9
10

执行多个并发请求

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) {
    // 两个请求现已完成
  }));
1
2
3
4
5
6
7
8
9
10
11
12

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'))
  });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

axios(url[, config])

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

请求方法别名

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

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'}
});
1
2
3
4
5

实例方法

下面列出了可用的实例方法，指定的配置将与实例配置合并。

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) {
  })
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

响应模式

请求的响应包含以下信息

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

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

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

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

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

  // `request` 生成这个响应的请求
  // 这是node.js中最后的客户端请求实例(重定向)和浏览器XMLHttpRequest实例
  request: {}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

使用 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);
  });
1
2
3
4
5
6
7
8

当使用 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';
1
2
3

自定义实例默认值

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

// 实例创建后改变默认配置
instance.defaults.headers.common['Authorization'] = AUTH_TOKEN;
1
2
3
4
5
6
7

配置优先级顺序

配置将按优先顺序改变，顺序是 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
});
1
2
3
4
5
6
7
8
9
10
11
12

拦截器

你可以拦截请求或者响应在他们被 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);
  });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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

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

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

const instance = axios.create();
instance.interceptors.request.use(function () {/*...*/});
1
2

处理错误

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);
  });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

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

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

消除

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

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.');
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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

const CancelToken = axios.CancelToken;
let cancel;

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

// cancel the request
cancel();
1
2
3
4
5
6
7
8
9
10
11
12

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

使用 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);
1
2
3
4

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

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

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

或以另一种方式 (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);
1
2
3
4
5
6
7
8
9

Node.js

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

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

你也可以使用 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');
1
2

资源

• 更新日志
• 升级指南
• 生态系统
• 贡献指南
• 行为守则

Credits

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

License

MIT