[Web 前端] SuperAgent中文使用文檔

cp from : https://blog.csdn.net/gebitan505/article/details/58585846

superagent是nodejs裏一個很是方便的客戶端請求代理模塊，當你想處理get,post,put,delete,head請求時,你就應該想起該用它了:)

SuperAgent

superagent 是一個輕量的,漸進式的ajax api,可讀性好,學習曲線低,內部依賴nodejs原生的請求api,適用於nodejs環境下.

一個簡單的post請求，並設置請求頭信息的例子

 request .post('/api/pet') .send({ name: 'Manny', species: 'cat' }) .set('X-API-Key', 'foobar') .set('Accept', 'application/json') .end(function(res){ if (res.ok) { alert('yay got ' + JSON.stringify(res.body)); } else { alert('Oh no! error ' + res.text); } });

測試文檔

這個連接文檔，是用Mocha’s文檔自動輸出的,下面提供了這個測試文檔對應的源文件

請求基礎

一個請求的初始化能夠用請求對象裏合適的方法來執行，而後調用end()來發送請求,下面是一個簡單的get請求

 request .get('/search') .end(function(res){ });

請求方法也能夠經過參數傳遞:

request('GET', '/search').end(callback);

node客戶端也容許提供絕對路徑:

 request .get('http://example.com/search') .end(function(res){ });

delete,head,post,put和別的http動做均可以使用,來換個方法看看:

request .head('/favicon.ico') .end(function(res){ });

delete是一個特列,由於它是系統保留的關鍵字,因此應該用.del()這個名字:

request .del('/user/1') .end(function(res){ });

http請求默認的方法爲get,因此就像你看到的,下面的這個例子也是可用的:

request('/search', function(res){ });

設置頭字段

設置頭字段很是簡單，只需調用.set()方法，傳遞一個名稱和值就行:

request .get('/search') .set('API-Key', 'foobar') .set('Accept', 'application/json') .end(callback);

你也能夠直接傳遞一個對象進去，這樣一次就能夠修改多個頭字段:

 request .get('/search') .set({ 'API-Key': 'foobar', Accept: 'application/json' }) .end(callback);

Get請求

當使用get請求傳遞查詢字符串的時候，用.query()方法,傳遞一個對象就能夠,下面的代碼將產生一個/search?query=Manny&range=1..5&order=desc請求:

 request .get('/search') .query({ query: 'Manny' }) .query({ range: '1..5' }) .query({ order: 'desc' }) .end(function(res){ });

或者傳一個單獨的大對象:

request .get('/search') .query({ query: 'Manny', range: '1..5', order: 'desc' }) .end(function(res){ });

.query()方法也容許傳遞字符串:

request .get('/querystring') .query('search=Manny&range=1..5') .end(function(res){ });

或者字符串拼接:

request .get('/querystring') .query('search=Manny') .query('range=1..5') .end(function(res){ });

POST/PUT請求

一個典型的json post請求看起來就像下面的那樣，設置一個合適的Content-type頭字段，而後寫入一些數據，在這個例子裏只是json字符串:

request.post('/user') .set('Content-Type', 'application/json') .send('{"name":"tj","pet":"tobi"}') .end(callback)

由於json很是通用，因此就做爲默認的Content-type,下面的例子跟上面的同樣:

request.post('/user') .send({ name: 'tj', pet: 'tobi' }) .end(callback)

或者調用屢次.send()方法:

request.post('/user') .send({ name: 'tj' }) .send({ pet: 'tobi' }) .end(callback)

默認發送字符串，將設置Content-type爲application/x-www-form-urlencoded,屢次調用將會經過&來鏈接，這裏的結果爲name=tj&pet=tobi:

request.post('/user') .send('name=tj') .send('pet=tobi') .end(callback);

superagent的請求數據格式化是能夠擴展的，不過默認支持form和json兩種格式,想發送數據以application/x-www-form-urlencoded類型的話，則能夠簡單的調用.type()方法傳遞form參數就行，這裏默認是json,下面的請求將會postname=tj&pet=tobi內容:

request.post('/user') .type('form') .send({ name: 'tj' }) .send({ pet: 'tobi' }) .end(callback)

注意:form是form-data和urlencoded的別名,爲了向後兼容

設置Content-Type

常見的方案是使用.set()方法:

 request.post('/user') .set('Content-Type', 'application/json')

一個簡便的方法是調用.type()方法，傳遞一個規範的MIME名稱，包括type/subtype,或者一個簡單的後綴就像xml,json,png這樣，例如:

 request.post('/user') .type('application/json') request.post('/user') .type('json') request.post('/user') .type('png')

設置接受類型

跟.type()簡便方法同樣，這裏也能夠調用.accept()方法來設置接受類型，這個值將會被request.types所引用，支持傳遞一個規範的MIME名稱，包括type/subtype,或者一個簡單的後綴就像xml,json,png這樣,例如:

request.get('/user') .accept('application/json') request.get('/user') .accept('json') request.get('/user') .accept('png')

查詢字符串

當用.send(obj)方法來發送一個post請求，而且但願傳遞一些查詢字符串，能夠調用.query()方法,好比向?format=json&dest=/login發送post請求:

request .post('/') .query({ format: 'json' }) .query({ dest: '/login' }) .send({ post: 'data', here: 'wahoo' }) .end(callback);

解析響應內容

superagent會解析一些經常使用的格式給請求者，當前支持application/x-www-form-urlencoded,application/json,multipart/form-data.

JSON/Urlencoded

res.body是解析後的內容對象,好比一個請求響應'{"user":{"name":"tobi"}}'字符串,res.body.user.name將會返回tobi,一樣的，x-www-form-urlencoded格式的user[name]=tobi解析完的值，也是同樣的.

Multipart

nodejs客戶端經過Formidable模塊來支持multipart/form-data類型,當解析一個multipart響應時,res.files屬性就能夠用.假設一個請求響應下面的數據:

--whoop Content-Disposition: attachment; name="image"; filename="tobi.png" Content-Type: image/png ... data here ... --whoop Content-Disposition: form-data; name="name" Content-Type: text/plain Tobi --whoop--

你將能夠獲取到res.body.name名爲’Tobi’,res.files.image爲一個file對象,包括一個磁盤文件路徑，文件名稱，還有其它的文件屬性.

響應屬性

響應通常會提供不少有用的標識以及屬性,都在response對象裏，按照respone.text,解析後的response.body,頭字段，一些標識的順序來排列.

Response text

res.text包含未解析前的響應內容，通常只在mime類型可以匹配text/,json,x-www-form-urlencoding的狀況下，默認爲nodejs客戶端提供,這是爲了節省內存.由於當響應以文件或者圖片大內容的狀況下影響性能.

Response body

跟請求數據自動序列化同樣，響應數據也會自動的解析，當爲一個Content-Type定義一個解析器後，就能自動解析，默認解析包含application/json和application/x-www-form-urlencoded,能夠經過訪問res.body來訪問解析對象.

Response header fields

res.header包含解析以後的響應頭數據,鍵值都是node處理成小寫字母形式，好比res.header['content-length'].

Response Content-Type

Content-Type響應頭字段是一個特列，服務器提供res.type來訪問它，默認res.charset是空的,若是有的話，則自動填充，例如Content-Type值爲text/html; charset=utf8,則res.type爲text/html,res.charst爲utf8.

Response status

響應狀態標識能夠用來判斷請求是否成功，除此以外，能夠用superagent來構建理想的restful服務器,這些標識目前定義爲:

var type = status / 100 | 0; // status / class res.status = status; res.statusType = type; // basics res.info = 1 == type; res.ok = 2 == type; res.clientError = 4 == type; res.serverError = 5 == type; res.error = 4 == type || 5 == type; // sugar res.accepted = 202 == status; res.noContent = 204 == status || 1223 == status; res.badRequest = 400 == status; res.unauthorized = 401 == status; res.notAcceptable = 406 == status; res.notFound = 404 == status; res.forbidden = 403 == status;

停止請求

能夠經過req.abort()來停止請求.

請求超時

能夠經過req.timeout()來定義超時時間,而後當超時錯誤發生時，爲了區別於別的錯誤,err.timeout屬性被定義爲超時時間,注意,當超時錯誤發生後，後續的請求都會被重定向.不是每一個請求.

基礎驗證

nodejs客戶端能夠經過兩種方式來達到驗證的目的,第一個是傳遞一個像這樣的url,user:pass:

request.get('http://tobi:learnboost[@local](/user/local)').end(callback);

第二種是調用.auth()方法:

request .get('http://local') .auth('tobo', 'learnboost') .end(callback);

跟隨重定向

默認是向上跟隨5個重定向，不過能夠經過調用.res.redirects(n)來設置個數:

request .get('/some.png') .redirects(2) .end(callback);

管道數據

nodejs客戶端容許使用一個請求流來輸送數據,好比請求一個文件做爲輸出流:

var request = require('superagent') , fs = require('fs'); var stream = fs.createReadStream('path/to/my.json'); var req = request.post('/somewhere'); req.type('json'); stream.pipe(req);

或者輸送一個響應流到文件中:

var request = require('superagent') , fs = require('fs'); var stream = fs.createWriteStream('path/to/my.json'); var req = request.get('/some.json'); req.pipe(stream);

複合請求

superagent用來構建複合請求很是不錯,提供了低級和高級的api方法.

低級的api是使用多個部分來表現一個文件或者字段，.part()方法返回一個新的部分,提供了跟request自己類似的api方法.

var req = request.post('/upload'); req.part() .set('Content-Type', 'image/png') .set('Content-Disposition', 'attachment; filename="myimage.png"') .write('some image data') .write('some more image data'); req.part() .set('Content-Disposition', 'form-data; name="name"') .set('Content-Type', 'text/plain') .write('tobi'); req.end(callback);

附加文件

上面說起的高級api方法，能夠通用.attach(name, [path], [filename])和.field(name, value)這兩種形式來調用.添加多個附件也比較簡單，只須要給附件提供自定義的文件名稱,一樣的基礎名稱也要提供.

request .post('/upload') .attach('avatar', 'path/to/tobi.png', 'user.png') .attach('image', 'path/to/loki.png') .attach('file', 'path/to/jane.png') .end(callback);

字段值

跟html的字段很像,你能夠調用.field(name,value)方法來設置字段,假設你想上傳一個圖片的時候帶上本身的名稱和郵箱，那麼你能夠像下面寫的那樣:

 request .post('/upload') .field('user[name]', 'Tobi') .field('user[email]', 'tobi[@learnboost](/user/learnboost).com') .attach('image', 'path/to/tobi.png') .end(callback);

壓縮

nodejs客戶端自己就提供了壓縮響應內容，因此你不須要作任何其它事情.

緩衝響應

爲了強迫緩衝res.text這樣的響應內容,能夠調用req.buffer()方法,想取消默認的文本緩衝響應像text/plain,text/html這樣的，能夠調用req.buffer(false)方法

當緩衝res.buffered標識提供了，那麼就能夠在一個回調函數裏處理緩衝和沒緩衝的響應.

跨域資源共享

.withCredentials()方法能夠激活發送原始cookie的能力,不過只有在Access-Control-Allow-Origin不是一個通配符(*),而且Access-Control-Allow-Credentials爲’true’的狀況下才行.

request .get('http://localhost:4001/') .withCredentials() .end(function(res){ assert(200 == res.status); assert('tobi' == res.text); next(); })

異常處理

當發送錯誤時，superagent首先會檢查回調函數的參數數量,當err參數提供的話，參數就是兩個,以下:

request .post('/upload') .attach('image', 'path/to/tobi.png') .end(function(err, res){ });

當省略了回調函數,或者回調只有一個參數的話,能夠添加error事件的處理.

request .post('/upload') .attach('image', 'path/to/tobi.png') .on('error', handle) .end(function(res){ });

注意:superagent默認狀況下,對響應4xx和5xx的認爲不是錯誤,例如當響應返回一個500或者403的時候,這些狀態信息能夠經過res.error,res.status和其它的響應屬性來查看,可是沒有任務的錯誤對象會傳遞到回調函數裏或者emit一個error事件.正常的error事件只會發生在網絡錯誤,解析錯誤等.

當產生一個4xx或者5xx的http錯誤響應,res.error提供了一個錯誤信息的對象，你能夠經過檢查這個來作某些事情.

if (res.error) { alert('oh no ' + res.error.message); } else { alert('got ' + res.status + ' response'); }

譯者序

superagent是一個很是實用的http代理模塊,推薦你們使用.