axios 中文文檔 翻譯

axios

版本:v0.18.0

0.18.0的版本更新有一段時間了，使用起來跟原先基本沒有什麼變化。可是增長了一些功能，例如錯誤處理的辨別，於07-06-2018從新翻譯和校驗了該翻譯，更正了一些錯別字和表達不許的地方，可是不免仍有錯誤，歡迎指出。

因爲工做須要，我的也包裝了一個簡易的跟axios風格同樣在小程序中使用的請求函數。方便一些使用相似vue寫法框架來開發小程序的人更方便的無縫橋接。
有須要的讀者能夠觀看一下。 傳送門

關於Promise的一練習和訓練，此處有一個比較好的集合。傳送門

正文

基於Promise的http庫，適用於瀏覽器和node.js。

原文

點擊查看原文

特點

• 瀏覽器端發起XMLHttpRequests請求
• node端發起http請求
• 支持Promise API
• 攔截請求和返回
• 轉化請求和返回（數據）
• 取消請求
• 自動轉化json數據
• 客戶端支持抵禦XSRF（跨站請求僞造）

瀏覽器支持

Latest ✔	Latest ✔	Latest ✔	Latest ✔	Latest ✔	8+ ✔

安裝

使用npm：

$ npm i axios

使用 bower

$ bower instal axios

使用cdn

<!--國內bootCDN-->
<script src="https://cdn.bootcss.com/axios/0.18.0/axios.min.js"></script>

示例

發起一個GET請求

const axios = require('axios')

//發起一個user請求，參數爲給定的ID
axios.get('/user?ID=12345')
.then(function(respone){
    console.log(response);
})
.catch(function(error){
    console.log(error);
});

//可配置的方式實現上面的代碼以下
axios.get('/user',{
    params:{
        ID:12345
    }
}).then(function(response){
        console.log(response);
  }).catch(function(error){
        console.log(error)
    });

注意：async/await是ECMAScript2017的語法，ie和一些老舊的瀏覽器不支持，請當心使用。
（譯者話：使用ts的話能夠很容易的編譯和使用，也不須要任何墊片，目標編譯成es5便可）

發起一個POST請求

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

發起一個多重併發請求

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

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

axios.all([getUerAccount(),getUserPermissions()])
    .then(axios.spread(function(acc,pers){
        //兩個請求如今都完成
    }));

譯者話：由於axios.all使用的是相似Primise.all的功能，因此若是其中有一個請求出現了錯誤那麼就會中止請求，因此建議對於單個請求最好附加上處理的catch。

axios API

---

根據本身需求能夠對axios傳遞一些的設置來生成請求（Request）。

axios(config)

//發起 POST請求

axios({
    method:'post',//方法
    url:'/user/12345',//地址
    data:{//參數
        firstName:'Fred',
        lastName:'Flintstone'
    }
});

//經過請求獲取遠程圖片
axios({
    method:'get',
    url:'http://bit.ly/2mTM3Ny',
    responseType:'stream'
})
    .then(function(response){
        response.data.pipe(fs.createWriteStream('ada_lovelace.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屬性沒必要在config中明確指定（如上面示例的post方法請求）。

併發 Concurrency

有用的方法

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

建立一個實例（instance）

你可使用自定義設置建立一個新的實例

axios.create([config])

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

實例方法

下面列出了一些實例可用方法，具體的設置將在實例中應用。

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

Requeset Config請求設置

如下列出了一些請求時的設置選項。只有url是必須的，若是沒有指明method的話，默認的請求方法是GET.

{
    //`url`是服務器連接，用來請求
    url:'/user',

    //`method`是發起請求時的方法
    method:`get`,

    //`baseURL`若是`url`不是絕對地址，那麼將會加在其前面。
    //能夠很方便的對相對地址的axios實例設置`baseUrl`。
    baseURL:'http://some-domain.com/api/',

    //`transformRequest`容許請求的數據在發送至服務器以前進行轉化。
    //這個只適用於`PUT`,`POST`,`PATCH`方法。
    //數組中的最後一個函數必須返回一個字符串或者一個`ArrayBuffer`,或者`Stream`,`Buffer`實例,`ArrayBuffer`,`FormData`
    //此外你也可能須要設置下headers對象
    transformRequest:[function(data,headers){
        //依本身的需求對請求數據進行處理
        return data;
    }],

    //`transformResponse`容許對返回的數據傳入then/catch以前進行處理
    transformResponse:[function(data){
        //依須要對數據進行處理
        return data;
    }],

    //`headers`是自定義的要被髮送的信息頭
    headers:{'X-Requested-with':'XMLHttpRequest'},

    //`params`是請求鏈接中的請求參數，必須是一個純對象，或者URLSearchParams對象
    params:{
        ID:12345
    },
    
    //`paramsSerializer`是一個可選的函數，用來控制和序列化參數
    //例如：（https://ww.npmjs.com/package/qs,http://api.jquery.com/jquery.param/)
    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:'fred'
    },
    //`timeout`定義請求的時間，單位是毫秒。
    //若是請求的時間超過這個設定時間，請求將會中止。
    timeout:1000,
    
    //`withCredentials`代表跨跨域請求書否須要證實。
    withCredentials:false //默認值

    //`adapter`適配器，容許自定義處理請求，這會使測試更簡單。
    //返回一個promise，而且提供一個有效的相應。（查看[response docs](#response-api)）
    adapter:function(config){
        /*...*/
    },

    //`auth`代表HTTP基礎的認證應該被使用，而且提供證書。
    //這個會設置一個`authorization` 頭（header），而且覆蓋你在header設置的Authorization頭信息。
    auth:{
        username:'janedoe',
        password:'s00pers3cret'
    },

    //`responsetype`代表服務器返回的數據類型，這些類型的設置應該是
    //'arraybuffer','blob','document','json','text',stream'
    responsetype:'json',

    //`responseEncoding`代表解析相應的編碼方式。
    //**注意**會忽視responseType爲stream或者客戶端的請求。
    responseEncoding:'utf8'//默認值

    //`xsrfCookieName`時cookie作xsrf會話時的名字。
    xsrfCookieName:'XSRF-TOKEN',//默認值

    //`xsrfHeaderName` 是http頭（header）的名字，而且該頭攜帶xsrf的值
    xrsfHeadername:'X-XSRF-TOKEN'，//默認值

    //`onUploadProgress`容許處理上傳過程的進程事件
    onUploadProgress: function(progressEvent){
        //本地過程事件發生時想作的事
    },

    //`onDownloadProgress`容許處理下載過程的進程事件
    onDownloadProgress: function(progressEvent){
        //下載過程當中想作的事
    },

    //`maxContentLength` 定義http返回內容的最大字節容量
    maxContentLength: 2000,

    //`validateStatus` 定義promise的resolve和reject。
    //http返回狀態碼，若是`validateStatus`返回true（或者設置成null/undefined），promise將會resolve；其餘的promise將reject。
    validateStatus: function(status){
        return status >= 200 && stauts < 300;//默認
    },

    //`maxRedirect`定義重導向到node.js中的最大數量。
    //若是值爲0，那麼沒有redirect。
    maxREdirects:5,//默認值

    //`socketPath`定義一個在node.js中使用的 `UNIX Socket`。
    //例如 `/var/run/docker.sock`發送請求到docker daemon。
    //`socketPath`和`proxy`只可定義其一。
    //若是都定義則只會使用`socketPath`。
    socketPath:null,//默認值

    //`httpAgent` 和 `httpsAgent`當產生一個http或者https請求時分別定義一個自定義的代理，在nodejs中。
    //這個容許設置一些選選個，像是`keepAlive`--這個在默認中是沒有開啓的。
    httpAgent: new http.Agent({keepAlive:treu}),
    httpsAgent: new https.Agent({keepAlive:true}),

    //`proxy`定義服務器的主機名字和端口號。
    //`auth`代表HTTP基本認證應該跟`proxy`相鏈接，而且提供證書。
    //這個將設置一個'Proxy-Authorization'頭(header)，覆蓋原先自定義的。
    proxy:{
        host:127.0.0.1,
        port:9000,
        auth:{
            username:'cdd',
            password:'123456'
        }
    },

    //`cancelTaken` 定義一個取消，可以用來取消請求
    //（查看 下面的Cancellation 的詳細部分）
    cancelToken: new CancelToken(function(cancel){
    })
}

返回響應概要 Response Schema

一個請求的返回包含如下信息

{
    //`data`是服務器的提供的回覆（相對於請求）
    data{},

    //`status`是服務器返回的http狀態碼
    status:200,


    //`statusText`是服務器返回的http狀態信息
    statusText: 'ok',

    //`headers`是服務器返回中攜帶的headers
    headers:{},

    //`config`是對axios進行的設置，目的是爲了請求（request）
    config:{}

    //`request`是獲取當前相應的請求
    //它是node.js中最後一次的 ClientRequest的實例（在redirect中）
    //或者是在瀏覽器中的XMLHttpREquest實例
}

使用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時，或者傳入一個reject callback做爲then的第二個參數，那麼返回的錯誤信息將可以被處理。

---

默認設置（Config Default)

你能夠設置一個默認的設置，這設置將在以後的每次請求中生效。

全局默認設置 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 default

//當建立一個實例時進行默認設置
var instance = axios.create({
    baseURL:'https://api.example.com'
});

//或者在實例建立以後改變默認值
instance.defaults.headers.common['Authorization'] = AUTH_TOKEN;

設置優先級 Config order of precedence

設置(config)將按照優先順序合併起來。首先的是在lib/defaults.js中定義的默認設置，其次是defaults實例屬性的設置，最後是請求中config參數的設置。越日後面的等級越高，會覆蓋前面的設置。
看下面這個例子：

//使用默認庫的設置建立一個實例，
//這個實例中，使用的是默認庫的timeout設置，默認值是0。
var instance = axios.create();

//覆蓋默認庫中timeout的默認值
//此時，全部的請求的timeout時間是2.5秒
instance.defaults.timeout = 2500;

//覆蓋該次請求中timeout的值，這個值設置的時間更長一些
instance.get('/longRequest',{
    timeout:5000
});

---

攔截器 interceptors

你能夠在請求或者返回被then或者catch處理以前對他們進行攔截。

//添加一個請求攔截器
axios.interceptors.request.use(function(config){
    //在請求發送以前作一些事
    return config;
},function(error){
    //當出現請求錯誤是作一些事
    return Promise.reject(error);
});

//添加一個返回攔截器
axios.interceptors.response.use(function(response){
    //對返回的數據進行一些處理
    return response;
},function(error){
    //對返回的錯誤進行一些處理
    return Promise.reject(error);
});

若是你須要在稍後移除攔截器,你能夠

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

你能夠在一個axios實例中使用攔截器

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

---

錯誤處理 Handling Errors

axios.get('user/12345')
    .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的 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時視爲錯誤
    }
});

---

取消 Cancellation

你可使用cancel token取消一個請求

axios的cancel token API是基於已經撤銷的**cnacelable promises proposal**提議。

你可使用CancelToken.source工廠函數建立一個cancel token，以下：

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

axios.get('/user/12345', {
    cancelToken:source.toke
}).catch(function(thrown){
    if(axiso.isCancel(thrown)){
        console.log('Rquest canceled', thrown.message);
    }else{
        //handle error
    }
});

//取消請求(信息參數設可設置的)
source.cancel("操做被用戶取消");

你能夠給CancelToken構造函數傳遞一個executor function來建立一個cancel token:

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

axios.get('/user/12345',{
  cancelToke:source.token
}).catch(function(thrown){
  if(axios.isCancel(throw)){
    console.log('請求已取消',throw.message)
  }else{
    //處理錯誤
  }
})

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

source.cancel('錯作已被用戶取消！')

你也能夠給CancelToke的構造函數傳遞一個處理函數來生成一個cancel token。

const CancelToken = axios.CancelToken
let cancel;

acios.get('/user/12345',{
  cancelToken:new CancelToken(function excutor(c){
    //一個處理函數接受一個cancel函數做爲參數
    cancel = c
  })
})

// 取消請求
cancel()

注意：你可使用同一個cancel token取消多個請求。

---

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

本人作的簡單包裝

默認狀況下，axios串聯js對象爲JSON格式。爲了發送application/x-wwww-form-urlencoded格式數據，
你可使用一下的設置。

瀏覽器 Browser

在瀏覽器中你能夠以下使用URLSearchParams API:

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

注意：URLSearchParams不支持全部的瀏覽器，可是這裏有個墊片
（poly fill）可用（確保墊片在瀏覽器全局環境中）

其餘方法：你可使用qs庫來對數據編碼。

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

或者其餘方法(es6)

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

兼容Semver

當axios放出1.0版本時，一些不兼容的更改將會放在新的版本中。例如0.5.1和0.5.4有相同的api，可是0.6.0會有不兼容的變化。

譯者：小知識
在npn的版本習慣中，版本使用的習慣是a.b.c,其中c的變化是一些bug的修復，b是一些功能的添加，a是大的版本的變化，會出現不兼容的狀況。

Node.js

在nodejs中，你能夠以下使用querystring:

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

你一樣可使用qs庫。

---

promises

axios 基於原生的ES6 Promise 實現。若是環境不支持請使用墊片.

TypeScript

axios 包含TypeScript定義

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