fetch-api简介

发表于 更新于
在抱怨自己赚钱之少之前先努力学着让自己值钱。
十多年来，我们一直使用 XMLHttpRequest（XHR）来发送异步请求，XHR 很实用，但并不是一个设计优良的 API，在设计上并不符合职责分离原则，输入、输出以及状态都杂糅在同一对象中，并用事件机制来跟踪状态变化。并且，基于事件的模型与最近流行的 Promise 和 generator 异步编程模型不太友好。

Fetch API 旨在修正上述缺陷，它提供了与 HTTP 语义相同的 JS 语法，简单来说，它引入了 fetch() 这个实用的方法来获取网络资源。

在 Fetch 规范中对 API 进行了定义，它结合 ServiceWorkers，尝试做到如下优化：

  • 改善离线体验
  • 保持可扩展性

简单示例

Fetch API 中最常用的是 fetch() 方法，该方法最简单的形式是，接受一个 URL 参数并返回以一个 promise 对象：

1
2
3
4
5
6
7
8
9
10
11
12
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);
});

如果是提交一个POST请求，代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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() 方法的参数和 Request() 构造函数的参数完全一致，所以你可以传任意复杂的参数来实现更强大的 fetch()，下面将详细介绍。

Headers

Fetch 引入了 3 个接口，分别是 Headers，Request 和 Response。他们直接对应于的 HTTP 中相应的概念，但是基于隐私和安全考虑，也有些区别，例如支持 CORS 规则以及保证 cookies 不能被第三方获取。

Headers 接口是一个简单的键值对：

1
2
3
4
5
6
ar 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");

也可以给构造函数传一个多维数组或 JS 字面量对象：

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

Headers 的内容可被检索：

1
2
3
4
5
6
7
8
9
10
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 中可用，但这些 API 使得操作 header 更为方便。

由于 header 可以在发送请求时被发送或在收到响应时被接收，并规定了那些参数可写，所以在 Headers 对象中有个一 guard 属性，来指定哪些参数可以被改变。

可能的值如下：

  • “none”：默认值
  • “request”：Request.headers 对象只读
  • “request-no-cors”：在 no-cors 模式下，Request.headers 对象只读
  • “response”：Response.headers 对象只读
  • “immutable”：通常在 ServiceWorkers 中使用，所有 Header 对象都为只读
    在规范中对每个 guard 属性值有更详细的描述。例如，当 guard 为 request 时，你将不能添加或修改header 的 Content-Length 属性。

如果使用了一个不合法的 HTTP Header 名，那么 Headers 的方法通常都抛出 TypeError 异常。如果不小心写入了一个只读属性，也会抛出一个 TypeError 异常。除此以外，失败了将不抛出任何异常。例如：

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

Request

通过构造一个 Request 对象来获取网络资源，构造函数需要 URL、method 和 headers 参数，同时也可以提供请求体（body）、请求模式（mode）、credentials 和 cache hints 等参数。

最简单的形式如下：

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

也可以将一个 Request 对象传给构造函数，这将返回该对象的一个副本（这与 clone() 方法不同，后面将介绍）。

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

同时，这种形式通常只在 ServiceWorkers 中使用。

除 URL 之外的参数只能通过第二个参数传递，该参数是一个键值对：

1
2
3
4
5
6
7
var uploadReq = new Request("/uploadImage", {
  method: "POST",
  headers: {
    "Content-Type": "image/png",
  },
  body: "image data"
});

mode 参数用来决定是否允许跨域请求，以及哪些 response 属性可读。可选的 mode 值为 “same-origin”、”no-cors”（默认）以及 “cors”。

same-origin

该模式很简单，如果一个请求是跨域的，那么将返回一个 error，这样确保所有的请求遵守同源策略。

1
2
3
4
5
6
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!");
});

Response

Response 对象通常在 fetch() 的回调中获得，也可以通过 JS 构造，不过这通常只在 ServiceWorkers 中使用。

Response 对象中最常见的属性是 status（整数，默认值是 200）和statusText（默认值是 “OK”）。还有一个 ok 属性，这是 status 值为 200~299 时的语法糖。

另外，还有一个 type 属性，它的值可能是 “basic”、”cors”、”default”、”error” 或 “opaque”。

  • “basic”：同域的响应，除 Set-Cookie 和 Set-Cookie2 之外的所有 Header 可用
  • “cors”：Response 从一个合法的跨域请求获得，某些 Header 和 body 可读
  • “error”：网络错误。Response 对象的 status 属性为 0，headers 属性为空并且不可写。当 Response 对象从 Response.error() 中得到时，就是这种类型
  • “opaque”：在 “no-cors” 模式下请求了跨域资源。依靠服务端来做限制
    当 type 属性值为 “error” 时会导致 fetch() 方法的 Promise 被 reject，reject 回调的参数为 TypeError 对象。

还有一些属性只在 ServerWorker 下有效。在 ServerWorker 下返回一个 Response 的正确方式为：

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

如你所见，Response 构造函数接收两个参数：返回的 body 和一个键值对对象，通过该对象来设置 status、statusText 和 headers 属性。

静态方法 Response.error() 将返回一个错误响应，Response.redirect(url, status) 将返回一个跳转响应。

http://bubkoo.com/2015/05/08/introduction-to-fetch/
https://developer.mozilla.org/zh-CN/docs/Web/API/Fetch_API/Using_Fetch