API

可以通过将相关配置传递给axios来发出请求。

• axios(config)

示例一：

// 发送 POST 请求
axios({
  method: "post",
  url: "/login",
  data: {
    username: "admin",
    password: "admin"
  }
});

示例二：

// 在node.js中通过GET请求从远程获取图片
axios({
  method: 'get',
  url: 'http://example.com/demo.jpg',
  responseType: 'stream'
})
  .then(function (response) {
    response.data.pipe(fs.createWriteStream('demo.jpg'))
  });

• axios(url[, config])

示例：

// 发送GET请求（默认配置）
axios('/user/12345');

请求方法的别名

为方便使用，axios为所有受支持的请求方法提供了相应的别名。

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

以上的方法名对应的其请求的方法名称。

注意：当使用别名方法时，url、method和data属性不需要在配置中指定。

实例

• 创建实例

您可以使用自定义配置创建一个新的axios实例。

axios.create([config])

示例：

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

• 示例方法

下面列出了可用的实例方法。指定的配置将与实例配置合并。

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

请求配置

这些是用于发出请求的可用配置选项。只需要url。如果没有指定method，请求将默认为GET。

{
  // `url` 用于请求的服务器URL
  url: '/user',

  // `method` 请求时使用的请求方法
  method: 'get', // default

  // `baseURL` 将被用为url的前缀，除非url是绝对的。
  // 为axios实例设置' baseURL '可以方便地传递相对url
  // to methods of that instance.
  baseURL: 'https://some-domain.com/api/',

  // `transformRequest` 允许在发送到服务器之前更改请求数据
  // 这只适用于请求方法 'PUT', 'POST', 'PATCH' 和 'DELETE'
  // 数组中的最后一个函数必须返回一个字符串或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` 负责序列化“params”的可选函数
  // (例如： https://www.npmjs.com/package/qs, http://api.jquery.com/jquery.param/)
  paramsSerializer: function (params) {
    return Qs.stringify(params, {arrayFormat: 'brackets'})
  },

  // `data` 作为请求体发送的数据
  // 仅适用于请求方法 'PUT', 'POST', 'DELETE 和 'PATCH'
  // 当没有设置' transformRequest '时，必须是以下类型之一:
  // - string, 普通的对象, ArrayBuffer, ArrayBufferView, URLSearchParams
  // - Browser only: FormData, File, Blob
  // - Node only: Stream, Buffer
  data: {
    firstName: 'Fred'
  },
  
  // 向主体发送数据到可选语法
  // method 的值为 post
  // 只发送值，不发送键
  data: 'Country=Brasil&City=Belo Horizonte',

  // `timeout` 指定请求超时前的毫秒数。
  // 如果请求的时间超过' timeout '，请求将被中止。
  timeout: 1000, // 默认为' 0 '(永远不会超时)

  // `withCredentials` 设置是否跨站点访问控制请求
  // 应使用凭证
  withCredentials: false, // 默认

  // `adapter` 允许自定义处理请求，使测试更容易。
  // 返回一个promise并提供一个有效的响应 (请参考 lib/adapters/README.md).
  adapter: function (config) {
    /* ... */
  },

  // `auth` 指定使用HTTP基本身份验证，并提供凭据。
  // 这将设置一个' Authorization '头，覆盖任何现有的头
  // 使用' headers '设置的' Authorization '自定义头
  // 请注意，只有HTTP基本认证可通过此参数配置。
  // 对于Bearer令牌之类的，可以使用`Authorization` 自定义头替代
  auth: {
    username: 'janedoe',
    password: 's00pers3cret'
  },

  // `responseType` 指示服务器将响应的数据类型
  // 值可以是: 'arraybuffer', 'document', 'json', 'text', 'stream'
  //   仅限于浏览器: 'blob'
  responseType: 'json', // 默认值

  // `responseEncoding` 指示用于解码响应的编码(仅限于Node.js)
  // 注意:对于'stream'的' responseType '或客户端请求将被忽略
  responseEncoding: 'utf8', // 默认值

  // `xsrfCookieName` cookie的名称用作xsrf令牌的值
  xsrfCookieName: 'XSRF-TOKEN', // 默认值

  // `xsrfHeaderName` 携带xsrf令牌值的http头的名称
  xsrfHeaderName: 'X-XSRF-TOKEN', // 默认值

  // `onUploadProgress` 允许处理上传的进度事件
  // 仅限于浏览器
  onUploadProgress: function (progressEvent) {
    // 对本地进度事件执行您想要的任何操作
  },

  // `onDownloadProgress` 允许处理下载的进度事件
  // 仅限于浏览器
  onDownloadProgress: function (progressEvent) {
    // 对本地进度事件执行您想要的任何操作
  },

  // `maxContentLength` 定义node.js中允许的http响应内容的最大字节的大小
  maxContentLength: 2000,

  // `maxBodyLength` (仅限于Node选项)定义允许的http请求内容的最大大小(以字节为单位)
  maxBodyLength: 2000,

  // `validateStatus` 定义是否resolve 或reject 给定的promise
  //HTTP响应状态码。如果' validateStatus '返回' true '(或设置为' null '或' undefined ')
  //promise 将被resolved;否则，承诺将被rejected。
  validateStatus: function (status) {
    return status >= 200 && status < 300; // 默认实现
  },

  // `maxRedirects` 在node.js中定义要遵循的重定向的最大数量。
  // 如果设置为0，则不会进行重定向。
  maxRedirects: 5, // 默认值

  // `socketPath` 定义在node.js中使用的UNIX套接字。
  // 例如： '/var/run/docker.sock' 向docker守护进程发送请求。
  // 只能指定' socketPath '或' proxy '。
  // 如果两者都指定，则使用' socketPath '。
  socketPath: null, // 默认值

  //“httpAgent”和“httpAgent”分别定义了在node.js中执行http和https
  // 请求时使用的自定义代理。这允许添加选项，如“keepAlive”，默认情况下不启用。
  httpAgent: new http.Agent({ keepAlive: true }),
  httpsAgent: new https.Agent({ keepAlive: true }),

  // ' proxy '定义代理服务器的主机名、端口和协议。
  // 您还可以使用传统的“http_proxy”和“https_proxy”环境变量定义您的代理。
   // 如果你正在为你的代理配置使用环境变量，你也可以定义一个“no_proxy”环境变量
   //作为一个逗号分隔的不应该被代理的域列表。
  // 使用“false”禁用代理，忽略环境变量。
  // `auth` 指示应该使用HTTP基本认证连接到代理，并提供凭据。
  // 这将设置一个' Proxy-Authorization '头，
  // 覆盖任何使用' headers '设置的现有' Proxy-Authorization '自定义头。
  // 如果代理服务器使用HTTPS，那么您必须将协议设置为“HTTPS”。
  proxy: {
    protocol: 'https',
    host: '127.0.0.1',
    port: 9000,
    auth: {
      username: 'mikeymike',
      password: 'rapunz3l'
    }
  },

  // ' cancelToken '指定一个可用于取消请求的取消令牌(详细信息请参阅下面的Cancellation部分)
  cancelToken: new CancelToken(function (cancel) {
  }),

  // `decompress` 指示响应体是否应自动解压缩。
  // 如果设置为“true”，也将从所有解压缩的响应对象中移除
//“content-encoding”头——仅限于Node(XHR无法关闭解压缩)
  decompress: true // default

}

响应模式

请求的结果响应包含以下信息。

{
  // `data` 服务器提供的响应内容
  data: {},

  // `status` 来自服务器HTTP响应状态码
  status: 200,

  // `statusText`来自服务器HTTP响应状态消息
  statusText: 'OK',

  // `headers` 服务器用所有报头名称响应的HTTP报头是小写的，可以使用括号符号访问。
  // 例如: `response.headers['content-type']`
  headers: {},

  // `config`为“axios”的请求提供的配置
  config: {},

  // `request`生成此响应的请求
  // 它是node.js(重定向)中的最后一个ClientRequest实例和浏览器中的一个XMLHttpRequest实例
  request: {}
}

当使用then时，您将收到如下响应：

axios.get('/login')
  .then(function (response) {
    console.log(response.data);
    console.log(response.status);
    console.log(response.statusText);
    console.log(response.headers);
    console.log(response.config);
  });

当使用catch或rejection callback（https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then）回调作为then的第二个参数时，响应将通过error对象变量获得，在处理错误一节中对此进行了解释（https://axios-http.com/docs/handling_errors）。

配置默认值

您可以指定应用于每个请求的配置默认值。

• axios全局默认配置项

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

• 自定义示例配置项

// 创建实例时配置默认值
const instance = axios.create({
  baseURL: 'https://api.example.com'
});

// 在创建实例之后更改默认值
instance.defaults.headers.common['Authorization'] = AUTH_TOKEN;

• 配置的优先级

配置将按照优先级的顺序被合并。在lib/defaults中可以查看库的顺序默认值。然后是实例的默认属性，最后是请求的config参数。后者将优先于前者。

例如：

// 使用库提供的配置默认值创建一个实例
// 此时，超时配置值为' 0 '，这是库的默认值
const instance = axios.create();

// 覆盖库的默认超时
// 现在，所有使用此实例的请求将在超时前等待2.5秒
instance.defaults.timeout = 2500;

// 重载此请求的超时时间，因为众所周知这需要很长时间
instance.get('/login', {
  timeout: 5000
});

拦截器

您可以在then或catch处理请求或响应之前拦截它们。

例如：

// 添加一个请求拦截器
axios.interceptors.request.use(function (config) {
    // 在发送请求之前先做一些事情
    return config;
  }, function (error) {
    // 处理请求错误
    return Promise.reject(error);
  });

// 添加一个响应拦截器
axios.interceptors.response.use(function (response) {
    // 任何位于2xx范围内的状态代码都会触发此函数
    // 对响应数据做一些事情
    return response;
  }, function (error) {
    // 任何超出2xx范围的状态码都会触发此函数
    // 处理请求错误
    return Promise.reject(error);
  });

如果您需要稍后删除拦截器，您可以这样做。

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

您可以向axios的自定义实例添加拦截器。

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

处理错误

示例：

axios.get('/login')
  .catch(function (error) {
    if (error.response) {
      // 发出请求后，服务器用状态码进行响应
      //这不在2xx的范围内
      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);
  });

使用validateStatus配置选项，您可以定义应该抛出错误的HTTP代码。

axios.get('/user/12345', {
  validateStatus: function (status) {
    return status < 500; // 仅当状态码小于500时才进行解析
  }
})

使用toJSON可以获得一个包含HTTP错误更多信息的对象。

axios.get('/login')
  .catch(function (error) {
    console.log(error.toJSON());
  });

取消请求

您可以使用取消令牌取消请求。

axios取消令牌API基于撤消的可取消承诺提议(https://github.com/tc39/proposal-cancelable-promises)。

您可以使用CancelToken.source创建一个取消令牌工厂如下所示：

const CancelToken = axios.CancelToken;
const source = CancelToken.source();

axios.get('/login', {
  cancelToken: source.token
}).catch(function (thrown) {
  if (axios.isCancel(thrown)) {
    console.log('Request canceled', thrown.message);
  } else {
    // handle error
  }
});

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

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

你也可以通过向构造函数CancelToken传递executor函数来创建一个取消令牌:

const CancelToken = axios.CancelToken;
let cancel;

axios.get('/login', {
  cancelToken: new CancelToken(function executor(c) {
    // 执行函数接收一个cancel函数作为参数
    cancel = c;
  })
});

// 取消请求
cancel();

注意：您可以用相同的取消令牌取消多个请求。

url编码的请求体

默认情况下，axios将JavaScript对象序列化为JSON。要用application/x-www-form-urlencoded格式发送数据，您可以使用以下选项之一。

• 浏览器

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

const params = new URLSearchParams();
params.append('username', 'admin');
params.append('password', 'admin');
axios.post('/login', params);

注意：URLSearchParams并不被所有的浏览器支持(参见caniuse.com。http://www.caniuse.com/#feat=urlsearchparams)，但是有一个可用的polyfill(确保填充全局环境)。

另外，你也可以使用qs（https://github.com/ljharb/qs）库来编码数据：

const qs = require('qs');
axios.post('/login', qs.stringify({ 'username': 'admin','password':'admin' }));

或者用另一种方式(ES6)

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

• Node.js

查询字符串

在node.js中，你可以使用querystring模块如下：

const querystring = require('querystring');
axios.post('http://example.com/login/', 
           querystring.stringify({ username: 'admin',password: 'admin' 
                }));

或者url模块中的URLSearchParams，如下所示：

const url = require('url');
const params = new url.URLSearchParams({ username: 'admin',password: 'admin' });
axios.post('http://example.com/login/', params.toString());

你也可以使用qs库。

注意：如果需要对嵌套对象进行字符串化，则最好使用qs库，因为querystring方法知道该用例存在问题 (https://github.com/nodejs/node-v0.x-archive/issues/1665)。

表单数据

在node.js中，你可以使用form-data库如下：

const FormData = require('form-data');
 
const form = new FormData();
form.append('username', 'my value');
form.append('buffer', new Buffer(10));
form.append('file', fs.createReadStream('image.jpg'));

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

或者，使用拦截器：

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

注意事项

• 语义化版本号

在axios发布1.0版本之前，破坏性更改将通过一个新的小版本发布。例如，0.5.1和0.5.4将具有相同的API，但0.6.0将具有破坏性的更改。

• Promises

axios依赖于要支持的本机ES6Promise实现(https://caniuse.com/promises)。如果您的环境不支持ES6Promise，您可以使用polyfill。