axios official guide translation

Translation of the original link https://github.com/axios/axios
axios Personal pronunciation: Axis

Promise based HTTP client for the browser and node.js
translation: Promise based HTTP client for the browser and node.js

Features

• Make XMLHttpRequests from the browser (Create XMLHttpRequests in the browser)
• Make http requests from node.js (create http requests in node.js)
• Supports the Promise API （支持Promise API）
• Intercept request and response (Intercept request and response)
• Transform request and response data (transform request and response data format)
• Cancel requests
• Automatic transforms for JSON data (automatic transforms for JSON data)
• Client side support for protecting against XSRF ( Client side support for protecting against XSRF [cross-site request forgery] attacks)

Browser Support Browser Support

Chrome	FireFox	Safari	Opera	Edge	IE
Latest ✔	Latest✔	Latest✔	Latest✔	Latest✔	11✔

Installing process

• Using npm: Use npm to install:

$ npm install axios

• Using bower: install using bower

$ bower install axios

• Using yarn: install using yarn

$ yarn add axios

• Using jsDelivr CDN: Use jsDelivr static resources to accelerate the network

<script src="https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js"></script>

• Using unpkg CDN: Use unpkg static resources to speed up the network

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

Example

In order to gain the TypeScript typings (for intellisense / autocomplete) while using CommonJS imports with require() use the following approach:

Translation: In order to get TypeScript code hints (smart hints/autofill), use CommonJS to import, please use the following method of require():

const axios = require('axios').default;

// axios. will now provide autocomplete and parameter typings
axios.method will now provide autocomplete and parameter typings

Performing a GET request

const axios = require('axios');

// Make a request for a user with a given ID 根据id查询用户
axios.get('/user?ID=12345')
  .then(function (response) {
    // handle success 成功处理
    console.log(response);
  })
  .catch(function (error) {
    // handle error 失败处理
    console.log(error);
  })
  .then(function () {
    // always executed 总会执行
  });

// Optionally the request above could also be done as 以上请求也可以这样做
axios.get('/user', {
    params: {
      ID: 12345
    }
  })
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  })
  .then(function () {
    // always executed
  });  

// Want to use async/await? Add the `async` keyword to your  outer function/method.
async function getUser() {
  try {
    const response = await axios.get('/user?ID=12345');
    console.log(response);
  } catch (error) {
    console.error(error);
  }
}

async/await is part of ECMAScript 2017 and is not supported in Internet Explorer and older browsers, so use with caution.
async/await is the content of ES 2017 and does not support Internet Explorer and some older browsers. Please use it with caution.

Performing a POST request

axios.post('/user', {
    firstName: 'Fred',
    lastName: 'Flintstone'
  })
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  });

Performing multiple concurrent requests  //执行多个并发请求

function getUserAccount() {
  return axios.get('/user/12345');
}

function getUserPermissions() {
  return axios.get('/user/12345/permissions');
}

Promise.all([getUserAccount(), getUserPermissions()])
  .then(function (results) {
    const acct = results[0];
    const perm = results[1];
  });

axios API axios interface

Requests can be made by passing the relevant config to axios. Requests can be made by passing the relevant config to axios
.
axios(config)

// Send a POST request  发送POST请求
axios({
  method: 'post',
  url: '/user/12345',
  data: {
    firstName: 'Fred',
    lastName: 'Flintstone'
  }
});

// GET request for remote image in node.js 在nodejs中读取远程图片
axios({
  method: 'get',
  url: 'http://bit.ly/2mTM3nY',
  responseType: 'stream'
})
  .then(function (response) {
    response.data.pipe(fs.createWriteStream('ada_lovelace.jpg'))
  });

axios(url[, config])

// Send a GET request (default method)
axios(’/user/12345’);

Request method aliases

For convenience aliases have been provided for all supported request methods.

Translation: For convenience, aliases have provided all request methods.

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

When using the alias methods url, method, and data properties don't need to be specified in config. When using the alias methods, url, method, and data properties don't need to be
declared in config.

Concurrency (Deprecated) Concurrency (Deprecated)

Please use Promise.all to replace the below functions. Please use Promise.all to replace the below functions
.
Helper functions for dealing with concurrent requests. Helper functions for dealing with concurrent requests
.

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

Creating an instance

You can create a new instance of axios with a custom config.

You can create an axios instance with custom configuration
axios.create([config])

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

Instance methods

The available instance methods are listed below. The specified config will be merged with the instance config.

The example methods are listed below. The specified configuration will be merged with the instance configuration.

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

Request Config

These are the available config options for making requests. Only the url is required. Requests will default to GET if method is not specified.

Translation: These are the available configuration options for making the request. Only the url is required. If no method is specified, the request will default to GET.

{
  // `url` is the server URL that will be used for the request （请求的url地址）
  url: '/user',

  // `method` is the request method to be used when making the request （method 是发出请求时使用的请求方法）
  method: 'get', // default 默认方式

  // `baseURL` will be prepended to `url` unless `url` is absolute.（' baseURL '将被放在' url '的前面，除非url时绝对路径）
  // It can be convenient to set `baseURL` for an instance of axios to pass relative URLs
  它可以在axios实例设置baseURL值方便指定相对路径
  // to methods of that instance.
  baseURL: 'https://some-domain.com/api/',

  // `transformRequest` allows changes to the request data before it is sent to the server（transformRequest 允许在发送到服务之前更改请求数据）
  // This is only applicable for request methods 'PUT', 'POST', 'PATCH' and 'DELETE'（它只适用这些请求方法‘PUT’,'POST','PATCH','DELETE'）
  // The last function in the array must return a string or an instance of Buffer, ArrayBuffer,(在数组中的最后一个函数必须返回字符串或Buffer,ArrayBuffer对象)
  // FormData or Stream
  // You may modify the headers object.
  transformRequest: [function (data, headers) {
    // Do whatever you want to transform the data

    return data;
  }],

  // `transformResponse` allows changes to the response data to be made before（transformResponse 允许在响应数据之前更改响应数据）
  // it is passed to then/catch 它被传递给then/catch
  transformResponse: [function (data) {
    // Do whatever you want to transform the data

    return data;
  }],

  // `headers` are custom headers to be sent (自定义请求头)
  headers: {'X-Requested-With': 'XMLHttpRequest'},

  // `params` are the URL parameters to be sent with the request（param是与请求一起发送的URL 参数）
  // Must be a plain object or a URLSearchParams object（必须是一个普通对象还是一个URLSearchParams对象）
  params: {
    ID: 12345
  },

  // `paramsSerializer` is an optional function in charge of serializing `params`（' parsserializer '是一个可选函数负责序列化' params '）
  // (e.g. https://www.npmjs.com/package/qs, http://api.jquery.com/jquery.param/)
  paramsSerializer: function (params) {
    return Qs.stringify(params, {arrayFormat: 'brackets'})
  },

  // `data` is the data to be sent as the request body（' data '是作为请求体发送的数据）
  // Only applicable for request methods 'PUT', 'POST', 'DELETE , and 'PATCH' （仅适用PUT,POST,DELETE,PATCH这些请求方法）
  // When no `transformRequest` is set, must be of one of the following types:
  // - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
  // - Browser only: FormData, File, Blob
  // - Node only: Stream, Buffer
  data: {
    firstName: 'Fred'
  },
  
  // syntax alternative to send data into the body（将数据发送到主体的可选语法）
  // method post
  // only the value is sent, not the key （只发送值,不发送键）
  data: 'Country=Brasil&City=Belo Horizonte',

  // `timeout` specifies the number of milliseconds before the request times out.（timeout指定请求超时的毫秒数）
  // If the request takes longer than `timeout`, the request will be aborted.（当请求耗时超过timeout，请求被放弃）
  timeout: 1000, // default is `0` (no timeout) （默认为0，没有超时时间）

  // `withCredentials` indicates whether or not cross-site Access-Control requests （“withCredentials”表示是否跨站点访问控制请求）
  // should be made using credentials
  withCredentials: false, // default

  // `adapter` allows custom handling of requests which makes testing easier.
  // Return a promise and supply a valid response (see lib/adapters/README.md).
  adapter: function (config) {
    /* ... */
  },

  // `auth` indicates that HTTP Basic auth should be used, and supplies credentials.（“auth”表示应该使用HTTP基本认证，并提供凭据。）
  // This will set an `Authorization` header, overwriting any existing
  （这将设置一个' Authorization '头，覆盖任何现有的头）
  // `Authorization` custom headers you have set using `headers`.（你得在headers参数配置自定义Authorization请求头）
  // Please note that only HTTP Basic auth is configurable through this parameter.（请注意，只有HTTP基本认证可通过此参数配置。）
  // For Bearer tokens and such, use `Authorization` custom headers instead.
  auth: {
    username: 'janedoe',
    password: 's00pers3cret'
  },

  // `responseType` indicates the type of data that the server will respond with （声明服务器返回的数据类型）
  // options are: 'arraybuffer', 'document', 'json', 'text', 'stream'
  //   browser only: 'blob'
  responseType: 'json', // default

  // `responseEncoding` indicates encoding to use for decoding responses (Node.js only) （声明返回解码使用的编码）（仅用于Node.js）
  // Note: Ignored for `responseType` of 'stream' or client-side requests
  responseEncoding: 'utf8', // default

  // `xsrfCookieName` is the name of the cookie to use as a value for xsrf token
  xsrfCookieName: 'XSRF-TOKEN', // default

  // `xsrfHeaderName` is the name of the http header that carries the xsrf token value
  xsrfHeaderName: 'X-XSRF-TOKEN', // default

  // `onUploadProgress` allows handling of progress events for uploads(' onUploadProgress '允许处理上传的进度事件)
  // browser only
  onUploadProgress: function (progressEvent) {
    // Do whatever you want with the native progress event
  },

  // `onDownloadProgress` allows handling of progress events for downloads(' onDownloadProgress '允许处理下载的进度事件)
  // browser only
  onDownloadProgress: function (progressEvent) {
    // Do whatever you want with the native progress event
  },

  // `maxContentLength` defines the max size of the http response content in bytes allowed in node.js (' maxContentLength '定义了node.js中允许的http响应内容的最大字节大小)
  maxContentLength: 2000,

  // `maxBodyLength` (Node only option) defines the max size of the http request content in bytes allowed(' maxBodyLength '(仅节点选项)定义允许的http请求内容的最大大小(以字节为单位))
  maxBodyLength: 2000,

  // `validateStatus` defines whether to resolve or reject the promise for a given(' validateStatus '定义promise中的resolve或reject)
  // HTTP response status code. If `validateStatus` returns `true` (or is set to `null`
  // or `undefined`), the promise will be resolved; otherwise, the promise will be
  // rejected.
  validateStatus: function (status) {
    return status >= 200 && status < 300; // default
  },

  // `maxRedirects` defines the maximum number of redirects to follow in node.js.（maxRedirects定义最大重定向次数）
  // If set to 0, no redirects will be followed.
  maxRedirects: 5, // default

  // `socketPath` defines a UNIX Socket to be used in node.js.
  // e.g. '/var/run/docker.sock' to send requests to the docker daemon.
  // Only either `socketPath` or `proxy` can be specified.
  // If both are specified, `socketPath` is used.
  socketPath: null, // default

  // `httpAgent` and `httpsAgent` define a custom agent to be used when performing http
  // and https requests, respectively, in node.js. This allows options to be added like
  // `keepAlive` that are not enabled by default.
  httpAgent: new http.Agent({ keepAlive: true }),
  httpsAgent: new https.Agent({ keepAlive: true }),

  // `proxy` defines the hostname, port, and protocol of the proxy server.（' proxy '定义代理服务器的主机名、端口和协议。）
  // You can also define your proxy using the conventional `http_proxy` and
  // `https_proxy` environment variables. If you are using environment variables
  // for your proxy configuration, you can also define a `no_proxy` environment
  // variable as a comma-separated list of domains that should not be proxied.
  // Use `false` to disable proxies, ignoring environment variables.
  // `auth` indicates that HTTP Basic auth should be used to connect to the proxy, and
  // supplies credentials.
  // This will set an `Proxy-Authorization` header, overwriting any existing
  // `Proxy-Authorization` custom headers you have set using `headers`.
  // If the proxy server uses HTTPS, then you must set the protocol to `https`. 
  proxy: {
    protocol: 'https',
    host: '127.0.0.1',
    port: 9000,
    auth: {
      username: 'mikeymike',
      password: 'rapunz3l'
    }
  },

  // `cancelToken` specifies a cancel token that can be used to cancel the request （' cancelToken '指定一个可用于取消请求的取消令牌）
  // (see Cancellation section below for details) （详情在下面的Cancellation章节）
  cancelToken: new CancelToken(function (cancel) {
  }),

  // `decompress` indicates whether or not the response body should be decompressed 
  // automatically. If set to `true` will also remove the 'content-encoding' header 
  // from the responses objects of all decompressed responses
  // - Node only (XHR cannot turn off decompression)
  decompress: true // default

}

Response Schema

The response for a request contains the following information
.

{
  // `data` is the response that was provided by the server（data是服务端返回的响应体）
  data: {},

  // `status` is the HTTP status code from the server response（服务的返回的HTTP状态码）
  status: 200,

  // `statusText` is the HTTP status message from the server response（服务端响应的HTTP状态码信息）
  statusText: 'OK',

  // `headers` the HTTP headers that the server responded with（headers 是服务端响应的HTTP头）
  // All header names are lower cased and can be accessed using the bracket notation.（所有的请求头名称都是小写，可以用括号访问）
  // Example: `response.headers['content-type']`
  headers: {},

  // `config` is the config that was provided to `axios` for the request（config 是axios请求的config）
  config: {},

  // `request` is the request that generated this response (request是响应体生产的请求)
  // It is the last ClientRequest instance in node.js (in redirects)
  // and an XMLHttpRequest instance in the browser
  request: {}
}

When using then, you will receive the response as follows
:

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

When using catch, or passing a rejection callback as second parameter of then, the response will be available through the error object as explained in the Handling Errors section.

Translation: When using catch or reject callback as the second parameter of then, the response will be available through the error object, as described in the section Handling Errors.

Config Defaults

You can specify config defaults that will be applied to every request.
You can specify the default configuration is applied to all requests

Global axios defaults Global axios default configuration

axios.defaults.baseURL = 'https://api.example.com';

// Important: If axios is used with multiple domains, the AUTH_TOKEN will be sent to all of them.
// See below for an example using Custom instance defaults instead.
axios.defaults.headers.common['Authorization'] = AUTH_TOKEN;

axios.defaults.headers.post['Content-Type'] = 'application/x-www-form-urlencoded';

Custom instance defaults

// Set config defaults when creating the instance
const instance = axios.create({
  baseURL: 'https://api.example.com'
});

// Alter defaults after instance has been created
instance.defaults.headers.common['Authorization'] = AUTH_TOKEN;

Config order of precedence

Config will be merged with an order of precedence. The order is library defaults found in lib/defaults.js, then defaults property of the instance, and finally config argument for the request. The latter will take precedence over the former. Here's an example The
configuration will be merged in order of priority. Order is the defaultThe library, followed by the default configuration of the instance, and finally the requested configuration parameters. The last one will overwrite the previous one. As shown in this case.

// Create an instance using the config defaults provided by the library
// At this point the timeout config value is `0` as is the default for the library
const instance = axios.create();

// Override timeout default for the library
// Now all requests using this instance will wait 2.5 seconds before timing out
instance.defaults.timeout = 2500;

// Override timeout for this request as it's known to take a long time
instance.get('/longRequest', {
  timeout: 5000
});

Interceptors

You can intercept requests or responses before they are handled by then or catch. You can intercept requests or responses before they are handled by then or catch
.

// Add a request interceptor 添加请求拦截器
axios.interceptors.request.use(function (config) {
    // Do something before request is sent 在请求之前做些处理
    return config;
  }, function (error) {
    // Do something with request error 请求错误做些处理
    return Promise.reject(error);
  });

// Add a response interceptor 添加响应拦截器
axios.interceptors.response.use(function (response) {
    // Any status code that lie within the range of 2xx cause this function to trigger 状态码在2xx范围，该函数将被触发
    // Do something with response data
    return response;
  }, function (error) {
    // Any status codes that falls outside the range of 2xx cause this function to trigger
    // Do something with response error
    return Promise.reject(error);
  });

If you need to remove an interceptor later you can. If you need to remove an interceptor later you can
.

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

You can add interceptors to a custom instance of axios.
You can add a blocker for the specified instance axios

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

Handling Errors

axios.get('/user/12345')
  .catch(function (error) {
    if (error.response) {
      // The request was made and the server responded with a status code
      // that falls out of the range of 2xx 请求被发送且返回的状态码不是2xx
      console.log(error.response.data);
      console.log(error.response.status);
      console.log(error.response.headers);
    } else if (error.request) {
      // The request was made but no response was received 请求已发送但是没有收到响应
      // `error.request` is an instance of XMLHttpRequest in the browser and an instance of
      // http.ClientRequest in node.js (error.request是浏览器的XMLHttpRequest实例或Node.js http.ClientRequest的实例)
      console.log(error.request);
    } else {
      // Something happened in setting up the request that triggered an Error 一些在设置请求的时候报错触发的
      console.log('Error', error.message);
    }
    console.log(error.config);
  });

Using the validateStatus config option, you can define HTTP code(s) that should throw an error. Using the validateStatus of the configuration option, you can define
which HTTP status codes should throw errors.
axios.get('/user/12345', { validateStatus: function (status) { return status <500; // Resolve only if the status code is less than 500 (Only status codes less than 500 will be processed) } } )

Using toJSON you get an object with more information about the HTTP error.
Using toJSON you can get more information about the HTTP error .
axios.get('/user/12345')
.catch(function (error) { console.log(error.toJSON()); });

Cancellation Cancel the request

You can cancel a request using a cancel token.
You can cancel a request by using the cancel token

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

You can create a cancel token using the CancelToken.source factory as shown below: You can create a cancel token using the CancelToken.source factory as shown below
:

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 {
    // handle error
  }
});

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

// cancel the request (the message parameter is optional)
source.cancel('Operation canceled by the user.');

You can also create a cancel token by passing an executor function to the CancelToken constructor:
You can also transfer the executable function by CancelToken constructor creates a token canceled

const CancelToken = axios.CancelToken;
let cancel;

axios.get('/user/12345', {
  cancelToken: new CancelToken(function executor(c) {
    // An executor function receives a cancel function as a parameter
    cancel = c;
  })
});

// cancel the request
cancel();

Note: you can cancel several requests with the same cancel token.
You can cancel several requests with the same cancel token.

Using application/x-www-form-urlencoded format 使用application/x-www-form-urlencoded格式

By default, axios serializes JavaScript objects to JSON. To send data in the application/x-www-form-urlencoded format instead, you can use one of the following options.

Translation: By default, axios serializes JavaScript objects to JSON. To send data in application/x-www-form-urlencoded format, you can use one of the following options.

Browser

In a browser, you can use the URLSearchParams API as follows: In a browser, you can use the URLSearchParams API as follows
:

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

Note that URLSearchParams is not supported by all browsers (see caniuse.com ), but there is a polyfill available (make sure to polyfill the global environment). Note that URLSearchParams is not supported by all browsers , but there is a
component (polyfill ) Can support all (please make sure the polyfill is in the global environment)

Alternatively, you CAN encode a using the Data at The qs Library:
Alternatively, you can also use libraries to encode data qs

const qs = require('qs');
axios.post('/foo', qs.stringify({ 'bar': 123 }));

Or in another way (ES6),
another way (ES6)

import qs from 'qs';
const data = { 'bar': 123 };
const options = {
  method: 'POST',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  data: qs.stringify(data),
  url,
};
axios(options);

Node.js

Query string

In node.js, you can use the querystring module as follows:
In Nodejs , you can use the querystring module as follows :

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

or 'URLSearchParams' from 'url Module1' AS Follows:
or a url assembly URLSearchParams, as follows

const url = require('url');
const params = new url.URLSearchParams({ foo: 'bar' });
axios.post('http://something.com/', params.toString());

Also at The CAN use by You qs Library.
You can also use the library qs
NOTE

IF IS preferable QS Library at The you need to stringify nested Objects, AS AND DELINQUENCY at The QueryString Known Method, has with that use Case ( https://github.com/nodejs/node-v0.x-archive/issues/1665 ).
If you need To stringify nested objects, it is best to use the qs library, because the querystring method knows that there is a problem with the use case

Form data

In node.js, you can use the form-data library as follows: In node.js, you can use the form-data library as follows
:

const FormData = require('form-data');
 
const form = new FormData();
form.append('my_field', 'my value');
form.append('my_buffer', new Buffer(10));
form.append('my_file', fs.createReadStream('/foo/bar.jpg'));

axios.post('https://example.com', form, { headers: form.getHeaders() })

Alternatively, use an interceptor:
or use an interceptor

axios.interceptors.request.use(config => {
  if (config.data instanceof FormData) {
    Object.assign(config.headers, config.data.getHeaders());
  }
  return config;
});

Semver semantic version

Until axios reaches a 1.0 release, breaking changes will be released with a new minor version. For example 0.5.1, and 0.5.4 will have the same API, but 0.6.0 will have breaking changes.
Translation: Release 1.0 in axios Previously, breaking changes would be released through a new minor version. For example, 0.5.1 and 0.5.4 will have the same API, but 0.6.0 will have disruptive changes.

Promises

axios depends on a native ES6 Promise implementation to be supported . If your environment doesn't support ES6 Promises, you can polyfill .
axios depends on the ES6 Promise implementation. If your environment does not support ES6 Promises, you can patch

TypeScript

axios includes TypeScript definitions.
axios includes TypeScript definitions

import axios from 'axios';
axios.get('/user?ID=12345');

Resources

• Changelog
• Upgrade Guide
• Ecosystem
• Contributing Guide
• Code of Conduct

Credits inspiration

axios is heavily inspired by the http service provided in Angular . Ultimately axios is an effort to provide a standalone $http-like service for use outside of Angular.
Translation: Axios is inspired by the http service provided in Angular to a large extent. In the final analysis, axios is to provide an independent http-like service outside of Angular.

License open source agreement

WITH