KOA 學習（六）superAgent

原文地址 http://www.2cto.com/kf/201611/569080.html

基本請求

初始化一個請求能夠經過調用request模塊中適當的方法，而後使用.end()來發送請求，例如一個簡單的GET請求：

request
    .get('/search')
    .end(function(err, res){ 
 })；

一個方法字符串也是容許的：

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

支持ES6，可使用.then()來代替.end()

request('GET', '/search').then(success, failure);

DELETE, HEAD, POST, PUT以及其餘HTTP請求均可使用，只須要簡單的改變方法名稱：

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

DELETE是特殊的保留字段，方法命名爲.del():

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

HTTP方法默認爲GET，若是你想如此，如下示例是有效的：

request('/search', function(err, 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請求

.query()方法接受對象，當使用GET方法時將生成查詢串，如下示例將生成路徑/search?query=Manny&range=1..5&order=desc。

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

或使用一個簡單對象：

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

.query()方法也接受字符串：

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

HEAD請求

你也可使用.query()方法來進行HEAD請求，如下示例將生成路徑/users?email=joe@smith.com

request 
  .head('/users')
  .query({ email: 'joe@smith.com' }) 
  .end(function(err, res){  
  });

POST/PUT請求

一個典型的JSON POST請求有點像如下示例，咱們適當的設置Content-Type頭字段，而且」寫」一些數據，在此時只是一個JSON字符串

request
  .post('/user') 
  .set('Content-Type', 'application/json') 
  .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格式是可擴展的，但支持默認」json」和」form」，發送相似application/x-www-form-urlencoded的數據只須要調用」form」的.type()，這裏默認是」json」,這種請求將會POST」name=tj&pet=tobi」

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

設置Content-Type

以前的結論是使用.set()方法

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

type()方法也可用於速記，接受規範化使用type/subtype完成的MIME類型名稱，或簡單的擴展名稱例如」xml」,」json」,」png」等等：

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

序列化請求結構

SuperAgent會自動序列化JSON和格式，若是你想要再一個傳統格式下發送一個有效載荷，你可使用.serialize()方法替換內置序列化

設置接收

經過速記方法.accept()設置接收頭能夠達成與.type()方法相似的效果，參考request.types容許你指定相似type/subtype的徹底規範化MIME名稱，或延期後綴格式相似」xml」、」json」、」png」：

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

查詢字符串

res.query(obj)方法可被用於創建一個查詢字符串，例如在一個POST中填充?format=json&dest=/login

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.
你可使用.buffer(true).parse(fn)方法設置自定義解析(提高優先級高於創建解析)，若是返回緩衝不可用(.buffer(false))，response事件將發出而不會等待結構解析器結束，所以response.body將不可用

JSON/Urlencoded

res.body屬性是解析對象，例如若是一個請求返回JSON字符串’{「user」:{「name」:」tobi」}}’，res.body.user.name將變爲」tobi」,一樣」user[name]=tobi」的x-www-form-urlencoded值將產生一樣的結果

Multipart

Node客戶端經過Formidable模塊支持multipart/form-data,當解析multipart返回時，對象res.files對你也是可用的，假設例如一個請求響應以下multipart結構：

--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對象，範圍包括返回文本、解析返回結構、頭字段、狀態標誌等

返回文本

res.text屬性包含未解析返回結構字符串，這個屬性會一直由客戶端API提供，而且僅當mime類型匹配」text/」、」/json」或」x-www-form-urlencoded」默認爲節點時，這是爲了保存記憶，大型結構體的緩存文本，例如multipart文件或圖片的效率是很是低的。
強制緩存可查看」緩存返回」部分

返回部分

相似SuperAgent能夠自動序列化請求數據，SuperAgent也能夠解析它，當一個解析器定義Content-Type，他的解析方式默認包含」application/json」和」application/x-www-form-urlencoded」。解析對象經過res.body可用

返回頭字段

res.header包含一個細節頭字段的對象，小寫字段名如節點一致，例如res.header['content-length']

返回Content-Type

Content-Type返回頭是特殊狀況，提供res.type，這是字符集的void(若是有的話),例如Content-Type值爲」text/html; charset=utf8」將提供res.type值爲」text/html」，res.charset屬性將包含」utf8」。

返回狀態

返回狀態標誌幫助決定請求是否成功、包含其餘有用的信息，使得SuperAgent更理想的與RESTful web服務互動，這些標誌當前定義以下：

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(ms)可應用超時，調用以後錯誤將會觸發，爲區分其餘錯誤，err.timeout屬性設置爲ms值。NOTE這是一個超時應用於請求和全部重定向，而不是對應每次請求

request
  .get('/big-file?network=slow')
  .timeout({
    response: 5000,  // Wait 5 seconds for the server to start sending,
    deadline: 60000, // but allow 1 minute for the file to finish loading.
  })
  .end(function(err, res){
    if (err.timeout) { /* timed out! */ }
  });

驗證

在全部Node和瀏覽器經過.auth()方法可用auth:

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

在Node客戶端基礎auth可在URL中」user:pass」字段：

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

默認只有 Basic auth可用，在瀏覽器你能夠添加{type:'auto'}來確保全部方法在瀏覽器(Digest、NTLM等)中創建

request.auth('digest', 'secret', {type:'auto'})

Following重定向

默認超過5個重定向將被followed，可是你可使用res.redirects(n)方法來指定：

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

Piping數據

Node客戶端容許你在請求中pipe傳入傳出數據，例如piping文件的內容做爲請求：

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

或piping返回到一個文件：

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

Multipart 請求

SuperAgent也適用於創建multipart請求，爲此提供了.attach()和.field()方法

附屬文件

如上所述，提供了一種更高級別的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)設置字段值，假設你想上傳一些圖片以及你的名字和email，你的請求能夠像下面這樣：

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

壓縮

node客戶端支持壓縮返回，最好你不須要作任務事，它自己在工做中

CORS

.withCredentials方法確保能夠發送cookies，但僅有當」Access-Control-Allow-Origin」不是通配符時(「*」)，」Access-Control-Allow-Credent-ials」爲」true」

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

錯誤處理

你的回調函數始終傳遞兩個參數：錯誤和返回，若是沒有錯誤發送，第一個參數爲空：

request 
  .post('/upload') 
  .attach('image', 'path/to/tobi.png') 
  .end(function(err, res){
 
  }); 
 
  An "error" event is also emitted, with you can listen for:
 
request 
  .post('/upload') 
  .attach('image', 'path/to/tobi.png') 
  .on('error', handle) 
  .end(function(err, res){ 
 
  });

 

Promise and Generator support

SuperAgent的請求是一個」thenable」對象，它兼容JavaScript語法和async/await句法。
相似co或koa能夠在任何SuperAgent方法中產生：

var res = yield request 
  .get('http://local') 
  .auth('tobi', 'learnboost')

注意SuperAgent指望呈現全局Promise對象，在Internet Explorer或Node.js 0.10中你將須要一個polyfill來使用promises。