Fetch API 教程(全文核查整理版)

作者:阮一峰。原文发表于 2020 年 12 月 28 日:Fetch API 教程。本文保留完整技术章节和原文参考链接,并在 2026 年 10 月 5 日核查整理。原文采用 CC BY-NC-ND 3.0,作者归属不变。

阅读说明:下列请求地址、文件名、DOM 元素和变量是各自独立示例的上下文,不是一段可直接拼接运行的程序。原文示例通常省略状态检查、错误处理和 DOM 判空;有关风险已在相邻段落及文末标明。修订内容标作“编者校订”,未把静态审核称为执行测试。

fetch()是 XMLHttpRequest 的升级版,用于在 JavaScript 脚本里面发出 HTTP 请求。

浏览器原生提供这个对象。本文详细介绍它的用法。

fetch 返回 Response;先检查 HTTP 状态,再选择一次性解析或读取 response.body;AbortController 可发送取消信号。
未完纪原创技术示意图;用于说明流程,不是运行截图。

一、基本用法

fetch()的功能与 XMLHttpRequest 基本相同,但有三个主要的差异。

(1)fetch()使用 Promise,不使用回调函数,因此大大简化了写法,写起来更简洁。

(2)fetch()采用模块化设计,API 分散在多个对象上(Response 对象、Request 对象、Headers 对象),更合理一些;相比之下,XMLHttpRequest 的 API 设计并不是很好,输入、输出、状态都在同一个接口管理,容易写出非常混乱的代码。

(3)fetch()可以通过响应体的 ReadableStream 分块处理数据。与通常一次性获取响应体的 XHR 用法相比,这种方式适合逐块处理下载内容;但调用 json()、text() 等便捷方法仍会等待并读取完整响应。编者校订:XHR 也有进度事件和部分渐进读取能力,不能把它概括成任何情况下都只能等到最后才看到数据。

在用法上,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)); 

上例拿到的是 Response 对象,不是 Stream 对象。流位于它的 body 属性中。response.json() 异步读完响应体并将内容解析为 JavaScript 值。编者校订:这里修正原文把 Response 本身称为流的表述。

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);
  }
}

上例在 try...catch 中等待请求和 JSON 解析,以便在本函数内处理它们的失败。编者校订: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()请求的mode属性设为no-cors,就会返回这个值,详见请求部分。表示发出的是简单的跨域请求,类似<form>表单的那种跨域请求。
  • opaqueredirect:如果fetch()请求的redirect属性设为manual,就会返回这个值,详见请求部分。

Response.redirected

Response.redirected属性返回一个布尔值,表示请求是否发生过跳转。

2.2 判断请求是否成功

fetch() 返回的 Promise 是否兑现,与服务器返回的 HTTP 状态码是否代表业务成功,是两件事。网络失败、请求被取消或请求参数等错误可能让 Promise 拒绝;HTTP 404、500 等响应通常仍会兑现为 Response。因此拿到响应后还要明确检查状态,解析响应体也可能单独失败。

这就是说,即使服务器返回的状态码是 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);
  }
}

上例把 2xx 状态视为成功。编者校订:默认 redirect: "follow" 会跟随重定向,但不会把任意 3xx 自动“转成 200”;最终地址仍可能返回 404、500 或其他结果。应检查最终 Response 的 ok 或 status。

另一种方法是判断response.ok是否为true。


if (response.ok) {
  // 请求成功
} else {
  // 请求失败
}

2.3 Response.headers 属性

response.headers 指向 Headers 对象,用于读取浏览器允许脚本看到的响应头。跨域响应只暴露 CORS 允许的头;Set-Cookie 等头不能作为普通前端 JavaScript 的可读响应头。

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 接口。编者校订:从网络响应得到的 Headers 通常不可修改,尝试写入可能抛出异常;请求头还受禁止设置的头名与 CORS 限制,不能把这些方法理解成浏览器允许任意改写网络头。

这些方法中,最常用的是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

安全校订:上段保留原文示例供辨认风险:把不可信响应直接赋给 innerHTML 会引入 HTML 注入/XSS 风险。若目的只是展示文本,可使用下列修订版;若必须渲染 HTML,需要另行采用可信模板和经过审查的 HTML 清理策略,不能仅靠“来自同域”判断可信。

const response = await fetch('/users.html');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const body = await response.text();
document.querySelector('#output').textContent = body;

差异:增加状态检查,将危险的 innerHTML 改为 textContent。页面应先存在 #output 元素;这段显示原始文本,不保留 HTML 排版。

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() 将完整响应体读入一个 ArrayBuffer,适用于需要直接处理二进制字节的场景。下例读取音频文件,再交给 Web Audio 解码;它本身不是边下载边播放的流式解码。


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 = decodeData; // 编者更正:使用解码后的 AudioBuffer
source.connect(audioCtx.destination);
source.loop = true;

编者校订:原文将下载得到的 ArrayBuffer 直接赋给 source.buffer,混淆了编码字节与解码后的 AudioBuffer。本文把该行改为 source.buffer = decodeData;其类型依据见 AudioBufferSourceNode.buffer 文档。上例描述下载、解码和连接节点的流程,未经运行验证。另须注意:源代码没有调用 source.start(),因此不能单凭此段断言“已经播放”。实际播放还需在允许的用户手势流程中恢复 AudioContext 并启动节点。这里只保留原文演示解码过程,未进行音频播放测试。

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() 返回读取器 ReadableStreamDefaultReader,其异步 read() 方法给出 { done, value },而不是普通同步迭代器。使用前还应检查 response.ok,并考虑 body 为空的情况。

done 表示流是否结束;Fetch 字节流中的 value 通常是 Uint8Array,value.length 是这一块的字节数。要显示累计进度,需要自己累加;若响应没有可靠的总长度,就只能显示已接收字节,而不能保证得到准确百分比。这里修正原文“arrayBuffer 数组”的说法。

三、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) 
});

JSON 字符串应与 Content-Type: application/json;charset=utf-8 配合。编者校订:Content-Type 不是每次 fetch 都无条件默认为纯文本;浏览器会根据 body 类型推断,字符串常对应 text/plain;charset=UTF-8,FormData、URLSearchParams 和 Blob 的行为不同,没有 body 的请求也不需要这个头。

(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 配置项

下面保留 2020 年原文列出的配置项示例,它不是对今天所有 RequestInit 字段的穷尽清单,也不是要求每个请求都照抄的默认配置。尤其 referrerPolicy 的历史默认值已发生变化。当前字段定义见 RequestInit。


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: "same-origin"。

mode

mode属性指定请求的模式。可能的取值如下:

  • cors:默认值,允许跨域请求。
  • same-origin:只允许同源请求。
  • no-cors:请求方法只限于 GET、POST 和 HEAD,并且只能使用有限的几个简单标头,不能添加跨域的复杂标头,相当于提交表单所能发出的请求。

credentials

credentials属性指定是否发送 Cookie。可能的取值如下:

  • same-origin:默认值,同源请求时发送 Cookie,跨域请求时不发送。
  • include:允许跨域请求携带凭据,但 Cookie 仍受到 SameSite、域、路径、Secure 以及浏览器隐私策略限制。
  • omit:一律不发送。

跨域发送凭据时可设置 credentials: "include"。下例是原文的 API 形式示意,实际服务应使用 HTTPS,并明确评估 CSRF。服务器还需返回允许凭据的 CORS 头及明确的调用方 origin,不能同时使用 Access-Control-Allow-Origin: *。仅设置 include 不能保证 Cookie 一定发送,也不能赋予读取任意跨域响应的权限。


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:不自动跟随跳转。浏览器通常返回字段被过滤的 opaqueredirect 响应,不能依赖它读取目标 Location,或假定 url 已是新地址、redirected 已为 true。此处修正原文对浏览器行为的描述。

integrity

integrity属性指定一个哈希值,用于检查 HTTP 回应传回的数据是否等于这个预先设定的哈希值。

比如,下载文件时,检查文件的 SHA-256 哈希值是否相符,确保没有被篡改。


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

referrer

referrer属性用于设定fetch()请求的referer标头。

编者校订:referrer 不能任意伪造跨域来源;支持同源的相对或绝对 URL、空字符串以及 about:client。空字符串表示不发送 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;
  }
}

六、参考链接

编者补充:正确使用这些示例

响应体只能消费一次。应在读取前调用 clone();已使用或已锁定的响应体不能任意克隆。克隆不表示第二次 HTTP 请求,但两个分支消费速度差距过大时可能增加缓冲和内存使用。Blob 示例创建的对象 URL 在不再使用时应通过 URL.revokeObjectURL() 释放,不能在图片尚未读取完时提前撤销。

上传数据要让类型与内容一致。FormData 的 multipart 边界由浏览器设置,不应手写一个不含边界的 Content-Type;文件选择器可能没有文件,canvas 的 toBlob 也可能得到 null。服务端仍必须核验文件类型、大小、权限与 CSRF。no-cors 只能得到不可读取正文和响应头的 opaque 响应,不是绕过 CORS 的办法。

页面离开不等于数据已经送达。原文的 window.onunload 例子只是历史写法,页面生命周期事件不保证总会触发。keepalive 也有体积限制(RequestInit 文档列出 64 KiB),不适合大文件上传。应按实际浏览器与业务需要设计可靠性和隐私策略,不把统计请求送达视为必然。

完整性校验需要真实摘要。原文 sha256-abcdef 只展示参数形式,不是任何文件的有效已知摘要。应使用可信渠道获得的真实哈希和 HTTPS;完整性参数不能代替来源信任。

取消不是服务端回滚。原文的立即 abort 片段没有消费 fetch 拒绝结果,实际使用应处理 Promise 拒绝。下面的修订版把计时器生命周期和响应体读取一起纳入处理范围;区别是增加状态检查、等待正文并在 finally 清理计时器。

async function fetchWithTimeout(url) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 1000);
  try {
    const response = await fetch(url, { signal: controller.signal });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.text();
  } catch (error) {
    if (error.name === 'AbortError') {
      console.log('请求已取消');
    }
    throw error;
  } finally {
    clearTimeout(timer);
  }
}

取消后服务器可能已接收并处理了请求;支付、创建资源等操作仍须由服务端设计幂等和事务语义,不能把客户端取消当作撤销成功。这里没有访问或测试任何示例接口。

本次校订依据:MDN fetch()、MDN RequestInit、MDN Referrer-Policy。具体浏览器与 Node.js 的网络实现可能存在差异,本文以浏览器上下文为主。

© 版权声明
THE END
喜欢就支持一下吧
点赞0 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容