> # SuperAgent
> SuperAgent是輕量級漸進式ajax API，相比于現有的請求API，它更加靈活，可讀，且學習成本低。 同樣它也適用于Node.js！
>
> ```
> request
> .post('/api/pet')
> .send({ name: 'Manny', species: 'cat' })
> .set('X-API-Key', 'foobar')
> .set('Accept', 'application/json')
> .then(function(res) {
> alert('yay got ' + JSON.stringify(res.body));
> });
> ```
> ## 測試文檔
> 以下 [測試文檔](docs/test.html) 是由[Mocha's](http://mochajs.org/) "doc" 記錄生成的，直接反映了測試套件。 這提供了額外的文檔來源。
>
> ## 基礎請求
> 請求可以通過調用 `request` 對象的適當方法來啟動，然后調用`.then()` (or `.end()` [or `await`](#promise-and-generator-support)) 來發送請求，例如一個簡單的GET請求:
>
> ```
> request
> .get('/search')
> .then(function(res) {
> // res.body, res.headers, res.status
> })
> .catch(function(err) {
> // err.message, err.response
> });
> ```
> HTTP 方法也可以使用字符串:
>
> ```
> request('GET', '/search').then(success, failure);
> ```
> 舊的回調依舊可以使用。 將 `.then()` **替換成** `.end()` ：
>
> ```
> request('GET', '/search').end(function(err, res){
> if (res.ok) {}
> });
> ```
> 可以使用絕對URL。 在Web瀏覽器中，絕對URL只在服務器實現 [CORS](#cors) 的情況下才起作用。
>
> ```
> request
> .get('http://example.com/search')
> .then(function(res) {
>
> });
> ```
> **Node** 客戶端支持向 [Unix域套接字](http://en.wikipedia.org/wiki/Unix_domain_socket) 發送請求:
>
> ```
> // pattern: https?+unix://SOCKET_PATH/REQUEST_PATH
> // Use `%2F` as `/` in SOCKET_PATH
> request
> .get('http+unix://%2Fabsolute%2Fpath%2Fto%2Funix.sock/search')
> .then(res => {
>
> });
> ```
> **DELETE** , **HEAD** , **PATCH** , **POST** , 和 **PUT** 請求方法依舊可以使用, 只需要修改一下方法名即可：
>
> ```
> request
> .head('/favicon.ico')
> .then(function(res) {
>
> });
> ```
> **DELETE** 也可以被稱為`.del()`與舊的IE兼容，其中`delete`是一個保留字。
>
> HTTP 方法默認是 **GET**，所以下面的寫法也是可以的:
>
> ```
> request('/search', function(err, res){
>
> });
> ```
> ## 設置 header 字段
> 設置標題字段很簡單，用字段名和值調用 `.set()`:
>
> ```
> request
> .get('/search')
> .set('API-Key', 'foobar')
> .set('Accept', 'application/json')
> .then(callback);
> ```
> 你也可以傳遞一個對象來在一次調用中設置幾個字段:
>
> ```
> request
> .get('/search')
> .set({ 'API-Key': 'foobar', Accept: 'application/json' })
> .then(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' })
> .then(function(res) {
>
> });
> ```
> 或者用一個對象包裹:
>
> ```
> request
> .get('/search')
> .query({ query: 'Manny', range: '1..5', order: 'desc' })
> .then(function(res) {
>
> });
> ```
> `.query()` 方法同樣可以接收字符串的形式:
>
> ```
> request
> .get('/querystring')
> .query('search=Manny&range=1..5')
> .then(function(res) {
>
> });
> ```
> 或者如下這樣:
>
> ```
> request
> .get('/querystring')
> .query('search=Manny')
> .query('range=1..5')
> .then(function(res) {
>
> });
> ```
> ## `HEAD` 請求
> 對于 HEAD 請求你依舊可以使用 `.query()` 方法。下面的 `.query()` 參數將會拼接成 `/users?email=joe@smith.com`。
>
> ```
> request
> .head('/users')
> .query({ email: 'joe@smith.com' })
> .then(function(res) {
>
> });
> ```
> ## `POST` / `PUT` 請求
> 一個典型的JSON **POST** 請求可能看起來有點像下面這樣，我們適當地設置 Content-Type 頭字段，并“寫”一些數據，在這種情況下，只是一個JSON字符串。
>
> ```
> request.post('/user')
> .set('Content-Type', 'application/json')
> .send('{"name":"tj","pet":"tobi"}')
> .then(callback)
> ```
> JSON無疑是最常見的，這就是 _默認的_ ！ 下面的例子等同于前面的例子
>
> ```
> request.post('/user')
> .send({ name: 'tj', pet: 'tobi' })
> .then(callback)
> ```
> 或調用多次 `.send()`:
>
> ```
> request.post('/user')
> .send({ name: 'tj' })
> .send({ pet: 'tobi' })
> .then(callback)
> ```
> 默認情況下，發送字符串將把 Content-Type 設置為 `application / x-www-form-urlencoded` ，多個調用將與`＆`連接在一起，這里生成`name = tj＆pet = tobi`：
>
> ```
> request.post('/user')
> .send('name=tj')
> .send('pet=tobi')
> .then(callback);
> ```
> SuperAgent 格式是可擴展的，但默認支持 "json" 和 "form"。 要以 `application / x-www-form-urlencoded` 方式發送數據，只需使用 "form" 調用 `.type()`，默認為“json”。 這個請求將 POST 的 body拼接成“名稱= tj＆pet = tobi"。
>
> ```
> request.post('/user')
> .type('form')
> .send({ name: 'tj' })
> .send({ pet: 'tobi' })
> .then(callback)
> ```
> 發送一個 [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData) 格式的數據也是支持的。以下示例將 **POST** 標識為 id =“myForm” 的HTML表單的內容。
>
> ```
> request.post('/user')
> .send(new FormData(document.getElementById('myForm')))
> .then(callback)
> ```
> ## 設置 `Content-Type`
> `.set()` 方法也是經常使用的:
>
> ```
> request.post('/user')
> .set('Content-Type', 'application/json')
> ```
> 作為一個簡短方式， `.type()` 方法也是可用的，它接受規范化的 MIME 類型名稱完整的類型/子類型，或簡單的擴展名稱，如“xml”，“json”，“png”:
>
> ```
> request.post('/user')
> .type('application/json')
>
> request.post('/user')
> .type('json')
>
> request.post('/user')
> .type('png')
> ```
> ## 序列化請求正文
> SuperAgent會自動序列化JSON和表單。 如果要以自定義格式發送有效內容，則可以使用 `.serialize()`方法替換內置序列化。
>
> ## 重試請求
> 當給定 `.retry()` 方法時，SuperAgent 會自動重試請求，如果它們以短暫的失敗或可能是由于Internet連接造成的。
>
> 此方法有兩個可選參數：重試次數（默認值3）和回調。 它在每次重試之前調用 `callback(err，res)`。 回調可能返回 `true` /`false` 來控制請求是否被重試（但總是應用最大重試次數）。
>
> ```
> request
> .get('http://example.com/search')
> .retry(2) // or:
> .retry(2, callback)
> .then(finished);
> ```
> 僅對 _冪等_ 的請求使用 `.retry()` 。
>
> ## 設置 Accept
> 類似于 `.type()` 方法，也可以通過簡短的方法 `.accept()` 來設置 `Accept` 頭。`request.types` 還允許您指定完整的規范化 MIME 類型名稱為`type/subtype`，或者擴展后綴形式為“xml”，“json”，“png”:
>
> ```
> request.get('/user')
> .accept('application/json')
>
> request.get('/user')
> .accept('json')
>
> request.post('/user')
> .accept('png')
> ```
> ### Facebook 和 Accept JSON
> 如果你正在調用 Facebook 的API，請確保在您的請求中發送 "Accept:application/json" 頭。 如果你不這樣做，Facebook 會用`Content-Type：text / javascript; charset = UTF-8`，SuperAgent 將不會解析，因此 `res.body` 將是未定義的。 你可以用 `req.accept('json')` 或`req.header('Accept'，'application / json')` 來做到這一點。 有關詳細信息，請參見 [issues1078](https://github.com/visionmedia/superagent/issues/1078)。
>
> ## 查詢字符串
> `req.query(obj)` 是一個可以用來建立一個查詢字符串的方法。 例如，在 **POST** 上填充 `？format = json＆dest = / login`：
>
> ```
> request
> .post('/')
> .query({ format: 'json' })
> .query({ dest: '/login' })
> .send({ post: 'data', here: 'wahoo' })
> .then(callback);
> ```
> 默認情況下，查詢字符串不會以任何特定的順序組裝的。 asciibetically-sorted 排序的查詢字符串可以用`req.sortQuery()` 來啟用。 你也可以用 `req.sortQuery(myComparisonFn)` 提供一個自定義的排序比較函數。 比較函數應該帶2個參數并返回一個負/零/正整數。
>
> ```js
> // default order
> request.get('/user')
> .query('name=Nick')
> .query('search=Manny')
> .sortQuery()
> .then(callback)
>
> // customized sort function
> request.get('/user')
> .query('name=Nick')
> .query('search=Manny')
> .sortQuery(function(a, b){
> return a.length - b.length;
> })
> .then(callback)
> ```
>
> ## TLS 選項
> 在 Node.js 中，SuperAgent 支持配置 HTTPS 請求的方法：
>
> * `.ca()`: 將CA證書設置為信任
> * `.cert()`: 設置客戶端證書鏈
> * `.key()`: 設置客戶端私鑰
> * `.pfx()`: 設置客戶端PFX或PKCS12編碼的私鑰和證書鏈
>
> 更多信息，請看 Node.js [https.request docs](https://nodejs.org/api/https.html#https_https_request_options_callback).
>
> ```js
> var key = fs.readFileSync('key.pem'),
> cert = fs.readFileSync('cert.pem');
>
> request
> .post('/client-auth')
> .key(key)
> .cert(cert)
> .then(callback);
> ```
>
> ```js
> var ca = fs.readFileSync('ca.cert.pem');
>
> request
> .post('https://localhost/private-ca-server')
> .ca(ca)
> .then(res => {});
> ```
>
> ## 解析響應主體
> SuperAgent 將為你解析已知的響應主體數據，目前支持 `application / x-www-form-urlencoded`，`application / json` 和 `multipart / form-data`。
>
> 您可以使用 `.buffer(true).parse(fn)` 方法設置自定義解析器（優先于內置解析器）。 如果沒有啟用響應緩沖 (`.buffer（false）`），那么 `response` 事件將不會等待 body 解析完成，所以 `response.body` 將不可用。
>
> ### JSON / Urlencoded
> 例如，如果請求用JSON字符串 “{”user“：{”name“：”tobi“}}” 響應，那么 `res.body.user.name` 就是解析對象就是“tobi”。同樣，“user [name] = tobi”的x-www-form-urlencoded值也會產生相同的結果。 只支持一個嵌套級別。 如果您需要更復雜的數據，請發送JSON。
>
> 通過重復key發送數組。 `.send({color：['red'，'blue']})` 發送 `color = red＆color = blue`。 如果你想讓數組 key 在它們的名字中包含`[]`，你必須自己添加它，因為SuperAgent不會自動添加它。
>
> ### Multipart
> Node客戶端通過 [Formidable](https://github.com/felixge/node-formidable) 模塊支持 _multipart / form-data_ 。 當解析多部分響應時，對象 `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”對象。
>
> ### 二進制
> 在瀏覽器中，你可以使用 `.responseType('blob')` 來請求處理二進制響應主體。 在 node.js 中運行時，此API不是必要的。 這個方法支持的參數值是
>
> * `blob` 傳遞給 XmlHTTPRequest `responseType` 屬性
> * `arraybuffer' 傳遞給 XmlHTTPRequest `responseType` 屬性
>
> ```js
> req.get('/binary.data')
> .responseType('blob')
> .end(function (error, res) {
> // res.body will be a browser native Blob type here
> });
> ```
>
> 更多內容請看 Mozilla Developer Network [xhr.responseType docs](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/responseType)。
>
> ## 響應屬性
> 響應對象設置了許多有用的標志和屬性，包括響應文本，解析的響應主體，標題字段，狀態標志等等。
>
> ### 響應文本
> `res.text` 屬性包含未解析的響應正文字符串。 此屬性始終為客戶端API提供，并且僅當默認情況下mime類型與節點默認匹配“text / _”，“_ / json”或“x-www-form-urlencoded”時。 其原因是為了節省內存，因為諸如多部分文件或圖像的大型文本的緩存文本是非常低效的。 要強制緩存請參閱 “緩存響應” 部分。
>
> ### 響應體
> 與 SuperAgent 可以自動序列化請求數據一樣，它也可以自動解析它。 當為 Content-Type 定義一個解析器時，它將被解析，默認包含 “application / json” 和 “application / x-www-form-urlencoded” 。 解析的對象然后可以通過 `res.body` 獲得。
>
> ### 響應頭字段
> `res.header`包含一個解析的頭部字段的對象，和節點一樣壓縮字段名稱。 例如 `res.header ['content-length']`。
>
> ### 響應類型
> Content-Type 響應頭是特殊的，提供 `res.type`，這是沒有字符集（如果有的話）。 例如，“text / html; charset = utf8” 的 Content-Type 將提供“text / html”作為“res.type”，然后“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({deadline:ms})` 或 `req.timeout(ms)`（其中`ms`是毫秒數> 0）為整個請求（包括所有重定向）設置完成的最后期限.。如果在這段時間內沒有完全下載響應，請求將被中止。
> * `req.timeout({response:ms})` 設置等待來自服務器的第一個字節的最大時間, 但并不限制整個下載可以花費多長時間。響應超時應比服務器響應所需的時間要長數秒，因為它還包括進行DNS查找，TCP / IP和TLS連接的時間。
>
> 你應該使用 `deadline` 和 `response` 超時。 通過這種方式，你可以使用短暫的響應超時來快速檢測到無響應的網絡，并且可以在較慢的但可靠的網絡上為下載提供時間。
>
> ```
> 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.
> })
> .then(function(res) {
> if (err.timeout) { /* timed out! */ }
> });
> ```
> 超時錯誤具有 `.timeout` 屬性。
>
> ## 認證
> 在 Node 和瀏覽器中，通過 `.auth()` 方法提供的 auth 可用：
>
> ```
> request
> .get('http://local')
> .auth('tobi', 'learnboost')
> .then(callback);
> ```
> 在 _Node_ 客戶端中，基本身份驗證可以在URL中作為“user：pass”：
>
> ```
> request.get('http://tobi:learnboost@local').then(callback);
> ```
> 默認情況下只使用 `Basic` auth。 在瀏覽器中，你可以添加 `{type：'auto'} 來啟用瀏覽器內置的所有方法（Digest，NTLM等）：
>
> ```
> request.auth('digest', 'secret', {type:'auto'})
> ```
> ## 重定向 (Following redirects)
> 默認情況下最多會有5個重定向，但是你可以用 `res.redirects(n)` 方法指定：
>
> ```
> request
> .get('/some.png')
> .redirects(2)
> .then(callback);
> ```
> ## 代理全局狀態
> ### 保存cookies
> 在Node中，SuperAgent 默認不保存 cookie，但是你可以使用 `.agent()` 方法創建一個保存 cookie 的SuperAgent 副本。 每個副本都有一個單獨的 cookie 。
>
> ```
> const agent = request.agent();
> agent
> .post('/login')
> .then(() => {
> return agent.get('/cookied-page');
> });
> ```
> 在瀏覽器中，Cookie 由瀏覽器自動管理，因此 `.agent()` 不會隔離cookie。
>
> ### 多個請求的默認選項
> 代理程序上調用的常規請求方法 (`.use()`，`.set()`，`.auth()`)將用作該代理程序發出的所有請求的默認值。
>
> ```
> const agent = request.agent()
> .use(plugin)
> .auth(shared);
>
> await agent.get('/with-plugin-and-auth');
> await agent.get('/also-with-plugin-and-auth');
> ```
> ## 管道數據
> Node客戶端允許您將數據傳入和傳出請求。 例如，傳遞一個文件的內容作為請求：
>
> ```
> const request = require('superagent');
> const fs = require('fs');
>
> const stream = fs.createReadStream('path/to/my.json');
> const req = request.post('/somewhere');
> req.type('json');
> stream.pipe(req);
> ```
> 請注意，當您管道請求時，superagent 會使用 [chunked transfer encoding](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) 發送管道數據，而不是所有服務器都支持（例如，Python WSGI服務器）。
>
> 或者將響應傳遞給一個文件：
>
> ```
> const stream = fs.createWriteStream('path/to/my.json');
> const req = request.get('/some.json');
> req.pipe(stream);
> ```
> 請注意，您應該 **不** 嘗試管道 `.end()` 或 `Response` 對象的結果：
>
> ```
> // Don't do either of these:
> const stream = getAWritableStream();
> const req = request
> .get('/some.json')
> // this pipes garbage to the stream and fails in unexpected ways
> .end((err, response) => response.pipe(stream))
> const req = request
> .get('/some.json')
> .end()
> // this is also unsupported, .pipe calls .end for you.
> .pipe(stream);
> ```
> 在superagent的 [未來版本](https://github.com/visionmedia/superagent/issues/1188) 中，不正確地調用`pipe（）`將會失敗。
>
> ## 多部分請求
> SuperAgent 對于提供 `.attach()` 和 `.field()` 方法的 _building_ 多部分請求也非常給力。
>
> 當你使用 `.field()` 或者 `.attach()` 時，你不能使用 `.send()` 而你 _不能_ 設置 'Content-Type'（正確的類型將會被(自動)設置）。
>
> ### 發送文件
> 要發送文件，請使用 `.attach(name, [file], [options])`。 您可以通過多次調用 `.attach` 來附加多個文件。 參數是：
>
> * `name` — 表單字段名稱
> * `file` — 帶有文件路徑的字符串或者“Blob”/“Buffer”對象
> * `options` — (可選) 用自定義文件名字符串或者“{filename：string}”對象。 在Node中，還支持`{contentType：'mime / type'}`。 在瀏覽器中，用相應的類型創建一個“Blob”。
>
>
> ```
> request
> .post('/upload')
> .attach('image1', 'path/to/felix.jpeg')
> .attach('image2', imageBuffer, 'luna.jpeg')
> .field('caption', 'My cats')
> .then(callback);
> ```
> ### 字段值
> 就像HTML中的表單字段一樣，你可以用 `.field(name，value)` 和 `.field（{name：value}）` 來設置字段值。 假設你想用你的名字和電子郵件上傳幾張圖片，你的請求可能是這樣的：
>
> ```
> request
> .post('/upload')
> .field('user[name]', 'Tobi')
> .field('user[email]', 'tobi@learnboost.com')
> .field('friends[]', ['loki', 'jane'])
> .attach('image', 'path/to/tobi.png')
> .then(callback);
> ```
> ## 壓縮
> 節點客戶端支持壓縮響應，最重要的是，你不必做任何事情！它能用。
>
> ## 緩存響應
> 要強制緩存響應主體為 `res.text`，你可以調用 `req.buffer()`。 要撤消文本響應的默認緩存，例如 “text / plain”，“text / html”等，你可以調用 `req.buffer(false)`。
>
> 當緩沖提供 `res.buffered` 標志時，你可以使用它來處理同一個回調中的緩存和無緩存響應。
>
> ## CORS
> 出于安全原因，瀏覽器將阻止跨源請求，除非服務器選擇使用CORS標頭。 瀏覽器也會做額外的
> **OPTIONS** 請求來檢查服務器允許的HTTP頭和方法。 [閱讀更多關于CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS)。
>
> The `.withCredentials()` method enables the ability to send cookies from the origin, however only when `Access-Control-Allow-Origin` is _not_ a wildcard ("_"), and `Access-Control-Allow-Credentials` is "true". `.withCredentials（）`方法使得能夠從源站發送cookie，但是只有當'Access-Control-Allow-Origin'不是通配符（“_”）和`Access-Control-Allow-Credentials` 是 "true”時。
>
> ```
> request
> .get('http://api.example.com:4001/')
> .withCredentials()
> .then(function(res) {
> assert.equal(200, res.status);
> assert.equal('tobi', res.text);
> })
> ```
> ## 錯誤處理
> 你的回調函數將始終傳遞兩個參數：錯誤和響應。 如果沒有錯誤發生，第一個參數將為null：
>
> ```
> request
> .post('/upload')
> .attach('image', 'path/to/tobi.png')
> .then(function(res) {
>
> });
> ```
> 當你監聽的時候，"error" 事件將被觸發:
>
> ```
> request
> .post('/upload')
> .attach('image', 'path/to/tobi.png')
> .on('error', handle)
> .then(function(res) {
>
> });
> ```
> 請注意，**superagent默認考慮 4xx 和 5xx 響應（以及未處理的 3xx 響應）錯誤**。 例如，如果你得到一個`304 Not modified`，`403 Forbidden`或`500 Internal server error`的響應，這個狀態信息可以通過`err.status`獲得。 來自這樣的響應的錯誤還包含具有在 “[響應屬性](%EF%BC%83%E5%93%8D%E5%BA%94%E5%B1%9E%E6%80%A7)” 中提及的所有屬性的“err.response”字段。 庫以這種方式處理想要成功響應和將HTTP錯誤狀態碼視為錯誤的常見情況，同時仍允許圍繞特定錯誤條件的定制邏輯。
>
> 網絡故障，超時以及其他不產生響應的錯誤將不包含“err.status”或“err.response”字段。
>
> 如果你希望處理404或其他HTTP錯誤響應，則可以查詢“err.status”屬性。 當發生HTTP錯誤（4xx或5xx響應）時，`res.error`屬性是一個`Error`對象，這允許你執行如下檢查：
>
> ```
> if (err && err.status === 404) {
> alert('oh no ' + res.body.message);
> }
> else if (err) {
> // all other error types we handle generically
> }
> ```
> 或者，您可以使用`.ok（callback）`方法來決定響應是否是錯誤的。 如果響應應該被解釋為成功，則對“ok”函數的回調將得到一個響應并返回“true”。
>
> ```
> request.get('/404')
> .ok(res => res.status < 500)
> .then(response => {
> // reads 404 page as a successful response
> })
> ```
> ## 進度跟蹤
> SuperAgent在上傳和下載大文件時觸發“progress”事件。
>
> ```
> request.post(url)
> .attach('field_name', file)
> .on('progress', event => {
> /* the event is:
> {
> direction: "upload" or "download"
> percent: 0 to 100 // may be missing if file size is unknown
> total: // total file size, may be missing
> loaded: // bytes downloaded or uploaded so far
> } */
> })
> .end()
> ```
> ## Promise 和 Generator 支持
> SuperAgent 的請求是一個“可接受的”對象，它與 JavaScript promise 和 `async` /`await` 語法兼容。 如果你使用promises，請勿調用 `.end()` 。
>
> 像 [co](https://github.com/tj/co) 這樣的庫或 [koa](https://github.com/koajs/koa) 這樣的 web 框架可以在任何 SuperAgent 方法上 "yield" :
>
> ```
> const req = request
> .get('http://local')
> .auth('tobi', 'learnboost');
> const res = yield req;
> ```
> 請注意，SuperAgent 期望全局 `Promise` 對象存在。 您需要在 Internet Explorer 或 Node.js 0.10 中使用 polyfill 來使用 promise 。
>
> ## 瀏覽器和節點版本
> SuperAgent 有兩個實現：一個用于Web瀏覽器（使用XHR），一個用于Node.JS（使用核心http模塊）。 默認情況下，Browserify和WebPack將選擇瀏覽器版本。
>
> 如果要使用WebPack編譯Node.JS的代碼，您必須在其配置中指定[node target](https://webpack.github.io/docs/configuration.html#target)。
>
> ### 在 electron 中使用瀏覽器版本
> [Electron](http://electron.atom.io/) 開發人員報告，如果您希望使用瀏覽器版本的 SuperAgent 而不是Node版本，則可以使用 `require（'superagent / superagent'）`。 您的請求現在將顯示在Chrome開發人員工具“網絡”標簽中。 請注意，此環境不包含在自動化測試套件中，并且不受官方支持。
