Fetch API 教程

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

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

一、基本用法

fetch()的功能與 XMLHttpRequest 基本相同，但有三個主要的差異。

（1）fetch()使用 Promise，不使用回調函數，因此大大簡化了寫法，寫起來更簡潔。

（2）fetch()採用模塊化設計，API 分散在多個對象上（Response 對象、Request 對象、Headers 對象），更合理一些；相比之下，XMLHttpRequest 的 API 設計並不是很好，輸入、輸出、狀態都在同一個接口管理，容易寫出非常混亂的代碼。

（3）fetch()通過數據流（Stream 對象）處理數據，可以分塊讀取，有利於提高網站性能表現，減少內存佔用，對於請求大文件或者網速慢的場景相當有用。XMLHTTPRequest 對象不支持數據流，所有的數據必須放在緩存裏，不支持分塊讀取，必須等待全部拿到後，再一次性吐出來。

在用法上，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.values()) {
  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.blob();

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屬性設爲include。


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();
let signal = controller.signal;

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事件，這個事件可以監聽，也可以通過controller.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;
  }
}

六、參考鏈接

（完）

一、基本用法

二、Response 對象：處理 HTTP 迴應

2.1 Response 對象的同步屬性

2.2 判斷請求是否成功

2.3 Response.headers 屬性

2.4 讀取內容的方法

2.5 Response.clone()

2.6 Response.body 屬性

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

四、`fetch()`配置對象的完整 API

五、取消`fetch()`請求

六、參考鏈接

Spring Cloud 部署時如何使用 Kubernetes 作爲註冊中心和配置中心

Linux中文本處理工具三劍客之一grep及shell腳本基礎

吳恩達：2020 年，這些 AI 大事件讓我無法忘懷...

【技術詳解】國標GB28181協議視頻平臺EasyGBS同一服務器同時啓動兩個服務注意事項

法研杯參賽總結：“抽取-生成”式長文本摘要

投影對角化詳細過程

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結

Fetch API 教程

一、基本用法

二、Response 對象：處理 HTTP 迴應

2.1 Response 對象的同步屬性

2.2 判斷請求是否成功

2.3 Response.headers 屬性

2.4 讀取內容的方法

2.5 Response.clone()

2.6 Response.body 屬性

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

四、fetch()配置對象的完整 API

五、取消fetch()請求

六、參考鏈接

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

四、`fetch()`配置對象的完整 API

五、取消`fetch()`請求