Fetch API 教程

阮一峰發表於2020-12-28
API

fetch()是 XMLHttpRequest 的升級版，用於在 JavaScript 指令碼里面發出 HTTP 請求。

瀏覽器原生提供這個物件。本文詳細介紹它的用法。

一、基本用法

fetch()的最大特點，就是使用 Promise，不使用回撥函式。因此大大簡化了 API，寫起來更簡潔。

fetch()接受一個 URL 字串作為引數，預設向該網址發出 GET 請求，返回一個 Promise 物件。它的基本用法如下。


fetch(url)
  .then(...)
  .catch(...)

下面是一個例子，從伺服器獲取 JSON 資料。


fetch('https://api.github.com/users/ruanyf')
  .then(response => response.json())
  .then(json => console.log(json))
  .catch(err => console.log('Request Failed', err));

上面示例中，fetch()接收到的response是一個 Stream 物件，response.json()是一個非同步操作，取出所有內容，並將其轉為 JSON 物件。

Promise 可以使用 await 語法改寫，使得語義更清晰。


async function getJSON() {
  let url = 'https://api.github.com/users/ruanyf';
  try {
    let response = await fetch(url);
    return await response.json();
  } catch (error) {
    console.log('Request Failed', error);
  }
}

上面示例中，await語句必須放在try...catch裡面，這樣才能捕捉非同步操作中可能發生的錯誤。

後文都採用await的寫法，不使用.then()的寫法。

二、Response 物件：處理 HTTP 回應

2.1 Response 物件的同步屬性

fetch()請求成功以後，得到的是一個 Response 物件。它對應伺服器的 HTTP 回應。


const response = await fetch(url);

前面說過，Response 包含的資料通過 Stream 介面非同步讀取，但是它還包含一些同步屬性，對應 HTTP 回應的標頭資訊（Headers），可以立即讀取。


async function fetchText() {
  let response = await fetch('/readme.txt');
  console.log(response.status); 
  console.log(response.statusText);
}

上面示例中，response.status和response.statusText就是 Response 的同步屬性，可以立即讀取。

標頭資訊屬性有下面這些。

Response.ok

Response.ok屬性返回一個布林值，表示請求是否成功，true對應 HTTP 請求的狀態碼 200 到 299，false對應其他的狀態碼。

Response.status

Response.status屬性返回一個數字，表示 HTTP 回應的狀態碼（例如200，表示成功請求）。

Response.statusText

Response.statusText屬性返回一個字串，表示 HTTP 回應的狀態資訊（例如請求成功以後，伺服器返回"OK"）。

Response.url

Response.url屬性返回請求的 URL。如果 URL 存在跳轉，該屬性返回的是最終 URL。

Response.type

Response.type屬性返回請求的型別。可能的值如下：

  • basic：普通請求，即同源請求。
  • cors：跨域請求。
  • error：網路錯誤，主要用於 Service Worker。
  • opaque：如果fetch()請求的type屬性設為no-cors，就會返回這個值，詳見請求部分。表示發出的是簡單的跨域請求，類似<form>表單的那種跨域請求。
  • opaqueredirect：如果fetch()請求的redirect屬性設為manual，就會返回這個值，詳見請求部分。

Response.redirected

Response.redirected屬性返回一個布林值，表示請求是否發生過跳轉。

2.2 判斷請求是否成功

fetch()發出請求以後，有一個很重要的注意點：只有網路錯誤，或者無法連線時，fetch()才會報錯，其他情況都不會報錯，而是認為請求成功。

這就是說，即使伺服器返回的狀態碼是 4xx 或 5xx，fetch()也不會報錯（即 Promise 不會變為 rejected狀態）。

只有通過Response.status屬性，得到 HTTP 回應的真實狀態碼，才能判斷請求是否成功。請看下面的例子。


async function fetchText() {
  let response = await fetch('/readme.txt');
  if (response.status >= 200 && response.status < 300) {
    return await response.text();
  } else {
    throw new Error(response.statusText);
  }
}

上面示例中，response.status屬性只有等於 2xx （200~299），才能認定請求成功。這裡不用考慮網址跳轉（狀態碼為 3xx），因為fetch()會將跳轉的狀態碼自動轉為 200。

另一種方法是判斷response.ok是否為true。


if (response.ok) {
  // 請求成功
} else {
  // 請求失敗
}

2.3 Response.headers 屬性

Response 物件還有一個Response.headers屬性，指向一個 Headers 物件，對應 HTTP 回應的所有標頭。

Headers 物件可以使用for...of迴圈進行遍歷。


const response = await fetch(url);

for (let [key, value] of response.headers) { 
  console.log(`${key} : ${value}`);  
}

// 或者
for (let [key, value] of response.headers.entries()) { 
  console.log(`${key} : ${value}`);  
}

Headers 物件提供了以下方法，用來操作標頭。

  • Headers.get()：根據指定的鍵名，返回鍵值。
  • Headers.has()： 返回一個布林值，表示是否包含某個標頭。
  • Headers.set()：將指定的鍵名設定為新的鍵值，如果該鍵名不存在則會新增。
  • Headers.append()：新增標頭。
  • Headers.delete()：刪除標頭。
  • Headers.keys()：返回一個遍歷器，可以依次遍歷所有鍵名。
  • Headers.values()：返回一個遍歷器，可以依次遍歷所有鍵值。
  • Headers.entries()：返回一個遍歷器，可以依次遍歷所有鍵值對（[key, value]）。
  • Headers.forEach()：依次遍歷標頭，每個標頭都會執行一次引數函式。

上面的有些方法可以修改標頭，那是因為繼承自 Headers 介面。對於 HTTP 回應來說，修改標頭意義不大，況且很多標頭是隻讀的，瀏覽器不允許修改。

這些方法中，最常用的是response.headers.get()，用於讀取某個標頭的值。


let response =  await  fetch(url);  
response.headers.get('Content-Type')
// application/json; charset=utf-8

Headers.keys()和Headers.values()方法用來分別遍歷標頭的鍵名和鍵值。


// 鍵名
for(let key of myHeaders.keys()) {
  console.log(key);
}

// 鍵值
for(let value of myHeaders.keys()) {
  console.log(value);
}

Headers.forEach()方法也可以遍歷所有的鍵值和鍵名。


let response = await fetch(url);
response.headers.forEach(
  (value, key) => console.log(key, ':', value)
);

2.4 讀取內容的方法

Response物件根據伺服器返回的不同型別的資料，提供了不同的讀取方法。

  • response.text()：得到文字字串。
  • response.json()：得到 JSON 物件。
  • response.blob()：得到二進位制 Blob 物件。
  • response.formData()：得到 FormData 表單物件。
  • response.arrayBuffer()：得到二進位制 ArrayBuffer 物件。

上面5個讀取方法都是非同步的，返回的都是 Promise 物件。必須等到非同步操作結束，才能得到伺服器返回的完整資料。

response.text()

response.text()可以用於獲取文字資料，比如 HTML 檔案。


const response = await fetch('/users.html');
const body = await response.text();
document.body.innerHTML = body

response.json()

response.json()主要用於獲取伺服器返回的 JSON 資料，前面已經舉過例子了。

response.formData()

response.formData()主要用在 Service Worker 裡面，攔截使用者提交的表單，修改某些資料以後，再提交給伺服器。

response.blob()

response.blob()用於獲取二進位制檔案。


const response = await fetch('flower.jpg');
const myBlob = await response.blob();
const objectURL = URL.createObjectURL(myBlob);

const myImage = document.querySelector('img');
myImage.src = objectURL;

上面示例讀取圖片檔案flower.jpg，顯示在網頁上。

response.arrayBuffer()

response.arrayBuffer()主要用於獲取流媒體檔案。


const audioCtx = new window.AudioContext();
const source = audioCtx.createBufferSource();

const response = await fetch('song.ogg');
const buffer = await response.arrayBuffer();

const decodeData = await audioCtx.decodeAudioData(buffer);
source.buffer = buffer;
source.connect(audioCtx.destination);
source.loop = true;

上面示例是response.arrayBuffer()獲取音訊檔案song.ogg，然後線上播放的例子。

2.5 Response.clone()

Stream 物件只能讀取一次，讀取完就沒了。這意味著，前一節的五個讀取方法，只能使用一個，否則會報錯。


let text =  await response.text();
let json =  await response.json();  // 報錯

上面示例先使用了response.text()，就把 Stream 讀完了。後面再呼叫response.json()，就沒有內容可讀了，所以報錯。

Response 物件提供Response.clone()方法，建立Response物件的副本，實現多次讀取。


const response1 = await fetch('flowers.jpg');
const response2 = response1.clone();

const myBlob1 = await response1.blob();
const myBlob2 = await response2.blog();

image1.src = URL.createObjectURL(myBlob1);
image2.src = URL.createObjectURL(myBlob2);

上面示例中，response.clone()複製了一份 Response 物件，然後將同一張圖片讀取了兩次。

Response 物件還有一個Response.redirect()方法，用於將 Response 結果重定向到指定的 URL。該方法一般只用在 Service Worker 裡面，這裡就不介紹了。

2.6 Response.body 屬性

Response.body屬性是 Response 物件暴露出的底層介面，返回一個 ReadableStream 物件，供使用者操作。

它可以用來分塊讀取內容，應用之一就是顯示下載的進度。


const response = await fetch('flower.jpg');
const reader = response.body.getReader();

while(true) {
  const {done, value} = await reader.read();

  if (done) {
    break;
  }

  console.log(`Received ${value.length} bytes`)
}

上面示例中，response.body.getReader()方法返回一個遍歷器。這個遍歷器的read()方法每次返回一個物件，表示本次讀取的內容塊。

這個物件的done屬性是一個布林值，用來判斷有沒有讀完；value屬性是一個 arrayBuffer 陣列，表示內容塊的內容，而value.length屬性是當前塊的大小。

三、fetch()的第二個引數：定製 HTTP 請求

fetch()的第一個引數是 URL，還可以接受第二個引數，作為配置物件，定製發出的 HTTP 請求。


fetch(url, optionObj)

上面命令的optionObj就是第二個引數。

HTTP 請求的方法、標頭、資料體都在這個物件裡面設定。下面是一些示例。

（1）POST 請求


const response = await fetch(url, {
  method: 'POST',
  headers: {
    "Content-type": "application/x-www-form-urlencoded; charset=UTF-8",
  },
  body: 'foo=bar&lorem=ipsum',
});

const json = await response.json();

上面示例中，配置物件用到了三個屬性。

  • method：HTTP 請求的方法，POST、DELETE、PUT都在這個屬性設定。
  • headers：一個物件，用來定製 HTTP 請求的標頭。
  • body：POST 請求的資料體。

注意，有些標頭不能通過headers屬性設定，比如Content-Length、Cookie、Host等等。它們是由瀏覽器自動生成，無法修改。

（2）提交 JSON 資料


const user =  { name:  'John', surname:  'Smith'  };
const response = await fetch('/article/fetch/post/user', {
  method: 'POST',
  headers: {
   'Content-Type': 'application/json;charset=utf-8'
  }, 
  body: JSON.stringify(user) 
});

上面示例中，標頭Content-Type要設成'application/json;charset=utf-8'。因為預設傳送的是純文字，Content-Type的預設值是'text/plain;charset=UTF-8'。

（3）提交表單


const form = document.querySelector('form');

const response = await fetch('/users', {
  method: 'POST',
  body: new FormData(form)
})

（4）檔案上傳

如果表單裡面有檔案選擇器，可以用前一個例子的寫法，上傳的檔案包含在整個表單裡面，一起提交。

另一種方法是用指令碼新增檔案，構造出一個表單，進行上傳，請看下面的例子。


const input = document.querySelector('input[type="file"]');

const data = new FormData();
data.append('file', input.files[0]);
data.append('user', 'foo');

fetch('/avatars', {
  method: 'POST',
  body: data
});

上傳二進位制檔案時，不用修改標頭的Content-Type，瀏覽器會自動設定。

（5）直接上傳二進位制資料

fetch()也可以直接上傳二進位制資料，將 Blob 或 arrayBuffer 資料放在body屬性裡面。


let blob = await new Promise(resolve =>   
  canvasElem.toBlob(resolve,  'image/png')
);

let response = await fetch('/article/fetch/post/image', {
  method:  'POST',
  body: blob
});

四、fetch()配置物件的完整 API

fetch()第二個引數的完整 API 如下。


const response = fetch(url, {
  method: "GET",
  headers: {
    "Content-Type": "text/plain;charset=UTF-8"
  },
  body: undefined,
  referrer: "about:client",
  referrerPolicy: "no-referrer-when-downgrade",
  mode: "cors", 
  credentials: "same-origin",
  cache: "default",
  redirect: "follow",
  integrity: "",
  keepalive: false,
  signal: undefined
});

fetch()請求的底層用的是 Request() 物件的介面，引數完全一樣，因此上面的 API 也是Request()的 API。

這些屬性裡面，headers、body、method前面已經給過示例了，下面是其他屬性的介紹。

cache

cache屬性指定如何處理快取。可能的取值如下：

  • default：預設值，先在快取裡面尋找匹配的請求。
  • no-store：直接請求遠端伺服器，並且不更新快取。
  • reload：直接請求遠端伺服器，並且更新快取。
  • no-cache：將伺服器資源跟本地快取進行比較，有新的版本才使用伺服器資源，否則使用快取。
  • force-cache：快取優先，只有不存在快取的情況下，才請求遠端伺服器。
  • only-if-cached：只檢查快取，如果快取裡面不存在，將返回504錯誤。

mode

mode屬性指定請求的模式。可能的取值如下：

  • cors：預設值，允許跨域請求。
  • same-origin：只允許同源請求。
  • no-cors：請求方法只限於 GET、POST 和 HEAD，並且只能使用有限的幾個簡單標頭，不能新增跨域的複雜標頭，相當於提交表單所能發出的請求。

credentials

credentials屬性指定是否傳送 Cookie。可能的取值如下：

  • same-origin：預設值，同源請求時傳送 Cookie，跨域請求時不傳送。
  • include：不管同源請求，還是跨域請求，一律傳送 Cookie。
  • omit：一律不傳送。

跨域請求傳送 Cookie，需要將credentials屬性設為true。


fetch('http://another.com', {
  credentials: "include"
});

signal

signal屬性指定一個 AbortSignal 例項，用於取消fetch()請求，詳見下一節。

keepalive

keepalive屬性用於頁面解除安裝時，告訴瀏覽器在後臺保持連線，繼續傳送資料。

一個典型的場景就是，使用者離開網頁時，指令碼向伺服器提交一些使用者行為的統計資訊。這時，如果不用keepalive屬性，資料可能無法傳送，因為瀏覽器已經把頁面解除安裝了。


window.onunload = function() {
  fetch('/analytics', {
    method: 'POST',
    body: "statistics",
    keepalive: true
  });
};

redirect

redirect屬性指定 HTTP 跳轉的處理方法。可能的取值如下：

  • follow：預設值，fetch()跟隨 HTTP 跳轉。
  • error：如果發生跳轉，fetch()就報錯。
  • manual：fetch()不跟隨 HTTP 跳轉，但是response.url屬性會指向新的 URL，response.redirected屬性會變為true，由開發者自己決定後續如何處理跳轉。

integrity

integrity屬性指定一個雜湊值，用於檢查 HTTP 回應傳回的資料是否等於這個預先設定的雜湊值。

比如，下載檔案時，檢查檔案的 SHA-256 雜湊值是否相符，確保沒有被篡改。


fetch('http://site.com/file', {
  integrity: 'sha256-abcdef'
});

referrer

referrer屬性用於設定fetch()請求的referer標頭。

這個屬性可以為任意字串，也可以設為空字串（即不傳送referer標頭）。


fetch('/page', {
  referrer: ''
});

referrerPolicy

referrerPolicy屬性用於設定Referer標頭的規則。可能的取值如下：

  • no-referrer-when-downgrade：預設值，總是傳送Referer標頭，除非從 HTTPS 頁面請求 HTTP 資源時不傳送。
  • no-referrer：不傳送Referer標頭。
  • origin：Referer標頭只包含域名，不包含完整的路徑。
  • origin-when-cross-origin：同源請求Referer標頭包含完整的路徑，跨域請求只包含域名。
  • same-origin：跨域請求不傳送Referer，同源請求傳送。
  • strict-origin：Referer標頭只包含域名，HTTPS 頁面請求 HTTP 資源時不傳送Referer標頭。
  • strict-origin-when-cross-origin：同源請求時Referer標頭包含完整路徑，跨域請求時只包含域名，HTTPS 頁面請求 HTTP 資源時不傳送該標頭。
  • unsafe-url：不管什麼情況，總是傳送Referer標頭。

五、取消fetch()請求

fetch()請求傳送以後，如果中途想要取消，需要使用AbortController物件。


let controller = new AbortController();
fetch(url, {
  signal: controller.signal
});

signal.addEventListener('abort',
  () => console.log('abort!')
);

controller.abort(); // 取消

console.log(signal.aborted); // true

上面示例中，首先新建 AbortController 例項，然後傳送fetch()請求，配置物件的signal屬性必須指定接收 AbortController 例項傳送的訊號controller.signal。

controller.abort()方法用於發出取消訊號。這時會觸發abort事件，這個事件可以監聽，也可以通過signal.aborted屬性判斷取消訊號是否已經發出。

下面是一個1秒後自動取消請求的例子。


let controller = new AbortController();
setTimeout(() => controller.abort(), 1000);

try {
  let response = await fetch('/long-operation', {
    signal: controller.signal
  });
} catch(err) {
  if (err.name == 'AbortError') {
    console.log('Aborted!');
  } else {
    throw err;
  }
}

六、參考連結

（完）

相關文章