JavaScript Fetch API 完整指南：基础、示例、错误处理与安全

By 佐川 直弘 | Naohiro Sagawa (運営者)

※記事内に広告を含みます。Amazonアソシエイトとして適格販売により収入を得ています。　

1. 介绍：什么是 Fetch API？

JavaScript 在 Web 应用前端开发中扮演着关键角色。在众多功能中，Fetch API 是一个用于与服务器进行异步通信的强大工具。本文将以初学者友好的方式解释如何使用 Fetch API，并通过实用示例介绍其特性。

Fetch API 的作用是什么？

Fetch API 是一个现代的、标准化的 HTTP 请求与响应处理接口。过去常用 XMLHttpRequest，但 Fetch API 提供了更简洁、更直观的设计。

Fetch API 与 XMLHttpRequest 的区别

Fetch API 与传统的 XMLHttpRequest 的主要区别如下。

如上所示，Fetch API 在现代 Web 开发中被广泛使用，因其更灵活、对开发者更友好。

Fetch API 的常见使用场景

Fetch API 常用于以下情形。

1. 数据获取： 从 API 获取用户信息或帖子数据。
2. 数据提交： 向服务器发送表单数据或 JSON 数据。
3. 实时更新： 从服务器接收动态数据并更新页面内容。
4. 外部 API 集成： 与第三方 API 连接以扩展功能。

正因为这些原因，Fetch API 已成为现代 JavaScript 开发的必备工具。

小结

本节我们解释了 Fetch API 的基本作用和优势。与传统的 XMLHttpRequest 相比，Fetch API 更直观、使用更简便，并基于 Promise，使错误处理更加简单。下一节我们将通过具体代码示例，深入探讨 Fetch API 的基本用法。

继续阅读，你将学习如何在实践中使用 Fetch API 检索和操作数据。

2. Fetch API 的基本用法（附示例代码）

本节通过具体代码示例，说明 Fetch API 的基本用法。即使是初学者也能跟随，从一个简单的 GET 请求开始。

基本的 Fetch API 语法

Fetch API 的基本语法如下所示。

fetch(url, options)
  .then(response => {
    // Handle the response
  })
  .catch(error => {
    // Handle errors
  });

• url： 指定请求的 URL。
• options： 用于配置 HTTP 方法和请求头（可选）。
• then： 处理响应。
• catch： 处理错误。

GET 请求示例

下面是一个基本的 GET 请求示例。

fetch('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => {
    if (!response.ok) {
      throw new Error('A network error occurred');
    }
    return response.json();
  })
  .then(data => {
    console.log(data); // Display data
  })
  .catch(error => {
    console.error('Error:', error);
  });

使用 async/await

使用现代 JavaScript，你可以通过 async/await 编写更简洁的代码。

async function fetchPost() {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/posts/1');
    if (!response.ok) {
      throw new Error('A network error occurred');
    }
    const data = await response.json();
    console.log(data); // Display data
  } catch (error) {
    console.error('Error:', error);
  }
}

fetchPost();

添加 URL 参数

若要包含查询参数，可按如下方式编写请求。

const userId = 1;
fetch(`https://jsonplaceholder.typicode.com/posts?userId=${userId}`)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

小结

本节我们介绍了使用 Fetch API 发起 GET 请求的基础知识。

• Basic syntax: 简单易懂的设计。
• Error handling: 支持网络错误和 HTTP 错误。
• async/await: 提高可读性和可维护性。
• URL parameters: 轻松实现动态条件。

下一节将更详细地说明如何处理 Fetch API 返回的响应数据。

3. 响应处理与数据格式转换

在本节中，我们解释如何处理使用 Fetch API 获取的响应。我们特别关注 JSON 数据的转换以及文本和二进制数据的处理。

什么是 Fetch API 响应对象？

使用 Fetch API 时，请求后返回的响应以 Response 对象 的形式提供。

主要属性

获取并转换 JSON 数据

使用 Fetch API 时，服务器通常以 JSON 格式返回数据。

fetch('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => {
    if (!response.ok) {
      throw new Error('Response error: ' + response.status);
    }
    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

获取文本数据

在某些情况下，您可能需要获取纯文本数据而不是 JSON。

fetch('https://example.com/textfile.txt')
  .then(response => response.text())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

获取二进制数据

要以二进制数据获取图像或文件，请使用 blob() 或 arrayBuffer()。

fetch('https://example.com/image.jpg')
  .then(response => response.blob())
  .then(blob => {
    const url = URL.createObjectURL(blob);
    document.getElementById('image').src = url;
  })
  .catch(error => console.error('Error:', error));

小结

在本节中，您学习了如何处理 Fetch API 响应并转换数据格式。

• JSON 数据： 支持最常见的服务器响应格式。
• 文本和二进制数据： 根据需要获取不同的格式。
• 响应头： 对数据管理和安全检查很有帮助。

4. 发送 POST 请求（实用示例）

在本节中，我们解释如何使用 Fetch API 通过 POST 请求 向服务器发送数据。我们通过实用示例介绍如何发送表单数据和 JSON 数据。

POST 请求的基本语法

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})

• method： 指定要使用的 HTTP 方法（此处为 POST）。
• headers： 指定数据格式（例如 JSON 或表单数据）。
• body： 将数据转换为字符串并发送。

示例：发送 JSON 数据

const userData = {
  name: 'Taro Tanaka',
  email: 'taro.tanaka@example.com'
};

fetch('https://jsonplaceholder.typicode.com/posts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(userData)
})
  .then(response => response.json())
  .then(data => console.log('Success:', data))
  .catch(error => console.error('Error:', error));

示例：发送表单数据

const formData = new FormData();
formData.append('name', 'Taro Tanaka');
formData.append('email', 'taro.tanaka@example.com');

fetch('https://example.com/api/submit', {
  method: 'POST',
  body: formData
})
  .then(response => response.text())
  .then(data => console.log('Success:', data))
  .catch(error => console.error('Error:', error));

示例：带身份验证的请求

fetch('https://example.com/api/protected', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({ query: 'data' })
})
  .then(response => response.json())
  .then(data => console.log('Success:', data))
  .catch(error => console.error('Error:', error));

小结

在本节中，我们介绍了使用 Fetch API 的 POST 请求 的基础知识和实际用法。

• 发送 JSON 数据： 适用于 API 集成。
• 发送表单数据： 适用于简单表单和文件上传。
• 已认证请求： 支持 API 安全需求。

下一节将深入探讨 Fetch API 的错误处理和调试技术。

5. 错误处理与调试技术

在本节中，我们详细了解在使用 Fetch API 时的错误处理和调试技术。

使用 Fetch API 时常见的错误

基本错误处理

fetch('https://jsonplaceholder.typicode.com/posts/9999')
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error: ${response.status}`);
    }
    return response.json();
  })
  .catch(error => console.error('Error:', error.message));

超时处理

const controller = new AbortController();
const signal = controller.signal;

const timeout = setTimeout(() => controller.abort(), 5000);

fetch('https://jsonplaceholder.typicode.com/posts', { signal })
  .then(response => response.json())
  .catch(error => {
    if (error.name === 'AbortError') {
      console.error('Timeout: The request was aborted');
    } else {
      console.error('Error:', error.message);
    }
  })
  .finally(() => clearTimeout(timeout));

调试技术

1. 日志输出：

   fetch('https://example.com/api/data')
     .then(response => {
       console.log('Status code:', response.status);
       return response.json();
     })
     .then(data => console.log('Data:', data))
     .catch(error => console.error('Error:', error.message));
   

2. 浏览器开发者工具（Network 选项卡）：

• 实时检查请求和响应。

小结

在本节中，我们探讨了 Fetch API 的错误处理和调试技术。

• 常见错误： 网络错误、JSON 解析错误以及超时问题。
• 详细错误处理： 通过清晰的错误处理逻辑提供实用示例。
• 调试： 使用日志和浏览器开发者工具识别问题。

下一节将解释 Fetch API 的高级使用模式和安全措施。

6. 高级用法与安全措施

在本节中，我们阐述了 Fetch API 的高级使用技巧和安全考虑。

中止请求（AbortController）

const controller = new AbortController();
const signal = controller.signal;

fetch('https://jsonplaceholder.typicode.com/posts', { signal })
  .then(response => response.json())
  .catch(error => {
    if (error.name === 'AbortError') {
      console.error('The request was aborted');
    } else {
      console.error('Error:', error.message);
    }
  });

setTimeout(() => controller.abort(), 3000); // Abort after 3 seconds

带身份验证凭证的请求

const token = 'YOUR_ACCESS_TOKEN';

fetch('https://example.com/api/protected', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log('Data:', data))
  .catch(error => console.error('Error:', error));

CORS（跨域资源共享）支持

fetch('https://example.com/api/data', {
  method: 'GET',
  mode: 'cors'
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

小结

在本节中，我们覆盖了高级 Fetch API 用法和安全措施。

• 请求中止： 使用 AbortController 提高效率。
• 已认证请求： 实现 API 令牌和 CSRF 对策。
• CORS 处理： 通过正确配置解决跨域问题。

7. 常见错误与故障排除（含汇总表）

在本节中，我们解释使用 Fetch API 时可能遇到的常见错误以及如何解决它们。

常见错误及其原因

详细错误处理

fetch('https://invalid-url.example.com')
  .then(response => response.json())
  .catch(error => {
    if (error.message.includes('Failed to fetch')) {
      console.error('Network error');
    } else {
      console.error('Other error:', error.message);
    }
  });

小结

在本节中，我们回顾了常见的 Fetch API 错误以及如何处理它们。

• 典型错误： 网络错误、JSON 格式错误和超时问题。
• 详细处理： 展示稳健错误处理的实际示例。

8. 实践示例：使用 API 数据构建简易 Web 应用

在本节中，我们解释如何使用 Fetch API 创建一个从外部 API 获取数据的简易 Web 应用。

准备 HTML

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  <title>Fetch API Sample App</title>
</head>
<body>
  <h1>Post List</h1>
  <button id="fetchButton">Fetch Data</button>
  <ul id="postList"></ul>
  <p id="errorMessage" style="color: red;"></p>

  <script src="app.js"></script>
</body>
</html>

编写 JavaScript 代码

const fetchButton = document.getElementById('fetchButton');
const postList = document.getElementById('postList');
const errorMessage = document.getElementById('errorMessage');

async function fetchPosts() {
  fetchButton.disabled = true;
  errorMessage.textContent = '';
  postList.innerHTML = '';

  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/posts');
    if (!response.ok) {
      throw new Error(`HTTP error: ${response.status}`);
    }
    const posts = await response.json();
    posts.forEach(post => {
      const listItem = document.createElement('li');
      listItem.textContent = `${post.id}: ${post.title}`;
      postList.appendChild(listItem);
    });
  } catch (error) {
    errorMessage.textContent = 'Failed to retrieve data.';
  } finally {
    fetchButton.disabled = false;
  }
}

fetchButton.addEventListener('click', fetchPosts);

小结

在本节中，我们演示了如何使用 Fetch API 构建实用的 Web 应用。

• 核心功能： 数据获取和列表渲染。
• 错误处理： 在失败时显示友好的用户提示。

9. 结论与后续步骤

本文全面介绍了 Fetch API，从基础到高级用法以及实践示例。在最后一节中，我们回顾各章节的要点并建议下一步的学习方向。

关键要点

Fetch API 的基本结构和特性

• Fetch API 是一个强大的接口，用于在 JavaScript 中执行与服务器的异步通信。
• 与传统的 XMLHttpRequest 相比，它更简洁、更灵活且基于 Promise，这大大提升了可读性。

数据获取与响应处理

• 我们解释了如何获取 JSON、文本和二进制数据。
• 通过使用 async/await，可以编写更直观的代码，并简化错误处理。

数据提交与 POST 请求

• 你学习了如何向服务器发送 JSON 数据和表单数据。
• 还介绍了使用身份验证令牌的安全请求。

错误处理与调试技术

• 我们介绍了网络错误和 JSON 解析错误的实用解决方案。
• 实现了请求超时和中止请求等高级技术。

构建实用的 Web 应用

• 你构建了一个从外部 API 获取数据并在 UI 中动态显示的 Web 应用。
• 通过错误处理和按钮状态控制，你学习了反映真实开发场景的设计模式。

后续步骤

为了更好地使用 Fetch API，建议学习以下主题。

高级 API 实现技术

• 分页与排序： 在处理大型数据集时优化处理。
• 搜索功能： 根据用户输入实现数据过滤。
• 文件上传： 处理图像和视频的上传。

安全增强

• OAuth 2.0 与身份验证： 了解用于安全 API 连接的身份验证和授权流程。
• CSRF 与 XSS 防护： 实现更安全的表单提交并防御恶意脚本。

与现代技术的集成

• Axios 库： 一个流行的 Fetch API 替代方案，简化 HTTP 请求管理。
• GraphQL： 一种现代的 API 设计模型，相较于 REST API 优化数据检索。
• 实时通信： 使用 WebSocket 或服务器发送事件实现实时数据交换。

学习资源

使用以下官方文档和学习资源进一步提升您的技能。

• MDN Web Docs（官方）： 详细的 Fetch API 文档
• JSONPlaceholder（测试 API）： 用于测试的免费虚拟 API
• JavaScript 学习站点： JavaScript.info

最后说明

通过本文，您已经获得了涵盖从基础到实际使用 Fetch API 的全部知识和实践技能。
Fetch API 被广泛用于从简单的数据检索到复杂的 API 集成等各种任务。将您在此学到的内容应用到真实项目中，您可以获得更多实践经验。

接下来的行动：

• 使用真实 API 构建小项目，以获得实践经验。
• 加强错误处理和安全措施，以提升生产就绪度。
• 采用 GraphQL 和实时通信等新技术，进一步扩展您的技能组合。