欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

axios官方技术文档(自翻译版)

程序员文章站 2022-04-12 22:38:58
axios 文档翻译大家好,我是梅巴哥~正在用react写一些项目,但是很多需要用到的知识,没有合适的中文文档可以查看和学习。于是就有了自己翻译官方文档的想法。我英语水平一般,很多单词不认识,都是靠百度和搜集相关资料查到的。如有错误,欢迎在评论里批评指正。希望这篇文档对大家在axios方面的学习,能有所帮助。1,概述基于Promise的http库,适用于浏览器和node.js。特点:从浏览器中创建 XMLHttpRequests从 node.js 创建 http请求支持promise...

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官方技术文档(自翻译版)

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

axios官方技术文档(自翻译版)

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 拦截器

在请求或响应被thencatch处理前,你可以拦截这些请求或响应。

// 添加一个请求拦截器 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

相关标签: react