axios官方文档翻译成中文文档

axios 文档翻译

大家好，我是梅巴哥~

正在用react写一些项目，但是很多需要用到的知识，没有合适的中文文档可以查看和学习。

于是就有了自己翻译官方文档的想法。

我英语水平一般，很多单词不认识，都是靠百度和搜集相关资料查到的。如有错误，欢迎在评论里批评指正。希望这篇文档对大家在axios方面的学习，能有所帮助。

补充： 我翻译都发在博客了，竟然在搜react-axios时，又找到了一个中文文档。大家也可以直接看这个。

1，概述

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

特点：

• 从浏览器中创建 XMLHttpRequests
• 从 node.js 创建 http请求
• 支持promise API
• 拦截请求和响应
• 转换请求和响应数据
• 取消请求
• 自动转换json数据
• 客户端支持抵御XSRF（跨站请求伪造）

2，安装

用npm：

​ npm install axios

用bower：

​ bower install axios

用cdn：

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

用ES6的import引入：

​ import axios from 'axios'

3，示例

• 执行一个GET请求：

const axios = require('axios')

// 给用户创建一个带有id的请求
axios.get('/user?ID=12345')
	.then(function (res) {
    
    
          // 处理成功
          console.log(res)
          })
     .catch(function (err) {
    
    
            // 处理出错
            console.log(err)
            })

上面的代码还可以这样写，这种写法是带有配置属性的：

axios.get('/user', {
    
    
    params: {
    
    
        ID: 12345
    }
})
.then(function (res) {
    
    
      console.log(res)
      })
.catch(function (err) {
    
    
       console.log(err)
       })

• 执行一个POST请求：

axios.post('/user', {
    
    
    firstName: '迪丽',
    lastName: '热巴'
})
.then(function (res) {
    
    
      console.log(res)
      })
.catch(function (err) {
    
    
       console.log(err)
       })

• 同时执行多个请求：

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) {
    
    
    // 两个请求都完成了
}))

4， axios API

可以通过向 axios 传递相关配置来创建请求

axios(config)

// 发送一个POST请求
axios({
    
    
    method: 'post',
    url: '/user/12345',
    data: {
    
    
        firstName: '迪丽',
        lastName: '热巴'
    }
})

// 发送GET请求获取远程图片
const axios = require('axios');
const fs = require('fs')

axios({
    
    
    method: 'get',
    // 图片的url
    url:  'https://bkimg.cdn.bcebos.com/pic/aec379310a55b319aea21ada4aa98226cefc17c1?x-bce-process=image/resize,m_lfit,h_452,limit_1',
    responseType: 'stream'
})
.then(function (res) {
    
    
    // 获取响应结果，并生成一个jpg文件
      res.data.pipe(fs.createWriteStream('dilireba.jpg'))
      })

在代码目录下生成一个dilireba.jpg照片文件：

双击打开就可以看到图片内容：

axios(url [, config])

// 发送一个GET请求 （默认方法）
// 为啥是默认的？可以查看第9条的请求配置
axios('/user/12345')

5，请求方法的别名

为方便起见，为所有支持的请求方法提供了别名：

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

*注意：

在使用这些别名方法时，url , method, 和 data 属性不需要在配置中专门指定。

6, Concurrency 并发

处理并发的助手函数：

axios.all(iterable)

axios.spread(callback)

提示：回看第三点给出的并发的例子里，有这两个助手函数的应用示例。

7，创建axios实例

创建一个新的带有自定义配置的axios：

axios.create([config])

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

8，实例方法

可用的实例方法展示如下，指定的配置将与实例配置合并：

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])

9，请求配置

以下示例里 ，都是发送请求时可用的配置选项。

这里 只有url是必须要写的。如果没有指定的方法，请求将会默认以GET形式发送。

(在第4条的最后有默认get方法举例.)

{
    
    
    	// url 是用于请求的服务器URL
    url: '/user',
        // method 是用于创建请求时的请求方法
    method: 'get', //默认是get
        // baseURL将会被加在url前面，除非url是绝对的或者完整的地址
        //它可以很方便的为一个传递相对路径给axios实例的方法设置一个baseURL
    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是一个管理序列化参数的可选函数
    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: '迪丽热巴'
    },
        // timeout用于指定请求超时的毫秒数
        // 如果请求时间超过了指定的毫秒数，就会终止请求
    timeout: 1000, //默认是0（没有请求超时的时间）
        // withCredentials表示跨域请求时是否需要凭证
    withCredentials: false, //默认不需要
        // adapter允许自定义处理可以让测试更简单的请求
        // 返回一个promise并提供一个有效的响应
    adapter: function (config) {
    
    
        
    },
        // auth表示需要使用HTTP基础验证，并提供证明，比如账户密码
        // 这将设置一个Authorization请求头，重写现有的任意使用 `headers` 设置
        // 的自定义 `Authorization`头
    auth: {
    
    
        username: '小明',
        password: 'hahh123'
    },
        // responseType表示服务端将会以'arraybuffer', 'blob', 'document',
        // 'json', 'text', 'stream'中的哪种数据类型来响应
    responseType: 'json', // 默认是json
        // responseEncoding表示响应的编码形式
        // 注意：已忽略stream响应类型或客户端请求
    responseEncoding: 'utf8',
        // xsrfCookieName是用作xsrf值的cookie名称
    xsrfCookieName:  'XSRF-TOKEN', //默认的
        // xsrfHeaderName是用作xsrf值的请求头名称
    xsrfHeaderName: 'X-XSRF-TOKEN', // 默认的
        // onUploadProgress允许处理上传进度事件
    onUploadProgress: function (progressEvent) {
    
    
        // 对原生进度事件进行处理
    },
        // onDownloadProgress允许处理下载进度事件
    onDownloadProgress: function (progressEvent) {
    
    
        // 对原生下载事件进行处理
    },
        // maxContentLength定义了http响应内容的最大字节数
    maxContentLength: 2000,
        // validateStatus定义了对于一个给定的HTTP响应状态码，是resolve还是reject
        // 如果validateStatus返回true或null或undefined，就会
        // 显示resolve。 反之，就会显示reject。
    validateStatus: function (status) {
    
    
    	return status >= 200 && status < 300; // 默认的
  	},
        // maxRedirects定义了follow的最大重定向数量。
    maxRedirects: 5, //默认是5
        // socketPath定义了在node.js中使用的UNIX接口
    socketPath: null, // 默认为null
        // httpAgent和httpsAgent定义了在node.js中，用http和https请求时各自的
        // 自定义代理。
    httpAgent: new http.Agent({
    
     keepAlive: true }),
    httpsAgent: new https.Agent({
    
     keepAlive: true }),
        // proxy定义代理服务器的主机名称和端口
        // auth表示 HTTP 基础验证应当用于连接代理，并提供凭据
    proxy: {
    
    
    	host: '127.0.0.1',
    	port: 9000,
    	auth: {
    
    
     		username: 'mikeymike',
      		password: 'rapunz3l'
    	}
  	},
        // cancelToken 定义了可以用来取消请求的cancel token
    cancelToken: new CancelToken(function (cancel) {
    
    
  	})
}

10， Response Schema 响应模式

对于一个包含如下信息的请求给出响应：

{
    
    
    	// data是服务端提供的响应数据
    data: {
    
    },
        // status是从服务端响应中得到的HTTP状态码
    status: 200,
        // statusText是从服务端响应中得到的HTTP状态信息
    statusText: 'OK',
        // headers是服务器响应的头
    headers: {
    
    },
        // config是为请求提供给axios的配置
    config: {
    
    },
        // request就是引起这次响应的请求
    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，或者通过一个拒绝服务的回调函数，你就会收到一个抛出错误的对象，来解释错误出现在哪里。

11，Config Defaults 默认配置

你给每个用到的请求设置指定的默认配置。

• Global axios defaults 全局默认配置

  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';
  
  

• Custom instance defaults自定义实例的默认配置

  // 创建实例时，设置默认配置
  const instance = axios.create({
        
        
    baseURL: 'https://api.example.com'
  });
  
  // 创建实例后，修改默认配置
  instance.defaults.headers.common['Authorization'] = AUTH_TOKEN;
  
  

• Config order of precedence配置的优先级顺序

  配置会以一个优先顺序进行合并。这个顺序是：在 lib/defaults.js 找到的库的默认值，然后是实例的 defaults 属性，最后是请求的 config 参数。后者将优先于前者。示例如下：

  // 使用由库提供的配置的默认值来创建实例
  // 此时超时配置的默认值是 `0`
  var instance = axios.create();
  
  // 覆写库的超时默认值
  // 现在，在超时前，所有请求都会等待 2.5 秒
  instance.defaults.timeout = 2500;
  
  // 为已知需要花费很长时间的请求覆写超时设置
  instance.get('/longRequest', {
        
        
    timeout: 5000
  });
  

12，Interceptors 拦截器

在请求或响应被then或catch处理前，你可以拦截这些请求或响应。

// 添加一个请求拦截器
axios.interceptors.request.use(function (config) {
    
    
   // 在发送请求前做一些事情
   return config
 }, function (err) {
    
    
    return Promise.reject(err)
})

// 添加一个响应拦截器
axios.interceptors.response.use(function (res) {
    
    
    return res
}, function (err) {
    
    
    return Promise.reject(err)
})

如果你需要移除一个拦截器，

const myInterceptor = axios.interceptors.request.use(function () {
    
    ...})
axios.interceptors.request.eject(myInterceptor)

你可以给一个自定义axios实例添加拦截器，

const instance = axios.create()
instance.interceptors.request.use(function() {
    
    ...})

13，Handling Errors处理错误

axios.get('/user/12345')
  .catch(function (error) {
    
    
    if (error.response) {
    
    
      // 创造请求并且服务器给出一个带状态码的响应
      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);
  });

你可以用alidateStatus配置项定义一个自定义的HTTP状态码错误范围：

axios.get('/user/12345', {
    
    
    validateStatus: function (status) {
    
    
        return status < 500
    }
})

14，Cancellation 取消

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

The axios cancel token API is based on the withdrawn cancelable promises proposal.

• **创建方法一：**你可以用CancelToken.source创建一个cancel token ，示例如下：

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 {
    
    
    //处理错误信息
  }
});

axios.post('/user/12345', {
    
    
  name: 'new name'
}, {
    
    
  cancelToken: source.token
})

// 取消该请求 (信息参数是可选的)
source.cancel('Operation canceled by the user.');

• 创建方法二：你也可以通过CancelToken构造函数来创建cancel token

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

**提示：**你可以用同样的cancel token取消多个服务器请求

15，用application/x-www-form-urlencoded格式

axios自动的把JS对象序列化到JSON。你可以用下列选项中的一个，来发送在application/x-www-form-urlencoded格式中的数据

• Browser

  在浏览器中，你可以像如下这样用URLSearchParams API

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

• Node.js

  在node.js中，你可以像下面这样用querystring模块：

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

oken`取消多个服务器请求

15，用application/x-www-form-urlencoded格式

axios自动的把JS对象序列化到JSON。你可以用下列选项中的一个，来发送在application/x-www-form-urlencoded格式中的数据

• Browser

  在浏览器中，你可以像如下这样用URLSearchParams API

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

• Node.js

  在node.js中，你可以像下面这样用querystring模块：

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