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

本文地址：https://blog.csdn.net/tuzi007a/article/details/107754966