[譯] superagent中文使用文檔

<code>superagent</code>是nodejs裡一個非常友善的用戶端請求代理子產品，當你想處理<code>get,post,put,delete,head</code>請求時,你就應該想起該用它了:)

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

一個簡單的post請求，并設定請求頭資訊的例子

一個請求的初始化可以用請求對象裡合适的方法來執行，然後調用<code>end()</code>來發送請求,下面是一個簡單的<code>get</code>請求

請求方法也可以通過參數傳遞:

<code>node</code>用戶端也允許提供絕對路徑:

<code>delete,head,post,put</code>和别的http動作都可以使用,來換個方法看看:

<code>delete</code>是一個特列,因為它是系統保留的關鍵字,是以應該用<code>.del()</code>這個名字:

http請求預設的方法為<code>get</code>,是以就像你看到的,下面的這個例子也是可用的:

設定頭字段非常簡單，隻需調用<code>.set()</code>方法，傳遞一個名稱和值就行:

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

當使用<code>get</code>請求傳遞查詢字元串的時候，用<code>.query()</code>方法,傳遞一個對象就可以,下面的代碼将産生一個<code>/search?query=manny&amp;range=1..5&amp;order=desc</code>請求:

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

<code>.query()</code>方法也允許傳遞字元串:

或者字元串拼接:

一個典型的json post請求看起來就像下面的那樣，設定一個合适的<code>content-type</code>頭字段，然後寫入一些資料，在這個例子裡隻是json字元串:

因為json非常通用，是以就作為預設的<code>content-type</code>,下面的例子跟上面的一樣:

或者調用多次<code>.send()</code>方法:

預設發送字元串，将設定<code>content-type</code>為<code>application/x-www-form-urlencoded</code>,多次調用将會通過<code>&amp;</code>來連接配接，這裡的結果為<code>name=tj&amp;pet=tobi</code>:

superagent的請求資料格式化是可以擴充的，不過預設支援<code>form</code>和<code>json</code>兩種格式,想發送資料以<code>application/x-www-form-urlencoded</code>類型的話，則可以簡單的調用<code>.type()</code>方法傳遞<code>form</code>參數就行，這裡預設是<code>json</code>,下面的請求将會post<code>name=tj&amp;pet=tobi</code>内容:

注意:<code>form</code>是<code>form-data</code>和<code>urlencoded</code>的别名,為了向後相容

常見的方案是使用<code>.set()</code>方法:

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

跟<code>.type()</code>簡便方法一樣，這裡也可以調用<code>.accept()</code>方法來設定接受類型，這個值将會被<code>request.types</code>所引用，支援傳遞一個規範的<code>mime</code>名稱，包括<code>type/subtype</code>,或者一個簡單的字尾就像<code>xml</code>,<code>json</code>,<code>png</code>這樣,例如:

當用<code>.send(obj)</code>方法來發送一個post請求，并且希望傳遞一些查詢字元串，可以調用<code>.query()</code>方法,比如向<code>?format=json&amp;dest=/login</code>發送post請求:

superagent會解析一些常用的格式給請求者，目前支援<code>application/x-www-form-urlencoded</code>,<code>application/json</code>,<code>multipart/form-data</code>.

<code>res.body</code>是解析後的内容對象,比如一個請求響應<code>'{"user":{"name":"tobi"}}'</code>字元串,<code>res.body.user.name</code>将會傳回<code>tobi</code>,同樣的，<code>x-www-form-urlencoded</code>格式的<code>user[name]=tobi</code>解析完的值，也是一樣的.

<code>nodejs</code>用戶端通過<code>formidable</code>子產品來支援<code>multipart/form-data</code>類型,當解析一個<code>multipart</code>響應時,<code>res.files</code>屬性就可以用.假設一個請求響應下面的資料:

你将可以擷取到<code>res.body.name</code>名為'tobi',<code>res.files.image</code>為一個<code>file</code>對象,包括一個磁盤檔案路徑，檔案名稱，還有其它的檔案屬性.

響應一般會提供很多有用的辨別以及屬性,都在<code>response</code>對象裡，按照<code>respone.text</code>,解析後的<code>response.body</code>,頭字段，一些辨別的順序來排列.

<code>res.text</code>包含未解析前的響應内容，一般隻在<code>mime</code>類型能夠比對<code>text/</code>,<code>json</code>,<code>x-www-form-urlencoding</code>的情況下，預設為nodejs用戶端提供,這是為了節省記憶體.因為當響應以檔案或者圖檔大内容的情況下影響性能.

跟請求資料自動序列化一樣，響應資料也會自動的解析，當為一個<code>content-type</code>定義一個解析器後，就能自動解析，預設解析包含<code>application/json</code>和<code>application/x-www-form-urlencoded</code>,可以通過通路<code>res.body</code>來通路解析對象.

<code>res.header</code>包含解析之後的響應頭資料,鍵值都是node處理成小寫字母形式，比如<code>res.header['content-length']</code>.

<code>content-type</code>響應頭字段是一個特列，伺服器提供<code>res.type</code>來通路它，預設<code>res.charset</code>是空的,如果有的話，則自動填充，例如<code>content-type</code>值為<code>text/html; charset=utf8</code>,則<code>res.type</code>為<code>text/html</code>,<code>res.charst</code>為<code>utf8</code>.

響應狀态辨別可以用來判斷請求是否成功，除此之外，可以用superagent來建構理想的<code>restful</code>伺服器,這些辨別目前定義為:

可以通過<code>req.abort()</code>來中止請求.

可以通過<code>req.timeout()</code>來定義逾時時間,然後當逾時錯誤發生時，為了差別于别的錯誤,<code>err.timeout</code>屬性被定義為逾時時間,注意,當逾時錯誤發生後，後續的請求都會被重定向.不是每個請求.

nodejs用戶端可以通過兩種方式來達到驗證的目的,第一個是傳遞一個像這樣的url,<code>user:pass</code>:

第二種是調用<code>.auth()</code>方法:

預設是向上跟随5個重定向，不過可以通過調用<code>.res.redirects(n)</code>來設定個數:

nodejs用戶端允許使用一個請求流來輸送資料,比如請求一個檔案作為輸出流:

或者輸送一個響應流到檔案中:

superagent用來建構複合請求非常不錯,提供了低級和進階的api方法.

低級的api是使用多個部分來表現一個檔案或者字段，<code>.part()</code>方法傳回一個新的部分,提供了跟<code>request</code>本身相似的api方法.

上面提及的進階api方法，可以通用<code>.attach(name, [path], [filename])</code>和<code>.field(name, value)</code>這兩種形式來調用.添加多個附件也比較簡單，隻需要給附件提供自定義的檔案名稱,同樣的基礎名稱也要提供.

跟html的字段很像,你可以調用<code>.field(name,value)</code>方法來設定字段,假設你想上傳一個圖檔的時候帶上自己的名稱和郵箱，那麼你可以像下面寫的那樣:

nodejs用戶端本身就提供了壓縮響應内容，是以你不需要做任何其它事情.

為了強迫緩沖<code>res.text</code>這樣的響應内容,可以調用<code>req.buffer()</code>方法,想取消預設的文本緩沖響應像<code>text/plain</code>,<code>text/html</code>這樣的，可以調用<code>req.buffer(false)</code>方法

當緩沖<code>res.buffered</code>辨別提供了，那麼就可以在一個回調函數裡處理緩沖和沒緩沖的響應.

<code>.withcredentials()</code>方法可以激活發送原始cookie的能力,不過隻有在<code>access-control-allow-origin</code>不是一個通配符(*),并且<code>access-control-allow-credentials</code>為'true'的情況下才行.

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

當省略了回調函數,或者回調隻有一個參數的話,可以添加<code>error</code>事件的處理.

注意:superagent預設情況下,對響應4xx和5xx的認為不是錯誤,例如當響應傳回一個500或者403的時候,這些狀态資訊可以通過<code>res.error</code>,<code>res.status</code>和其它的響應屬性來檢視,但是沒有任務的錯誤對象會傳遞到回調函數裡或者<code>emit</code>一個<code>error</code>事件.正常的<code>error</code>事件隻會發生在網絡錯誤,解析錯誤等.

當産生一個4xx或者5xx的http錯誤響應,<code>res.error</code>提供了一個錯誤資訊的對象，你可以通過檢查這個來做某些事情.

superagent是一個非常實用的http代理子產品,推薦大家使用.