JavaScript Fetch API 教程：请求、JSON 与错误处理

Fetch 是基于 Promise 的 HTTP 客户端

fetch 内置于浏览器和新版 Node 中。你给它一个 URL，它返回一个 Promise，resolve 的值是一个 Response 对象。核心 API 就这么简单：

fetch("https://jsonplaceholder.typicode.com/todos/1")
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(err => console.error("failed:", err));

之所以有两次 .then 调用，是因为有两个异步步骤：先是响应头到达（第一个 promise resolve 的就是它），然后读取并解析响应体（response.json() 本身也是一个 promise）。在你主动请求之前，响应体并不会被下载。

同样的流程用 async/await 来写，读起来就像普通的从上到下的代码：

async function loadTodo() {
    const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");
    const data = await response.json();
    console.log(data);
}

loadTodo();

两个 await，两个暂停点。做的事情一样，阅读顺序却清楚得多。

Response 对象

你拿到的不是响应体，而是一个 Response 对象，它包含元数据，以及以不同形式读取响应体的方法：

async function inspect() {
    const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");

    console.log(response.status);       // 200
    console.log(response.ok);           // true for 200-299
    console.log(response.headers.get("content-type"));

    const data = await response.json();
    console.log(data.title);
}

inspect();

你可以用 .json()、.text()、.blob()、.arrayBuffer() 或 .formData() 读取响应体，每个方法都返回 promise。响应体只能读取一次：对同一个响应调用两次 .json()，第二次调用会抛出异常。

最大的坑：HTTP 错误不会 reject

几乎每个刚接触 fetch 的人都会在这里栽跟头。404 或 500 响应并不会导致 reject。promise 会正常 resolve，只是 response.ok === false。只有当请求本身无法完成时，fetch 才会 reject：DNS 失败、没有网络、被 CORS 拦截。

这意味着一个天真的 fetch 会乐呵呵地把错误页面交给你，然后在之后的 .json() 处崩溃：

async function buggy() {
    // This URL returns 404, but fetch resolves anyway.
    const response = await fetch("https://jsonplaceholder.typicode.com/nope/999");
    const data = await response.json();    // might explode or return garbage
    console.log(data);
}

buggy();

解决办法是自己检查 response.ok，在服务器返回错误状态码时抛出异常：

async function loadTodo(id) {
    const response = await fetch(`https://jsonplaceholder.typicode.com/todos/${id}`);

    if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return response.json();
}

loadTodo(1).then(console.log).catch(err => console.error(err.message));

要习惯写这个 if (!response.ok) 代码块。你写的每个 fetch 封装函数里都应该有它。

发送 POST 请求

默认是 GET。其他请求方法需要传入第二个参数，也就是一个选项对象：

async function createPost() {
    const response = await fetch("https://jsonplaceholder.typicode.com/posts", {
        method: "POST",
        headers: {
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            title: "hello",
            body: "from fetch",
            userId: 1
        })
    });

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const data = await response.json();
    console.log(data);
}

createPost();

有三点值得注意：

• method 默认是 "GET"。POST、PUT、DELETE、PATCH 需要显式设置。
• body 接收字符串（或 FormData、Blob 等），fetch 不会替你序列化对象，JSON.stringify(...) 得你自己来。
• Content-Type 请求头告诉服务器如何解析请求体。忘了设置的话，大多数服务器会把请求体当作纯文本处理。

请求头、查询字符串和其他选项

请求头就是一个对象（或一个 Headers 实例）。查询字符串需要你自己拼，通常用 URLSearchParams：

async function search(query, token) {
    const params = new URLSearchParams({ q: query, limit: "10" });
    const url = `https://api.example.com/search?${params}`;

    const response = await fetch(url, {
        headers: {
            "Authorization": `Bearer ${token}`,
            "Accept": "application/json"
        }
    });

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
}

URLSearchParams 会替你处理编码，包括空格、& 符号和 Unicode 字符，这样输入中有需要转义的字符时，URL 也不会出错。

实际代码中你还会看到这些选项：credentials: "include" 用于跨域发送 cookie，cache: "no-store" 用于绕过 HTTP 缓存，mode: "cors"（通常是默认值）用于控制 CORS 行为。

用 AbortController 取消请求

有时你想放弃一个请求：用户输入了新的搜索词，或者请求耗时太久。AbortController 就是为此而生的机制：

async function loadWithTimeout(url, ms) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), ms);

    try {
        const response = await fetch(url, { signal: controller.signal });
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        return await response.json();
    } finally {
        clearTimeout(timeout);
    }
}

loadWithTimeout("https://jsonplaceholder.typicode.com/todos/1", 3000)
    .then(console.log)
    .catch(err => console.error(err.name, err.message));

controller.abort() 会让 fetch 的 promise 以一个 DOMException reject，它的 name 是 "AbortError"。finally 代码块会清除定时器，这样请求成功时也不会留下悬空的定时器。

这种 fetch 加超时再加清理的模式，值得封装成一个辅助函数，到处复用。

可复用的封装函数

把以上内容组合起来，就得到一个一次性处理样板代码的小工具：

async function apiRequest(url, options = {}) {
    const response = await fetch(url, {
        headers: { "Content-Type": "application/json", ...options.headers },
        ...options
    });

    if (!response.ok) {
        const text = await response.text();
        throw new Error(`HTTP ${response.status}: ${text || response.statusText}`);
    }

    if (response.status === 204) return null;   // No Content
    return response.json();
}

apiRequest("https://jsonplaceholder.typicode.com/todos/1")
    .then(console.log)
    .catch(err => console.error(err.message));

一个地方修改请求头，一个地方处理错误，一个地方应对空响应。每个稍有规模的应用最后都会有类似的东西。

下一步：异步代码中的错误处理

fetch 是异步错误最常出现的地方之一，而 response.ok 检查只是其中一环。下一页讲解 promise 和 async/await 中的错误处理：错误去了哪里、如何捕获它们，以及哪些陷阱会让错误悄无声息地溜走。