前端框架 ajax : axios API

心已赠人 2022-03-24 16:38 243阅读 0赞

# axios #

**axios受到[Angular][]提供的[$ http服务的][http]启发。最终，axios努力提供一种类似于独立的服务，以便在Angular之外使用。**

[![npm版本][npm]][npm_npm] [![建立状态][68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6178696f732f6178696f732e7376673f7374796c653d666c61742d737175617265]][68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6178696f732f6178696f732e7376673f7374796c653d666c61742d737175617265 1] [![代码覆盖率][68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f6d7a61627269736b69652f6178696f732e7376673f7374796c653d666c61742d737175617265]][68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f6d7a61627269736b69652f6178696f732e7376673f7374796c653d666c61742d737175617265 1] [![安装尺寸][68747470733a2f2f7061636b61676570686f6269612e6e6f772e73682f62616467653f703d6178696f73]][68747470733a2f2f7061636b61676570686f6269612e6e6f772e73682f62616467653f703d6178696f73 1] [![npm下载][npm 1]][npm_npm 1] [![gitter聊天][gitter]][gitter_gitter] [![代码助手][68747470733a2f2f7777772e636f64657472696167652e636f6d2f6178696f732f6178696f732f6261646765732f75736572732e737667]][68747470733a2f2f7777772e636f64657472696167652e636f6d2f6178696f732f6178696f732f6261646765732f75736572732e737667 1]

基于Promise的HTTP客户端，用于浏览器和node.js

## 特征 ##

*  做[的XMLHttpRequest][XMLHttpRequest]从浏览器
 *  让[HTTP][]从node.js的请求
 *  支持[Promise][] API
 *  拦截请求和响应
 *  转换请求和响应数据
 *  取消请求
 *  自动转换JSON数据
 *  客户端支持防范[XSRF][]

## 浏览器支持 ##

[![浏览器矩阵][68747470733a2f2f73617563656c6162732e636f6d2f6f70656e5f73617563652f6275696c645f6d61747269782f6178696f732e737667]][68747470733a2f2f73617563656c6162732e636f6d2f6f70656e5f73617563652f6275696c645f6d61747269782f6178696f732e737667 1]

## 安装 ##

**使用npm：**

$ npm install axios

**使用bower：**

$ bower install axios

**使用cdn：**

## 例 ##

**执行`GET`请求**

> **注意：** `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);
      });

**执行多个并发请求**

## 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请求（默认方法）
    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]]）

**注意 ：****使用别名方法时`url`，不需要在config中指定`method`和`data`属性。**

### **并发** ###

**Helper函数用于处理并发请求。**

**axios.all（迭代器）**

**axios.spread（回调）**

### **创建实例** ###

**您可以使用自定义配置创建新的axios实例。**

**axios.create(\[config\])**

const instance = axios.create({
      baseURL: 'https://some-domain.com/api/',
      timeout: 1000,
      headers: {'X-Custom-Header': 'foobar'}
    });

### 实例方法 ###

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

iaxios#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]]）

**Request （请求）配置**

**这些是用于发出请求的可用配置选项。只`url`需要。`GET`如果`method`未指定，请求将默认为if 。**

{
      // `url`是将用于请求 url 的服务器URL 
      url: '/user',
    
      // `method` 方法是在发出请求时使用的请求方法
      method: 'get', // 默认get请求
    
      //`baseURL`将被添加到`url`，除非`url`是绝对的。
      //为axios实例设置`baseURL`可以方便地将相对URL
      //传递给该实例的方法。
      baseURL: 'https://some-domain.com/api/',
    
      // `transformRequest`允许在将请求数据发送到服务器之前对其进行更改
      //这仅适用于请求方法'PUT'，'POST'和'PATCH' 
      //数组中的最后一个函数必须返回一个字符串或Buffer，ArrayBuffer，
      // FormData或Stream的实例//您可以修改headers对象。
      transformRequest: [function (data, headers) {
        //做任何你想要转换数据
    
        return data;
      }],
    
     // `transformResponse`允许在之前更改响应数据它被传递给then / catch 
      transformResponse: [function (data) {
        //做任何你想要转换数据
    
        return data;
      }],
    
      // `headers` 要发送自定义头信息
      headers: {'X-Requested-With': 'XMLHttpRequest'},
    
      // `params`是与请求一起发送的URL参数
      //必须是普通对象或URLSearchParams对象 
      params: {
        ID: 12345
      },
    
      // `paramsSerializer`负责串行化的可选功能`params` 
      //（例如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`，则必须是以下类型之一：
      //- 字符串，普通对象，ArrayBuffer，ArrayBufferView，URLSearchParams 
      // - 仅限浏览器：FormData，File，Blob 
      // - 仅限节点：流，缓冲区 
      data: {
        firstName: 'Fred'
      },
    
      // `timeout`指定的数量请求超时前的毫秒数。
      //如果请求的时间超过“超时”，请求将被中止。
      timeout: 1000, // 默认是 `0` (无超时)
    
      // `withCredentials`指示跨站点是否访问控制请求
      //应该使用证书进行
      withCredentials: false, // 默认
    
      // `adapter`允许自定义处理请求，使测试更容易。
      //返回一个promise并提供一个有效的响应（参见lib / adapters / README.md）。
      adapter: function (config) {
        /* ... */
      },
    
      // `auth`表示应该使用HTTP Basic auth，并提供凭据。
      //这将设置一个'Authorization`头，覆盖任何现有
      // `Authorization`定制你已经使用`headers`设置头。
      auth: {
        username: 'janedoe',
        password: 's00pers3cret'
      },
    
      // `responseType`表示服务器将响应的数据类型
      //选项是 'arraybuffer', 'blob', 'document', 'json', 'text', 'stream'
      responseType: 'json', // 默认
    
      // `responseEncoding`表示编码以用于解码响应
      //注：忽略用于`的responseType`的'stream' 或客户端的请求
      responseEncoding: 'utf8', // 默认
    
      // `xsrfCookieName`是cookie的名称用作xsrf令牌（token）的值
      xsrfCookieName: 'XSRF-TOKEN', // default
    
      // `xsrfHeaderName` 带有xsrf令牌值的http header的名称
      xsrfHeaderName: 'X-XSRF-TOKEN', // default
    
      //  `onUploadProgress`允许处理上传的进度事件
      onUploadProgress: function (progressEvent) {
        //使用本机进度事件执行任何操作 
      },
    
      // `onDownloadProgress`允许处理下载的进度事件
      onDownloadProgress: function (progressEvent) {
        //使用本机进度事件执行任何操作 
      },
    
      / `maxContentLength`定义http响应内容的最大大小（以字节为单位）
      maxContentLength: 2000,
    
      // `validateStatus`定义是否解析或拒绝给定
      // HTTP响应状态代码的承诺。如果`validateStatus`返回`true`（或设置为`null` 或`undefined`），
      //则将解决promise; 否则，承诺将是被拒绝。
      validateStatus: function (status) {
        return status >= 200 && status < 300; // default
      },
    
      // `maxRedirects`定义node.js中要遵循的最大重定向数。
      //如果设置为0，则不会遵循重定向。
      maxRedirects: 5, // default
    
      // `socketPath`定义要在node.js中使用的UNIX套接字。
      //例如'/var/run/docker.sock'将请求发送到docker守护程序。
      //只能指定`socketPath`或`proxy`。
      //如果同时指定了两者，则使用`socketPath`。
      socketPath: null, // default
    
      // `httpAgent`和`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`标头，覆盖任何现有的标头
      //使用`headers`设置的`Proxy-Authorization`自定义标头。
      proxy: {
        host: '127.0.0.1',
        port: 9000,
        auth: {
          username: 'mikeymike',
          password: 'rapunz3l'
        }
      },
    
      // `cancelToken`指定可用于取消请求的取消令牌
      //（有关详细信息，请参阅下面的取消部分） 
      cancelToken: new CancelToken(function (cancel) {
      })
    }

## 响应模式 ##

**请求的响应包含以下信息。**

{
      // `data`是服务器数据提供的响应 
      data: {},
    
      // `status`是来自服务器响应 状态的HTTP状态代码：200，
      status: 200,
    
      // `statusText`是来自的状态消息服务器响应 
      statusText: 'OK',
    
      // `headers` 服务器用所有标题名响应的标题都是小写的
      headers: {},
    
      // `config`是为`axios`提供的配置请求
      config: {},
    
      // `request` is the request that generated this response
      //`request`是生成此响应的请求
      //它是node.js中的最后一个ClientRequest实例（在重定向中）
      //和一个浏览器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`或传递[拒绝回调][Link 1]作为第二个参数时`then`，响应将通过`error`对象可用，如[处理错误][Link 2]部分中所述。**

## **配置默认值** ##

**您可以指定将应用于每个请求的配置默认值。**

**全局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 /][lib] defaults.js中找到的库默认[值][lib]，然后`defaults`是实例的属性，最后`config`是请求的参数。后者优先于前者。这是一个例子。**

//使用库提供的配置默认值创建实例
    //此时超时配置值为“0”，这是库默认值
    const 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);
      });

**如果您可能需要稍后删除拦截器，则可以。**

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`config选项定义自定义HTTP状态代码错误范围。**

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

## 消除 ##

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

> axios取消令牌API基于撤销的[可取消承诺提议][Link 3]。

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

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

const CancelToken = axios.CancelToken;
    let cancel;
    
    axios.get('/user/12345', {
      cancelToken: new CancelToken(function executor(c) {
        // An executor function receives a cancel function as a parameter
        cancel = c;
      })
    });
    
    // 取消请求
    cancel();

> 注意：您可以使用相同的取消令牌取消多个请求。

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

**默认情况下，axios将JavaScript对象序列化为`JSON`。要以`application/x-www-form-urlencoded`格式发送数据，您可以使用以下选项之一。**

### 浏览器 ###

**在浏览器中，您可以[`URLSearchParams`][URLSearchParams]按如下方式使用API：**

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

> 请注意，`URLSearchParams`并非所有的浏览器（见支持[caniuse.com][]），但有一个[填充工具][Link 4]可用（确保填充工具全球环境）。

**或者，您可以使用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`][querystring]按如下方式使用该模块：**

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

**您也可以使用该qs库。**

**TypeScript**

** axios包括[TypeScript][]定义**

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

[Angular]: https://angularjs.org/
[http]: https://docs.angularjs.org/api/ng/service/$http
[npm]: https://camo.githubusercontent.com/9f600e10007ac86da6a8b90c16ca1e9504901730/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f6178696f732e7376673f7374796c653d666c61742d737175617265
[npm_npm]: https://www.npmjs.org/package/axios
[68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6178696f732f6178696f732e7376673f7374796c653d666c61742d737175617265]: https://camo.githubusercontent.com/5405d8b8a0112b4fbd790a91d2f8c161c8a133f5/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6178696f732f6178696f732e7376673f7374796c653d666c61742d737175617265
[68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6178696f732f6178696f732e7376673f7374796c653d666c61742d737175617265 1]: https://travis-ci.org/axios/axios
[68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f6d7a61627269736b69652f6178696f732e7376673f7374796c653d666c61742d737175617265]: https://camo.githubusercontent.com/04dcbd38251ebdea54b541442efb9dd48cfb297b/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f6d7a61627269736b69652f6178696f732e7376673f7374796c653d666c61742d737175617265
[68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f6d7a61627269736b69652f6178696f732e7376673f7374796c653d666c61742d737175617265 1]: https://coveralls.io/r/mzabriskie/axios
[68747470733a2f2f7061636b61676570686f6269612e6e6f772e73682f62616467653f703d6178696f73]: https://camo.githubusercontent.com/560b1ca3de5f51e2ac99eec30cc0c10d2433e3c6/68747470733a2f2f7061636b61676570686f6269612e6e6f772e73682f62616467653f703d6178696f73
[68747470733a2f2f7061636b61676570686f6269612e6e6f772e73682f62616467653f703d6178696f73 1]: https://packagephobia.now.sh/result?p=axios
[npm 1]: https://camo.githubusercontent.com/0466334190cd8c680cfa27ff0ace874fae1157e4/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f646d2f6178696f732e7376673f7374796c653d666c61742d737175617265
[npm_npm 1]: http://npm-stat.com/charts.html?package=axios
[gitter]: https://camo.githubusercontent.com/013650d23d9eb743d6169b87e2b1b9741709f699/68747470733a2f2f696d672e736869656c64732e696f2f6769747465722f726f6f6d2f6d7a61627269736b69652f6178696f732e7376673f7374796c653d666c61742d737175617265
[gitter_gitter]: https://gitter.im/mzabriskie/axios
[68747470733a2f2f7777772e636f64657472696167652e636f6d2f6178696f732f6178696f732f6261646765732f75736572732e737667]: https://camo.githubusercontent.com/30b3f0bb7cd9df884cecc1c2a3675aead6870a2f/68747470733a2f2f7777772e636f64657472696167652e636f6d2f6178696f732f6178696f732f6261646765732f75736572732e737667
[68747470733a2f2f7777772e636f64657472696167652e636f6d2f6178696f732f6178696f732f6261646765732f75736572732e737667 1]: https://www.codetriage.com/axios/axios
[XMLHttpRequest]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
[HTTP]: http://nodejs.org/api/http.html
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
[XSRF]: http://en.wikipedia.org/wiki/Cross-site_request_forgery
[68747470733a2f2f73617563656c6162732e636f6d2f6f70656e5f73617563652f6275696c645f6d61747269782f6178696f732e737667]: https://camo.githubusercontent.com/626c46cfd86214001b4143cda5d0ef27a25bd69f/68747470733a2f2f73617563656c6162732e636f6d2f6f70656e5f73617563652f6275696c645f6d61747269782f6178696f732e737667
[68747470733a2f2f73617563656c6162732e636f6d2f6f70656e5f73617563652f6275696c645f6d61747269782f6178696f732e737667 1]: https://saucelabs.com/u/axios
[Link 1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then
[Link 2]: https://github.com/axios/axios#handling-errors
[lib]: https://github.com/axios/axios/blob/master/lib/defaults.js#L28
[Link 3]: https://github.com/tc39/proposal-cancelable-promises
[URLSearchParams]: https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
[caniuse.com]: http://www.caniuse.com/#feat=urlsearchparams
[Link 4]: https://github.com/WebReflection/url-search-params
[querystring]: https://nodejs.org/api/querystring.html
[TypeScript]: http://typescriptlang.org/