axios开发指南

axios

版本 v0.19.0

axios 是基于Promise的http库，可运行于浏览器和node客户端。

特征

• 支持 浏览器 发出XMLHttpRequests请求
• 支持 node 发出http请求
• 遵循 Promise Api
• 支持 request、response 拦截器
• 支持转化 request、response (数据)
• 支持 取消 请求
• 自动转化为 JSON 数据
• 客户端支持对 XSRF(跨站请求伪造) 的抵御

浏览器支持

支持	支持	支持	支持	支持	ie8+

ie8，ie9需要先解决浏览器不支持跨域问题，其他浏览器无历史问题不需要担心兼容问题。

安装

npm

$ npm install axios
复制代码

cdn

复制代码

使用

axios使用一般分为两种，直接使用和创建实例后使用。为了保持项目的可扩展、纯粹项目中我们一般采用实例化使用。

直接使用

axios( config ) 做为函数使用

import axios from 'axios'
axios({
  method: 'post',   
  url: '/user/12345',
  data: {                       //'post', 'put', 'patch'方法支持携带data，其他方法不支持
    firstName: 'Fred',
    lastName: 'Flintstone'
  }
}).then(function(response) {
    console.log(response)
}
复制代码

axios 下方法使用

• 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.request与axios(cofing)用法相同
其余7种方法分别代表http的7种请求方法( 'post', 'put', 'patch'方法支持携带data，其他方法不支持 )

axios.get('/user?ID=12345')
  .then(function (response) {
    console.log(response);
  })
复制代码

创建实例使用

var instance = axios.create({
  baseURL: 'https://some-domain.com/api/',   //设置根url
  timeout: 1000,                             //超时时间
  headers: {'X-Custom-Header': 'foobar'}     //请求头
});
复制代码

使用方法与直接使用相同，同样拥有8种方法。

• instance.request( config )
• instance.get( url, config )
• instance.delete( url, config )
• instance.head( url , config )
• instance.options( url , config )
• instance.post( url , data , config )
• instance.put( url , data , config )
• instance.patch( url , data , config )

Concurrency 并发

axios.all(iterable) 
axios.spread(callback)
复制代码

axios.all源码如下，在这里要求参数是一个axios组成的数组

axios.all = function all(promises) {
  return Promise.all(promises);
};
复制代码

axios.spread源码如下,是利用函数式编程需要第二个参数输入一个axios组成的数组

function spread(callback) {
  return function wrap(arr) {
    return callback.apply(null, arr);
  };
};
复制代码

Request Config 请求配置

{
    //`url`是服务器链接，用来请求
    url:'/user',

    //`method`是发起请求时的方法
    method:`get`,

    //`baseURL`如果`url`不是绝对地址，那么将会加在其前面。
    //可以很方便的对相对地址的axios实例设置`baseUrl`。
    baseURL:'http://some-domain.com/api/',

    //`transformRequest`允许请求的数据在发送至服务器之前进行转化。
    //这个只适用于`PUT`,`GET`,`PATCH`方法。
    //数组中的最后一个函数必须返回一个字符串或者一个`ArrayBuffer`,或者`Stream`,`Buffer`实例,`ArrayBuffer`,`FormData`
    //此外你也可能需要设置下headers对象
    transformRequest:[function(data,headers){
        //依自己的需求对请求数据进行处理
        return data;
    }],

    //`transformResponse`允许对返回的数据传入then/catch之前进行处理
    transformResponse:[function(data){
        //依需要对数据进行处理
        return data;
    }],

    //`headers`是自定义的要被发送的信息头
    headers:{'X-Requested-with':'XMLHttpRequest'},

    //`params`是请求连接中的请求参数，必须是一个纯对象，或者URLSearchParams对象
    params:{
        ID:12345
    },
    
    //`paramsSerializer`是一个可选的函数，用来控制和序列化参数
    //例如：（https://ww.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`定义请求的时间，单位是毫秒。
    //如果请求的时间超过这个设定时间，请求将会停止。
    timeout:1000,
    
    //`withCredentials`表明跨跨域请求书否需要证明。
    withCredentials:false //默认值

    //`adapter`适配器，允许自定义处理请求，这会使测试更简单。
    //返回一个promise，并且提供一个有效的相应。（查看[response docs](#response-api)）
    adapter:function(config){
        /*...*/
    },

    //`auth`表明HTTP基础的认证应该被使用，并且提供证书。
    //这个会设置一个`authorization` 头（header），并且覆盖你在header设置的Authorization头信息。
    auth:{
        username:'janedoe',
        password:'s00pers3cret'
    },

    //`responsetype`表明服务器返回的数据类型，这些类型的设置应该是
    //'arraybuffer','blob','document','json','text','stream'
    responsetype:'json',

    //`responseEncoding`表明解析相应的编码方式。
    //**注意**会忽视responseType为stream或者客户端的请求。
    responseEncoding:'utf8'//默认值

    //`xsrfCookieName`时cookie做xsrf会话时的名字。
    xsrfCookieName:'XSRF-TOKEN',//默认值

    //`xsrfHeaderName` 是http头（header）的名字，并且该头携带xsrf的值
    xrsfHeadername:'X-XSRF-TOKEN'，//默认值

    //`onUploadProgress`允许处理上传过程的进程事件
    onUploadProgress: function(progressEvent){
        //本地过程事件发生时想做的事
    },

    //`onDownloadProgress`允许处理下载过程的进程事件
    onDownloadProgress: function(progressEvent){
        //下载过程中想做的事
    },

    //`maxContentLength` 定义http返回内容的最大字节容量
    maxContentLength: 2000,

    //`validateStatus` 定义promise的resolve和reject。
    //http返回状态码，如果`validateStatus`返回true（或者设置成null/undefined），promise将会resolve；其他的promise将reject。
    validateStatus: function(status){
        return status >= 200 && stauts < 300;//默认
    },

    //`maxRedirect`定义重导向到node.js中的最大数量。
    //如果值为0，那么没有redirect。
    maxREdirects:5,//默认值

    //`socketPath`定义一个在node.js中使用的 `UNIX Socket`。
    //例如 `/var/run/docker.sock`发送请求到docker daemon。
    //`socketPath`和`proxy`只可定义其一。
    //如果都定义则只会使用`socketPath`。
    socketPath:null,//默认值

    //`httpAgent` 和 `httpsAgent`当产生一个http或者https请求时分别定义一个自定义的代理，在nodejs中。
    //这个允许设置一些选选个，像是`keepAlive`--这个在默认中是没有开启的。
    httpAgent: new http.Agent({keepAlive:treu}),
    httpsAgent: new https.Agent({keepAlive:true}),

    //`proxy`定义服务器的主机名字和端口号。
    //`auth`表明HTTP基本认证应该跟`proxy`相连接，并且提供证书。
    //这个将设置一个'Proxy-Authorization'头(header)，覆盖原先自定义的。
    proxy:{
        host:127.0.0.1,
        port:9000,
        auth:{
            username:'cdd',
            password:'123456'
        }
    },

    //`cancelTaken` 定义一个取消，能够用来取消请求
    //（查看 下面的Cancellation 的详细部分）
    cancelToken: new CancelToken(function(cancel){
    })
}
复制代码

默认配置

全局配置

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';
复制代码

实例配置

// Set config defaults when creating the instance
var instance = axios.create({
  baseURL: 'https://api.example.com'
});
// Alter defaults after instance has been created
instance.defaults.headers.common['Authorization'] = AUTH_TOKEN;
复制代码

配置优先级

在多处设置配置后，最终配置将合并。优先级如下：

/使用默认库的设置创建一个实例，
//这个实例中，使用的是默认库的timeout设置，默认值是0。
var instance = axios.create();

//覆盖默认库中timeout的默认值
//此时，所有的请求的timeout时间是2.5秒
instance.defaults.timeout = 2500;

//覆盖该次请求中timeout的值，这个值设置的时间更长一些
instance.get('/longRequest',{
    timeout:5000
});
复制代码

Interceptors 拦截器

以在请求或者返回被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);
复制代码

实例中使用拦截器

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 if(error.request){
          //如果是请求时的错误，且没有收到相应
          //`error.request`是一个浏览器的XMLHttpRequest实例，或者node.js的 ClientRequest实例。
          console.log(error.request)
        } 
        else{
            //一些错误是在设置请求时触发的
            console.log('Error',error.message);
        }
        console.log(error.config);
    });
复制代码

取消请求

可以使用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 {
    // 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构造函数传递一个executor function来创建一个cancel token:

var CancelToken = axios.CancelToken;
var cancel;

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

// cancel the request
cancel();
复制代码

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

默认情况下，axios串联js对象为JSON格式。为了发送application/x-wwww-form-urlencoded格式数据， 你可以使用一下的设置。

浏览器中使用 application/x-www-form-urlencoded

浏览器中可以使用 URLSearchParams API 如下:

var params = new URLSearchParams();
params.append('param1', 'value1');
params.append('param2', 'value2');
axios.post('/foo', params);
复制代码

URLSearchParams是es6新的API，兼容需要增加 polyfill

使用qs格式化数据

var qs = require('qs');
axios.post('/foo', qs.stringify({ 'bar': 123 }));
复制代码

Node.js

var querystring = require('querystring');
axios.post('http://something.com/', querystring.stringify({ foo: 'bar' }));
复制代码