原文：https://hacks.mozilla.org/2015/03/this-api-is-so-fetching

原帖地址：https://www.w3ctech.com/topic/854

原標(biāo)題是This API is So Fetching，F(xiàn)etching也可以表示迷人的意思——譯者注

JavaScript 通過XMLHttpRequest(XHR)來執(zhí)行異步請求，這個(gè)方式已經(jīng)存在了很長一段時(shí)間。雖說它很有用，但它不是最佳API。它在設(shè)計(jì)上不符合職責(zé)分離原則，將輸入、輸出和用事件來跟蹤的狀態(tài)混雜在一個(gè)對象里。而且，基于事件的模型與最近JavaScript流行的Promise以及基于生成器的異步編程模型不太搭（事件模型在處理異步上有點(diǎn)過時(shí)了——譯者注）。

新的 Fetch API打算修正上面提到的那些缺陷。 它向JS中引入和HTTP協(xié)議中同樣的原語（即Fetch——譯者注）。具體而言，它引入一個(gè)實(shí)用的函數(shù)fetch()用來簡潔捕捉從網(wǎng)絡(luò)上檢索一個(gè)資源的意圖。

Fetch 規(guī)范的API明確了用戶代理獲取資源的語義。它結(jié)合ServiceWorkers，嘗試達(dá)到以下優(yōu)化：

1. 改善離線體驗(yàn)
2. 保持可擴(kuò)展性

到寫這篇文章的時(shí)候，F(xiàn)etch API被Firefox 39（Nightly版）以及Chrome 42（開發(fā)版）支持。在github上，有基于低版本瀏覽器的兼容實(shí)現(xiàn)

特性檢測

要檢查是否支持Fetch API，可以通過檢查 Headers, Request, Response 或者 fetch 在 window 或者 worker 作用域中是否存在。

簡單的fetching示例

在Fetch API中，最常用的就是fetch()函數(shù)。它接收一個(gè)URL參數(shù)，返回一個(gè)promise來處理response。response參數(shù)帶著一個(gè)Response對象。

fetch("/data.json").then(function(res) {
  // res instanceof Response == true.
  if (res.ok) {
    res.json().then(function(data) {
      console.log(data.entries);
    });
  } else {
    console.log("Looks like the response wasn't perfect, got status", res.status);
  }
}, function(e) {
  console.log("Fetch failed!", e);
});

如果是提交一個(gè)POST請求，代碼如下：

fetch("http://www.example.org/submit.php", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  body: "firstName=Nikhil&favColor=blue&password=easytoguess"
}).then(function(res) {
  if (res.ok) {
    alert("Perfect! Your settings are saved.");
  } else if (res.status == 401) {
    alert("Oops! You are not authorized.");
  }
}, function(e) {
  alert("Error submitting form!");
});

fetch()函數(shù)的參數(shù)和傳給Request()構(gòu)造函數(shù)的參數(shù)保持完全一致，所以你可以直接傳任意復(fù)雜的request請求給fetch()。

Headers

Fetch引入了3個(gè)接口，它們分別是 Headers,Request 以及 Response 。他們直接對應(yīng)了相應(yīng)的HTTP概念，但是基于安全考慮，有些區(qū)別，例如支持CORS規(guī)則以及保證cookies不能被第三方獲取。

Headers接口是一個(gè)簡單的多映射的名-值表

var content = "Hello World";
var reqHeaders = new Headers();
reqHeaders.append("Content-Type", "text/plain");
reqHeaders.append("Content-Length", content.length.toString());
reqHeaders.append("X-Custom-Header", "ProcessThisImmediately");

也可以傳一個(gè)多維數(shù)組或者json：

reqHeaders = new Headers({
  "Content-Type": "text/plain",
  "Content-Length": content.length.toString(),
  "X-Custom-Header": "ProcessThisImmediately",
});

Headers的內(nèi)容可以被檢索：

console.log(reqHeaders.has("Content-Type")); // true
console.log(reqHeaders.has("Set-Cookie")); // false
reqHeaders.set("Content-Type", "text/html");
reqHeaders.append("X-Custom-Header", "AnotherValue");

console.log(reqHeaders.get("Content-Length")); // 11
console.log(reqHeaders.getAll("X-Custom-Header")); // ["ProcessThisImmediately", "AnotherValue"]

reqHeaders.delete("X-Custom-Header");
console.log(reqHeaders.getAll("X-Custom-Header")); // []

一些操作不僅僅對ServiceWorkers有用，本身也提供了更方便的操作Headers的API（相對于XMLHttpRequest來說——譯者注）。

由于Headers可以在request請求中被發(fā)送或者在response請求中被接收，并且規(guī)定了哪些參數(shù)是可寫的，Headers對象有一個(gè)特殊的guard屬性。這個(gè)屬性沒有暴露給Web，但是它影響到哪些內(nèi)容可以在Headers對象中被改變。

可能的值如下：

• "none": 默認(rèn)的
• "request": 從Request中獲得的Headers只讀。
• "request-no-cors"：從不同域的Request中獲得的Headers只讀。
• "response": 從Response獲得的Headers只讀。
• "immutable" 在ServiceWorkers中最常用的，所有的Headers都只讀。

哪一種 guard 作用于 Headers 導(dǎo)致什么行為，詳細(xì)定義在了這個(gè)規(guī)范中。例如，你不可以添加或者修改一個(gè)guard屬性是"request"的Request Headers的"Content-Length"屬性。同樣地，插入"Set-Cookie"屬性到一個(gè)Response headers是不允許的，因此ServiceWorkers是不能給合成的Response的headers添加一些cookies。

如果使用了一個(gè)不合法的HTTP Header屬性名，那么Headers的方法通常都拋出 TypeError 異常。如果不小心寫入了一個(gè)不可寫的屬性，也會(huì)拋出一個(gè) TypeError 異常。除此以外的情況，失敗了并不拋出異常。例如：

var res = Response.error();
try {
  res.headers.set("Origin", "http://mybank.com");
} catch(e) {
  console.log("Cannot pretend to be a bank!");
}

Request

Request接口定義了通過HTTP請求資源的request格式。參數(shù)需要URL、method和headers，同時(shí)Request也接受一個(gè)特定的body，mode，credentials以及cache hints.

最簡單的 Request 當(dāng)然是一個(gè)URL，可以通過URL來GET一個(gè)資源。

var req = new Request("/index.html");
console.log(req.method); // "GET"
console.log(req.url); // "http://example.com/index.html"

你也可以將一個(gè)建好的Request對象傳給構(gòu)造函數(shù)，這樣將復(fù)制出一個(gè)新的Request。

var copy = new Request(req);
console.log(copy.method); // "GET"
console.log(copy.url); // "http://example.com/index.html"

這種用法通常見于ServiceWorkers。

URL以外的其他屬性的初始值能夠通過第二個(gè)參數(shù)傳給Request構(gòu)造函數(shù)。這個(gè)參數(shù)是一個(gè)json：

var uploadReq = new Request("/uploadImage", {
  method: "POST",
  headers: {
    "Content-Type": "image/png",
  },
  body: "image data"
});

mode屬性用來決定是否允許跨域請求，以及哪些response屬性可讀。可選的mode屬性值為same-origin，no-cors（默認(rèn)）以及cors。

same-origin模式很簡單，如果一個(gè)請求是跨域的，那么返回一個(gè)簡單的error，這樣確保所有的請求遵守同源策略。

var arbitraryUrl = document.getElementById("url-input").value;
fetch(arbitraryUrl, { mode: "same-origin" }).then(function(res) {
  console.log("Response succeeded?", res.ok);
}, function(e) {
  console.log("Please enter a same-origin URL!");
});

no-cors模式允許來自CDN的腳本、其他域的圖片和其他一些跨域資源，但是首先有個(gè)前提條件，就是請求的method只能是"HEAD","GET"或者"POST"。此外，任何 ServiceWorkers 攔截了這些請求，它不能隨意添加或者改寫任何headers，除了這些。第三，JavaScript不能訪問Response中的任何屬性，這保證了 ServiceWorkers 不會(huì)導(dǎo)致任何跨域下的安全問題而隱私信息泄漏。

cors模式我們通常用作跨域請求來從第三方提供的API獲取數(shù)據(jù)。這個(gè)模式遵守CORS協(xié)議。只有有限的一些headers被暴露給Response對象，但是body是可讀的。例如，你可以獲得一個(gè)Flickr的最感興趣的照片的清單：

var u = new URLSearchParams();
u.append('method', 'flickr.interestingness.getList');
u.append('api_key', '<insert api key here>');
u.append('format', 'json');
u.append('nojsoncallback', '1');

var apiCall = fetch('https://api.flickr.com/services/rest?' + u);

apiCall.then(function(response) {
  return response.json().then(function(json) {
    // photo is a list of photos.
    return json.photos.photo;
  });
}).then(function(photos) {
  photos.forEach(function(photo) {
    console.log(photo.title);
  });
});

你無法從Headers中讀取"Date"屬性，因?yàn)镕lickr在Access-Control-Expose-Headers中設(shè)置了不允許讀取它。

response.headers.get("Date"); // null

credentials枚舉屬性決定了cookies是否能跨域得到。這個(gè)屬性與XHR的withCredentials標(biāo)志相同，但是只有三個(gè)值，分別是"omit"（默認(rèn)）,"same-origin"以及"include"。

Request對象也可以提供 caching hints 給用戶代理。這個(gè)屬性還在安全復(fù)審階段。Firefox 提供了這個(gè)屬性，但是它目前還不起作用。

Request還有兩個(gè)只讀的屬性與ServiceWorks攔截有關(guān)。其中一個(gè)是referrer，表示Request的來源，可能為空。另外一個(gè)是context，是一個(gè)非常大的枚舉集合定義了獲得的資源的種類，它可能是image比如請求來自于img標(biāo)簽，可能是worker如果是一個(gè)worker腳本，等等。如果使用fetch()函數(shù)，這個(gè)值是fetch。

Response

Response實(shí)例通常在fetch()的回調(diào)中獲得。但是它們也可以用JS構(gòu)造，不過通常這招只用于ServiceWorkers。

Response中最常見的成員是status（一個(gè)整數(shù)默認(rèn)值是200）和statusText（默認(rèn)值是"OK"），對應(yīng)HTTP請求的status和reason。還有一個(gè)"ok"屬性，當(dāng)status為2xx的時(shí)候它是true。

headers 屬性是Response的Headers對象，它是只讀的(with guard "response")，url屬性是當(dāng)前Response的來源URL。

Response 也有一個(gè)type屬性，它的值可能是"basic","cors","default","error"或者"opaque。

• "basic": 正常的，同域的請求，包含所有的headers除開"Set-Cookie"和"Set-Cookie2"。
• "cors": Response從一個(gè)合法的跨域請求獲得，一部分header和body可讀。
• "error": 網(wǎng)絡(luò)錯(cuò)誤。Response的status是0，Headers是空的并且不可寫。當(dāng)Response是從Response.error()中得到時(shí)，就是這種類型。
• "opaque": Response從"no-cors"請求了跨域資源。依靠Server端來做限制。

"error"類型會(huì)導(dǎo)致fetch()函數(shù)的Promise被reject并回調(diào)出一個(gè)TypeError。

還有一些屬性只在ServerWorker作用域下有效。以正確的方式 返回一個(gè)Response針對一個(gè)被ServiceWorkers攔截的Request，可以像下面這樣寫：

addEventListener('fetch', function(event) {
  event.respondWith(new Response("Response body", {
    headers: { "Content-Type" : "text/plain" }
  });
});

如你所見，Response有個(gè)接收兩個(gè)可選參數(shù)的構(gòu)造器。第一個(gè)參數(shù)是返回的body，第二個(gè)參數(shù)是一個(gè)json，設(shè)置status、statusText以及headers。

靜態(tài)方法Response.error()簡單返回一個(gè)錯(cuò)誤的請求。類似的，Response.redirect(url, status)返回一個(gè)跳轉(zhuǎn)URL的請求。

處理body

無論Request還是Response都可能帶著body。由于body可以是各種類型，比較復(fù)雜，所以前面我們故意先略過它，在這里單獨(dú)拿出來講解。

body可以是以下任何一種類型的實(shí)例：

• ArrayBuffer
• ArrayBufferView(Uint8Array and friends)
• Blob/File
• 字符串
• URLSearchParams
• FormData——目前不被Gecko和Blink支持，F(xiàn)irefox預(yù)計(jì)在版本39和Fetch的其他部分一起推出。

此外，Request和Response都為他們的body提供了以下方法，這些方法都返回一個(gè)Promise對象。

• arrayBuffer()
• blob()
• json()
• text()
• formData()

在使用非文本的數(shù)據(jù)方面，F(xiàn)etch API和XHR相比提供了極大的便利。

可以通過傳body參數(shù)來設(shè)置Request的body：

var form = new FormData(document.getElementById('login-form'));
fetch("/login", {
  method: "POST",
  body: form
})

Response的第一個(gè)參數(shù)是body：

var res = new Response(new File(["chunk", "chunk"], "archive.zip",
                       { type: "application/zip" }));

Request和Response（通過fetch()方法）都能夠自動(dòng)識別自己的content type，Request還可以自動(dòng)設(shè)置"Content-Type" header，如果開發(fā)者沒有設(shè)置它的話。

流和克隆

非常重要的一點(diǎn)要說明，那就是Request和Response的body只能被讀取一次！它們有一個(gè)屬性叫bodyUsed，讀取一次之后設(shè)置為true，就不能再讀取了。

var res = new Response("one time use");
console.log(res.bodyUsed); // false
res.text().then(function(v) {
  console.log(res.bodyUsed); // true
});
console.log(res.bodyUsed); // true

res.text().catch(function(e) {
  console.log("Tried to read already consumed Response");
});

這樣設(shè)計(jì)的目的是為了之后兼容基于流的API，讓應(yīng)用一次消費(fèi)data，這樣就允許了JavaScript處理大文件例如視頻，并且可以支持實(shí)時(shí)壓縮和編輯。

有時(shí)候，我們希望多次訪問body，例如，你可能想用即將支持的Cache API去緩存Request和Response，以便于可以離線使用，Cache要求body能被再次讀取。

所以，我們該如何讓body能經(jīng)得起多次讀取呢？API提供了一個(gè)clone()方法。調(diào)用這個(gè)方法可以得到一個(gè)克隆對象。不過要記得，clone()必須要在讀取之前調(diào)用，也就是先clone()再讀取。

addEventListener('fetch', function(evt) {
  var sheep = new Response("Dolly");
  console.log(sheep.bodyUsed); // false
  var clone = sheep.clone();
  console.log(clone.bodyUsed); // false

  clone.text();
  console.log(sheep.bodyUsed); // false
  console.log(clone.bodyUsed); // true

  evt.respondWith(cache.add(sheep.clone()).then(function(e) {
    return sheep;
  });
});

未來的改進(jìn)

為了支持流，F(xiàn)etch最終將提供可以中斷執(zhí)行讀取資源的能力，并且提供可以得到讀取進(jìn)度的API。這些能力在XHR中有，但是想要實(shí)現(xiàn)成Promise-based的Fetch API有些麻煩。

你可以加入WHATWG的郵件組參與Fetch和ServiceWorker的討論，為改進(jìn)API貢獻(xiàn)自己的力量。

為了創(chuàng)造更好的互聯(lián)網(wǎng)而努力！

感謝 Andrea Marchesini, Anne van Kesteren 和 Ben Kelly 感謝他們對規(guī)范和實(shí)現(xiàn)所做的努力.