版本:v0.18.0css
0.18.0的版本更新有一段时间了,使用起来跟原先基本没有什么变化。可是增长了一些功能,例如错误处理的辨别,于07-06-2018
从新翻译和校验了该翻译,更正了一些错别字和表达不许的地方,可是不免仍有错误,欢迎指出。vue
因为工做须要,我的也包装了一个简易的跟axios风格同样在小程序中使用的请求函数。方便一些使用相似vue写法框架来开发小程序的人更方便的无缝桥接。
有须要的读者能够观看一下。 传送门node
关于Promise
的一练习和训练,此处有一个比较好的集合。传送门jquery
基于Promise的http库,适用于浏览器和node.js。ios
点击查看原文git
Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | 8+ ✔ |
使用npm:es6
$ npm i axios
使用 bowergithub
$ bower instal axios
使用cdnchrome
<!--国内bootCDN--> <script src="https://cdn.bootcss.com/axios/0.18.0/axios.min.js"></script>
发起一个GET
请求docker
const axios = require('axios') //发起一个user请求,参数为给定的ID axios.get('/user?ID=12345') .then(function(respone){ 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) });
注意:async/await
是ECMAScript2017的语法,ie和一些老旧的浏览器不支持,请当心使用。
(译者话:使用ts的话能够很容易的编译和使用,也不须要任何垫片,目标编译成es5便可)
发起一个POST
请求
axios.post('/user',{ firstName:'friend', 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([getUerAccount(),getUserPermissions()]) .then(axios.spread(function(acc,pers){ //两个请求如今都完成 }));
译者话:由于axios.all
使用的是相似Primise.all
的功能,因此若是其中有一个请求出现了错误那么就会中止请求,因此建议对于单个请求最好附加上处理的catch。
根据本身需求能够对axios传递一些的设置来生成请求(Request)。
axios(config)
//发起 POST请求 axios({ method:'post',//方法 url:'/user/12345',//地址 data:{//参数 firstName:'Fred', lastName:'Flintstone' } });
//经过请求获取远程图片 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提供了全部请求方法的别名支持
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
,method
,以及data
属性没必要在config中明确指定(如上面示例的post方法请求)。
有用的方法
axios.all(iterable)
axios.spread(callback)
你可使用自定义设置建立一个新的实例
axios.create([config])
var instance = axios.create({ baseURL:'http://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]])
如下列出了一些请求时的设置选项。只有url
是必须的,若是没有指明method
的话,默认的请求方法是GET
.
{ //`url`是服务器连接,用来请求 url:'/user', //`method`是发起请求时的方法 method:`get`, //`baseURL`若是`url`不是绝对地址,那么将会加在其前面。 //能够很方便的对相对地址的axios实例设置`baseUrl`。 baseURL:'http://some-domain.com/api/', //`transformRequest`容许请求的数据在发送至服务器以前进行转化。 //这个只适用于`PUT`,`POST`,`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){ }) }
一个请求的返回包含如下信息
{ //`data`是服务器的提供的回复(相对于请求) data{}, //`status`是服务器返回的http状态码 status:200, //`statusText`是服务器返回的http状态信息 statusText: 'ok', //`headers`是服务器返回中携带的headers headers:{}, //`config`是对axios进行的设置,目的是为了请求(request) config:{} //`request`是获取当前相应的请求 //它是node.js中最后一次的 ClientRequest的实例(在redirect中) //或者是在浏览器中的XMLHttpREquest实例 }
使用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
时,或者传入一个reject callback
做为then
的第二个参数,那么返回的错误信息将可以被处理。
你能够设置一个默认的设置,这设置将在以后的每次请求中生效。
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;
设置(config)将按照优先顺序合并起来。首先的是在lib/defaults.js
中定义的默认设置,其次是defaults
实例属性的设置,最后是请求中config
参数的设置。越日后面的等级越高,会覆盖前面的设置。
看下面这个例子:
//使用默认库的设置建立一个实例, //这个实例中,使用的是默认库的timeout设置,默认值是0。 var instance = axios.create(); //覆盖默认库中timeout的默认值 //此时,全部的请求的timeout时间是2.5秒 instance.defaults.timeout = 2500; //覆盖该次请求中timeout的值,这个值设置的时间更长一些 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 if(error.request){ //若是是请求时的错误,且没有收到相应 //`error.request`是一个浏览器的XMLHttpRequest实例,或者node.js的 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时视为错误 } });
你可使用cancel token取消一个请求
axios的cancel token API是基于已经撤销的**cnacelable promises proposal**提议。
你可使用CancelToken.source
工厂函数建立一个cancel token,以下:
var CancelToken = axios.CancelToken; var source = CancelToken.source(); axios.get('/user/12345', { cancelToken:source.toke }).catch(function(thrown){ if(axiso.isCancel(thrown)){ console.log('Rquest canceled', thrown.message); }else{ //handle error } }); //取消请求(信息参数设可设置的) source.cancel("操做被用户取消");
你能够给CancelToken
构造函数传递一个executor function来建立一个cancel token:
var CancelToken = axios.CancelToken; var source = CancelToken.source() axios.get('/user/12345',{ cancelToke:source.token }).catch(function(thrown){ if(axios.isCancel(throw)){ console.log('请求已取消',throw.message) }else{ //处理错误 } }) axios.post('/user/2345',{ name:'new name' },{ cancelToken:source.toke }) source.cancel('错作已被用户取消!')
你也能够给CancelToke
的构造函数传递一个处理函数来生成一个cancel token。
const CancelToken = axios.CancelToken let cancel; acios.get('/user/12345',{ cancelToken:new CancelToken(function excutor(c){ //一个处理函数接受一个cancel函数做为参数 cancel = c }) }) // 取消请求 cancel()
注意:你可使用同一个cancel token取消多个请求。
默认状况下,axios串联js对象为JSON
格式。为了发送application/x-wwww-form-urlencoded
格式数据,
你可使用一下的设置。
在浏览器中你能够以下使用URLSearchParams
API:
var params = new URLSearchParams(); params.append('param1','value1'); params.append('param2','value2'); axios.post('/foo',params);
注意:URLSearchParams
不支持全部的浏览器,可是这里有个垫片
(poly fill)可用(确保垫片在浏览器全局环境中)
其余方法:你可使用qs
库来对数据编码。
var 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-from-urlencoded' }, data:qs.stringify(data), url } axios(options)
当axios放出1.0
版本时,一些不兼容的更改将会放在新的版本中。例如0.5.1
和0.5.4
有相同的api,可是0.6.0
会有不兼容的变化。
译者:小知识
在npn的版本习惯中,版本使用的习惯是a.b.c,其中c的变化是一些bug的修复,b是一些功能的添加,a是大的版本的变化,会出现不兼容的状况。
在nodejs中,你能够以下使用querystring
:
var querystring = require('querystring'); axios.post('http://something.com/', querystring.stringify({foo:'bar'}));
你一样可使用qs
库。
axios 基于原生的ES6 Promise 实现。若是环境不支持请使用垫片.
axios 包含TypeScript
定义
import axios from 'axios' axios.get('/user?ID=12345')