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
APIconst 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
APIconst 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