资讯专栏INFORMATION COLUMN

axios 中文文档 翻译

verano / 3385人阅读

摘要:返回状态码,如果返回或者设置成,将会其他的将。一些错误是在设置请求时触发的你可以使用设置选项自定义状态码的错误范围。

axios

版本:v0.18.0

0.18.0的版本更新有一段时间了,使用起来跟原先基本没有什么变化。但是增加了一些功能,例如错误处理的辨别,于07-06-2018重新翻译和校验了该翻译,更正了一些错别字和表达不准的地方,但是难免仍有错误,欢迎指出。

由于工作需要,个人也包装了一个简易的跟axios风格一样在小程序中使用的请求函数。方便一些使用类似vue写法框架来开发小程序的人更方便的无缝桥接。
有需要的读者可以观看一下。 传送门

关于Promise的一练习和训练,此处有一个比较好的集合。传送门

正文

基于Promise的http库,适用于浏览器和node.js。

原文

点击查看原文

特色

浏览器端发起XMLHttpRequests请求

node端发起http请求

支持Promise API

拦截请求和返回

转化请求和返回(数据)

取消请求

自动转化json数据

客户端支持抵御XSRF(跨站请求伪造)

浏览器支持
Latest ✔ Latest ✔ Latest ✔ Latest ✔ Latest ✔ 8+ ✔
安装

使用npm:

</>复制代码

  1. $ npm i axios

使用 bower

</>复制代码

  1. $ bower instal axios

使用cdn

</>复制代码

示例

发起一个GET请求

</>复制代码

  1. const axios = require("axios")
  2. //发起一个user请求,参数为给定的ID
  3. axios.get("/user?ID=12345")
  4. .then(function(respone){
  5. console.log(response);
  6. })
  7. .catch(function(error){
  8. console.log(error);
  9. });
  10. //可配置的方式实现上面的代码如下
  11. axios.get("/user",{
  12. params:{
  13. ID:12345
  14. }
  15. }).then(function(response){
  16. console.log(response);
  17. }).catch(function(error){
  18. console.log(error)
  19. });

注意:async/await是ECMAScript2017的语法,ie和一些老旧的浏览器不支持,请小心使用。
(译者话:使用ts的话可以很容易的编译和使用,也不需要任何垫片,目标编译成es5即可)

发起一个POST请求

</>复制代码

  1. axios.post("/user",{
  2. firstName:"friend",
  3. lastName:"Flintstone"
  4. })
  5. .then(function(response){
  6. console.log(response);
  7. })
  8. .catch(function(error){
  9. console.log(error);
  10. });

发起一个多重并发请求

</>复制代码

  1. function getUserAccount(){
  2. return axios.get("/user/12345");
  3. }
  4. function getUserPermissions(){
  5. return axios.get("/user/12345/permissions");
  6. }
  7. axios.all([getUerAccount(),getUserPermissions()])
  8. .then(axios.spread(function(acc,pers){
  9. //两个请求现在都完成
  10. }));

译者话:因为axios.all使用的是类似Primise.all的功能,所以如果其中有一个请求出现了错误那么就会停止请求,所以建议对于单个请求最好附加上处理的catch。

axios API

根据自己需求可以对axios传递一些的设置来生成请求(Request)。

axios(config)

</>复制代码

  1. //发起 POST请求
  2. axios({
  3. method:"post",//方法
  4. url:"/user/12345",//地址
  5. data:{//参数
  6. firstName:"Fred",
  7. lastName:"Flintstone"
  8. }
  9. });

</>复制代码

  1. //通过请求获取远程图片
  2. axios({
  3. method:"get",
  4. url:"http://bit.ly/2mTM3Ny",
  5. responseType:"stream"
  6. })
  7. .then(function(response){
  8. response.data.pipe(fs.createWriteStream("ada_lovelace.jpg"))
  9. })

axios(url[,config])

</>复制代码

  1. //发起一个GET请求
  2. 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方法请求)。

并发 Concurrency

有用的方法

axios.all(iterable)
axios.spread(callback)

创建一个实例(instance)

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

axios.create([config])

</>复制代码

  1. var instance = axios.create({
  2. baseURL:"http://some-domain.com/api/",
  3. timeout:1000,
  4. headers:{"X-Custom-Header":"foobar"}
  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]])

Requeset Config请求设置

以下列出了一些请求时的设置选项。只有url是必须的,如果没有指明method的话,默认的请求方法是GET.

</>复制代码

  1. {
  2. //`url`是服务器链接,用来请求
  3. url:"/user",
  4. //`method`是发起请求时的方法
  5. method:`get`,
  6. //`baseURL`如果`url`不是绝对地址,那么将会加在其前面。
  7. //可以很方便的对相对地址的axios实例设置`baseUrl`。
  8. baseURL:"http://some-domain.com/api/",
  9. //`transformRequest`允许请求的数据在发送至服务器之前进行转化。
  10. //这个只适用于`PUT`,`POST`,`PATCH`方法。
  11. //数组中的最后一个函数必须返回一个字符串或者一个`ArrayBuffer`,或者`Stream`,`Buffer`实例,`ArrayBuffer`,`FormData`
  12. //此外你也可能需要设置下headers对象
  13. transformRequest:[function(data,headers){
  14. //依自己的需求对请求数据进行处理
  15. return data;
  16. }],
  17. //`transformResponse`允许对返回的数据传入then/catch之前进行处理
  18. transformResponse:[function(data){
  19. //依需要对数据进行处理
  20. return data;
  21. }],
  22. //`headers`是自定义的要被发送的信息头
  23. headers:{"X-Requested-with":"XMLHttpRequest"},
  24. //`params`是请求连接中的请求参数,必须是一个纯对象,或者URLSearchParams对象
  25. params:{
  26. ID:12345
  27. },
  28. //`paramsSerializer`是一个可选的函数,用来控制和序列化参数
  29. //例如:(https://ww.npmjs.com/package/qs,http://api.jquery.com/jquery.param/)
  30. paramsSerializer: function(params){
  31. return Qs.stringify(params,{arrayFormat:"brackets"})
  32. },
  33. //`data`是请求时作为请求体的数据
  34. //只适用于应用的"PUT","POST","PATCH",请求方法
  35. //当没有设置`transformRequest`时,必须是以下其中之一的类型(不可重复?):
  36. //-string(字符串),plain object(纯对象),ArrayBuffer,ArrayBufferView,URLSearchParams
  37. //-限浏览器:FormData(表格数据),File(文件数据),Blob
  38. //-限Node:Stream
  39. data:{
  40. firstName:"fred"
  41. },
  42. //`timeout`定义请求的时间,单位是毫秒。
  43. //如果请求的时间超过这个设定时间,请求将会停止。
  44. timeout:1000,
  45. //`withCredentials`表明跨跨域请求书否需要证明。
  46. withCredentials:false //默认值
  47. //`adapter`适配器,允许自定义处理请求,这会使测试更简单。
  48. //返回一个promise,并且提供一个有效的相应。(查看[response docs](#response-api))
  49. adapter:function(config){
  50. /*...*/
  51. },
  52. //`auth`表明HTTP基础的认证应该被使用,并且提供证书。
  53. //这个会设置一个`authorization` 头(header),并且覆盖你在header设置的Authorization头信息。
  54. auth:{
  55. username:"janedoe",
  56. password:"s00pers3cret"
  57. },
  58. //`responsetype`表明服务器返回的数据类型,这些类型的设置应该是
  59. //"arraybuffer","blob","document","json","text",stream"
  60. responsetype:"json",
  61. //`responseEncoding`表明解析相应的编码方式。
  62. //**注意**会忽视responseType为stream或者客户端的请求。
  63. responseEncoding:"utf8"//默认值
  64. //`xsrfCookieName`时cookie做xsrf会话时的名字。
  65. xsrfCookieName:"XSRF-TOKEN",//默认值
  66. //`xsrfHeaderName` 是http头(header)的名字,并且该头携带xsrf的值
  67. xrsfHeadername:"X-XSRF-TOKEN"//默认值
  68. //`onUploadProgress`允许处理上传过程的进程事件
  69. onUploadProgress: function(progressEvent){
  70. //本地过程事件发生时想做的事
  71. },
  72. //`onDownloadProgress`允许处理下载过程的进程事件
  73. onDownloadProgress: function(progressEvent){
  74. //下载过程中想做的事
  75. },
  76. //`maxContentLength` 定义http返回内容的最大字节容量
  77. maxContentLength: 2000,
  78. //`validateStatus` 定义promise的resolve和reject。
  79. //http返回状态码,如果`validateStatus`返回true(或者设置成null/undefined),promise将会resolve;其他的promise将reject。
  80. validateStatus: function(status){
  81. return status >= 200 && stauts < 300;//默认
  82. },
  83. //`maxRedirect`定义重导向到node.js中的最大数量。
  84. //如果值为0,那么没有redirect。
  85. maxREdirects:5,//默认值
  86. //`socketPath`定义一个在node.js中使用的 `UNIX Socket`
  87. //例如 `/var/run/docker.sock`发送请求到docker daemon。
  88. //`socketPath``proxy`只可定义其一。
  89. //如果都定义则只会使用`socketPath`。
  90. socketPath:null,//默认值
  91. //`httpAgent``httpsAgent`当产生一个http或者https请求时分别定义一个自定义的代理,在nodejs中。
  92. //这个允许设置一些选选个,像是`keepAlive`--这个在默认中是没有开启的。
  93. httpAgent: new http.Agent({keepAlive:treu}),
  94. httpsAgent: new https.Agent({keepAlive:true}),
  95. //`proxy`定义服务器的主机名字和端口号。
  96. //`auth`表明HTTP基本认证应该跟`proxy`相连接,并且提供证书。
  97. //这个将设置一个"Proxy-Authorization"头(header),覆盖原先自定义的。
  98. proxy:{
  99. host:127.0.0.1,
  100. port:9000,
  101. auth:{
  102. username:"cdd",
  103. password:"123456"
  104. }
  105. },
  106. //`cancelTaken` 定义一个取消,能够用来取消请求
  107. //(查看 下面的Cancellation 的详细部分)
  108. cancelToken: new CancelToken(function(cancel){
  109. })
  110. }
返回响应概要 Response Schema

一个请求的返回包含以下信息

</>复制代码

  1. {
  2. //`data`是服务器的提供的回复(相对于请求)
  3. data{},
  4. //`status`是服务器返回的http状态码
  5. status:200,
  6. //`statusText`是服务器返回的http状态信息
  7. statusText: "ok",
  8. //`headers`是服务器返回中携带的headers
  9. headers:{},
  10. //`config`是对axios进行的设置,目的是为了请求(request)
  11. config:{}
  12. //`request`是获取当前相应的请求
  13. //它是node.js中最后一次的 ClientRequest的实例(在redirect中)
  14. //或者是在浏览器中的XMLHttpREquest实例
  15. }

使用then时,你会接受到下面的信息:

</>复制代码

  1. axios.get("/user/12345")
  2. .then(function(response){
  3. console.log(response.data);
  4. console.log(response.status);
  5. console.log(response.statusText);
  6. console.log(response.headers);
  7. console.log(response.config);
  8. });

使用catch时,或者传入一个reject callback作为then的第二个参数,那么返回的错误信息将能够被处理。

默认设置(Config Default)

你可以设置一个默认的设置,这设置将在之后的每次请求中生效。

全局默认设置 Global axios defaults

</>复制代码

  1. axios.defaults.baseURL = "https://api.example.com";
  2. axios.defaults.headers.common["Authorization"] = AUTH_TOKEN;
  3. axios.defaults.headers.post["Content-Type"]="application/x-www-form-urlencoded";
实例中自定义默认值 Custom instance default

</>复制代码

  1. //当创建一个实例时进行默认设置
  2. var instance = axios.create({
  3. baseURL:"https://api.example.com"
  4. });
  5. //或者在实例创建之后改变默认值
  6. instance.defaults.headers.common["Authorization"] = AUTH_TOKEN;
设置优先级 Config order of precedence

设置(config)将按照优先顺序合并起来。首先的是在lib/defaults.js中定义的默认设置,其次是defaults实例属性的设置,最后是请求中config参数的设置。越往后面的等级越高,会覆盖前面的设置。
看下面这个例子:

</>复制代码

  1. //使用默认库的设置创建一个实例,
  2. //这个实例中,使用的是默认库的timeout设置,默认值是0。
  3. var instance = axios.create();
  4. //覆盖默认库中timeout的默认值
  5. //此时,所有的请求的timeout时间是2.5秒
  6. instance.defaults.timeout = 2500;
  7. //覆盖该次请求中timeout的值,这个值设置的时间更长一些
  8. instance.get("/longRequest",{
  9. timeout:5000
  10. });
拦截器 interceptors

你可以在请求或者返回then或者catch处理之前对他们进行拦截。

</>复制代码

  1. //添加一个请求拦截器
  2. axios.interceptors.request.use(function(config){
  3. //在请求发送之前做一些事
  4. return config;
  5. },function(error){
  6. //当出现请求错误是做一些事
  7. return Promise.reject(error);
  8. });
  9. //添加一个返回拦截器
  10. axios.interceptors.response.use(function(response){
  11. //对返回的数据进行一些处理
  12. return response;
  13. },function(error){
  14. //对返回的错误进行一些处理
  15. return Promise.reject(error);
  16. });

如果你需要在稍后移除拦截器,你可以

</>复制代码

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

你可以在一个axios实例中使用拦截器

</>复制代码

  1. var instance = axios.create();
  2. instance.interceptors.request.use(function(){/*...*/});
错误处理 Handling Errors

</>复制代码

  1. axios.get("user/12345")
  2. .catch(function(error){
  3. if(error.response){
  4. //存在请求,但是服务器的返回一个状态码
  5. //他们是在2xx之外
  6. console.log(error.response.data);
  7. console.log(error.response.status);
  8. console.log(error.response.headers);
  9. }else if(error.request){
  10. //如果是请求时的错误,且没有收到相应
  11. //`error.request`是一个浏览器的XMLHttpRequest实例,或者node.js的 ClientRequest实例。
  12. console.log(error.request)
  13. }
  14. else{
  15. //一些错误是在设置请求时触发的
  16. console.log("Error",error.message);
  17. }
  18. console.log(error.config);
  19. });

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

</>复制代码

  1. axios.get("user/12345",{
  2. validateStatus:function(status){
  3. return status < 500;//当返回码小于等于500时视为错误
  4. }
  5. });
取消 Cancellation

你可以使用cancel token取消一个请求

</>复制代码

  1. axios的cancel token API是基于已经撤销的**cnacelable promises proposal**提议。

你可以使用CancelToken.source工厂函数创建一个cancel token,如下:

</>复制代码

  1. var CancelToken = axios.CancelToken;
  2. var source = CancelToken.source();
  3. axios.get("/user/12345", {
  4. cancelToken:source.toke
  5. }).catch(function(thrown){
  6. if(axiso.isCancel(thrown)){
  7. console.log("Rquest canceled", thrown.message);
  8. }else{
  9. //handle error
  10. }
  11. });
  12. //取消请求(信息参数设可设置的)
  13. source.cancel("操作被用户取消");

你可以给CancelToken构造函数传递一个executor function来创建一个cancel token:

</>复制代码

  1. var CancelToken = axios.CancelToken;
  2. var source = CancelToken.source()
  3. axios.get("/user/12345",{
  4. cancelToke:source.token
  5. }).catch(function(thrown){
  6. if(axios.isCancel(throw)){
  7. console.log("请求已取消",throw.message)
  8. }else{
  9. //处理错误
  10. }
  11. })
  12. axios.post("/user/2345",{
  13. name:"new name"
  14. },{
  15. cancelToken:source.toke
  16. })
  17. source.cancel("错做已被用户取消!")

你也可以给CancelToke的构造函数传递一个处理函数来生成一个cancel token。

</>复制代码

  1. const CancelToken = axios.CancelToken
  2. let cancel;
  3. acios.get("/user/12345",{
  4. cancelToken:new CancelToken(function excutor(c){
  5. //一个处理函数接受一个cancel函数作为参数
  6. cancel = c
  7. })
  8. })
  9. // 取消请求
  10. cancel()

</>复制代码

  1. 注意:你可以使用同一个cancel token取消多个请求。
使用 application/x-www-form-urlencoded 格式

本人做的简单包装

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

浏览器 Browser

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

</>复制代码

  1. var params = new URLSearchParams();
  2. params.append("param1","value1");
  3. params.append("param2","value2");
  4. axios.post("/foo",params);

注意:URLSearchParams不支持所有的浏览器,但是这里有个垫片
(poly fill)可用(确保垫片在浏览器全局环境中)

其他方法:你可以使用qs库来对数据编码。

</>复制代码

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

或者其他方法(es6)

</>复制代码

  1. import qs from "qs";
  2. const data = {"bar":123};
  3. const options = {
  4. method:"POST",
  5. headers:{
  6. "content-type":"application/x-www-from-urlencoded"
  7. },
  8. data:qs.stringify(data),
  9. url
  10. }
  11. axios(options)
兼容Semver

当axios放出1.0版本时,一些不兼容的更改将会放在新的版本中。例如0.5.10.5.4有相同的api,但是0.6.0会有不兼容的变化。

译者:小知识
在npn的版本习惯中,版本使用的习惯是a.b.c,其中c的变化是一些bug的修复,b是一些功能的添加,a是大的版本的变化,会出现不兼容的情况。

Node.js

在nodejs中,你可以如下使用querystring:

</>复制代码

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

你同样可以使用qs库。

promises

axios 基于原生的ES6 Promise 实现。如果环境不支持请使用垫片.

TypeScript

axios 包含TypeScript定义

</>复制代码

  1. import axios from "axios"
  2. axios.get("/user?ID=12345")

文章版权归作者所有,未经允许请勿转载,若此文章存在违规行为,您可以联系管理员删除。

转载请注明本文地址:https://www.ucloud.cn/yun/81727.html

相关文章

  • 前端学习资源汇总

    摘要:建立该仓库的目的主要是整理收集学习资源,统一管理,方便随时查找。目前整合的学习资源只是前端方向的,可能会存在漏缺比较好的资源,需要慢慢的完善它,欢迎在该上补充资源或者提供宝贵的建议。 说明 平时的学习资源都比较的凌乱,看到好的资源都是直接收藏在浏览器的收藏夹中,这样其实并不方便,整理在云笔记上,也不方便查看修改记录,索性就整理在 github 上并开源出来,希望帮助大家能够更快的找到需...

    SnaiLiu 评论0 收藏0
  • axios使用心得总结

    摘要:最近项目中使用也遇到了一些问题,就借此机会总结一下,如有错误,还请不吝指正。而在使用时对应的传参使用的是,是作为请求体发送的,同样使用这种形式的还有等请求方式。层在环境中可以使用。 Axios是一个基于Promise的 HTTP 库,可以用在浏览器和node.js 中,因为尤大大的推荐,axios也变得越来越流行。最近项目中使用axios也遇到了一些问题,就借此机会总结一下,如有错误,...

    Lowky 评论0 收藏0
  • React Hooks实现异步请求实例—useReducer、useContext和useEffec

    摘要:本文是学习了年新鲜出炉的提案之后,针对异步请求数据写的一个案例。注意,本文假设了你已经初步了解的含义了,如果不了解还请移步官方文档。但不要忘记和上下文对象可以看做是写法的以及三个钩子函数的组合。 本文是学习了2018年新鲜出炉的React Hooks提案之后,针对异步请求数据写的一个案例。注意,本文假设了:1.你已经初步了解hooks的含义了,如果不了解还请移步官方文档。(其实有过翻译...

    Code4App 评论0 收藏0

发表评论

0条评论

最新活动
阅读需要支付1元查看
<