本文系统讲解在JavaScript中使用Fetch API发起HTTP请求并解析JSON数据的完整技术方案。涵盖GET与POST请求编写、双阶段Promise原理解析、response.ok状态判断、常见踩坑排查及超时控制。
JavaScript使用Fetch API发起HTTP请求与处理JSON数据
时间:2026-11-18
浏览:561
文章目录
Fetch API 是现代浏览器原生支持的底层网络通信接口,基于 Promise 设计,用来取代旧时代的 XMLHttpRequest。在前后端数据交互中,客户端最频繁的工作是向后端 RESTful 接口拉取或提交 JSON 数据。本文通过具体的代码示例、执行步骤和底层原理解释,直接介绍如何使用 Fetch API 发起 GET 与 POST 请求、解析 JSON 响应流、正确判定 HTTP 业务状态码,并建立起包含超时取消与异常捕获的健壮通信机制。
一、Fetch API 的核心机制与双阶段 Promise 运作
使用 Fetch API 发起网络通信时,最基础的调用方式是 fetch(url, options)。当不提供 options 配置对象时,浏览器默认以 GET 方法发出请求。但与传统的 AJAX 库(如 Axios)不同,Fetch API 在设计上具有两个至关重要的底层行为特征,理解这两个特征是写出稳定代码的前提。
1. 两个独立的 Promise 解析阶段
从发起请求到最终拿到解析好的 JavaScript 对象,Fetch 必须经历两个先后串联的 Promise:
-
第一阶段(建立连接与获取响应头):调用
fetch(url)返回一个 Promise。只要客户端与服务器建立了 HTTP 握手,并且收到了服务器返回的 HTTP 响应头(Headers)与状态码(Status),这个 Promise 就会成功决议(resolve),生成一个Response实例。此时,响应体(Body)通常还在网络链路上持续传输,并没有全部到达内存。 -
第二阶段(异步读取数据流并解析):在拿到
Response对象后,调用response.json()会开启第二个 Promise。该方法会读取底层传入的流式数据(ReadableStream),在数据流全部接收完毕后,将其反序列化为原生的 JavaScript 对象或数组。
2. Fetch 对 HTTP 状态码的决议规则
404 Not Found 或 500 Internal Server Error 时,fetch() 会自动抛出异常并进入 catch 块。这是错误的。
在 Fetch 的设计规范中,只要服务端返回了任何合法的 HTTP 响应报文,无论状态码是 200、400、404 还是 500,fetch() 产生的 Promise 都会被认定为成功执行(resolve)。
只有在发生真正的网络通信崩溃时,fetch() 的 Promise 才会进入 reject 状态。这包括:设备完全脱机离线、域名 DNS 解析失败、跨域资源共享(CORS)配置错误被浏览器强制中断、或者通过 AbortController 主动取消了请求。因此,检查 HTTP 业务状态是否成功,必须由开发者通过 response.ok 属性显式完成。
二、发起 GET 请求并解析 JSON 数据
GET 请求通常用于从服务端检索指定资源。为了保证代码清晰与避免回调地狱,推荐在 async 函数内部使用 await 关键字进行操作。
1. 参数组装与标头协商
在发起 GET 请求时,查询参数应该附加在 URL 之后。推荐使用标准对象 URLSearchParams 来组装参数,它可以自动对参数的键值进行 URL 编码(解决中文、空格及特殊符号转义问题),杜绝手动用 + 或模板字符串拼接带来的格式损坏。
同时,通过在请求头中加入 Accept: application/json,可以明确告知服务端 API 期望返回 JSON 格式的内容,避免服务端因缺乏内容协商而返回 XML 或 HTML 页面。
2. GET 请求完整示例
下面是一个标准、规范的 GET 请求示例,展示了参数构建、响应状态校验以及 JSON 数据提取的完整代码:
/**
* 根据分页与关键词获取用户列表数据
* @param {number} page 当前页码
* @param {string} keyword 搜索关键词
* @returns {Promise<Array>} 用户数据数组
*/
async function fetchUserList(page = 1, keyword = '') {
// 1. 安全组装查询参数
const queryParams = new URLSearchParams({
page: String(page),
limit: '10',
search: keyword
});
const requestUrl = `https://api.example.com/v1/users?${queryParams.toString()}`;
try {
// 2. 发起请求并配置协商标头
const response = await fetch(requestUrl, {
method: 'GET',
headers: {
'Accept': 'application/json'
}
});
// 3. 校验 HTTP 状态码 (200~299)
if (!response.ok) {
// 当服务端返回 404 或 500 时,手动抛出包含状态码的异常
throw new Error(`HTTP 请求失败,状态码: ${response.status} (${response.statusText})`);
}
// 4. 消费数据流提取 JSON
const result = await response.json();
// 5. 业务字段消费(假设接口返回结构为 { code: 0, data: [...] })
console.log('获取数据成功:', result.data);
return result.data;
} catch (error) {
// 统一捕获网络异常、状态码异常与 JSON 解析异常
console.error('获取用户列表失败:', error.message);
throw error;
}
}
三、发起 POST 请求提交 JSON 数据
向服务端新增资源或提交表单时,需要使用 POST 方法,并将结构化数据置于 HTTP 请求体(Body)中。Fetch 提交 JSON 数据时,必须在 options 对象中明确配置三个要素:
method: 'POST':声明 HTTP 动词。headers: { 'Content-Type': 'application/json' }:告知服务端正文的 MIME 类型。body: JSON.stringify(payload):将 JavaScript 内存对象显式序列化为 JSON 字符串。
初学者极易踩坑的两个关键失误
| 错误行为 | 底层发生的情况 | 服务端表现与结果 |
|---|---|---|
忘记 JSON.stringifybody: newUser |
Fetch 的 body 仅支持字符串、Blob 或 FormData 等。如果传入普通 JS 对象,底层会调用对象的 .toString() 方法,实际传出的载荷变成了字面量 "[object Object]"。 |
服务端 JSON 解析器遇到 [object Object] 必然抛出语法解析错误,直接返回 400 Bad Request。 |
漏写 Content-Typeheaders: {} |
浏览器默认会将没有显式指定类型的字符串请求体作为 text/plain 发送。 |
现代后端框架(如 Express 的 express.json() 或 Spring Boot 的 @RequestBody)会因为标头不匹配而直接跳过正文反序列化,导致后端控制器接收到的 req.body 为 undefined 或空对象 {}。 |
POST 请求完整示例
以下示例向后端创建新用户,提交 JSON 数据,并接收服务端生成的 201 Created 响应:
/**
* 提交新用户信息至服务器
* @param {Object} userData 包含用户名、邮箱和角色的新用户对象
* @returns {Promise<Object>} 服务端创建成功后的实体对象
*/
async function createNewUser(userData) {
const targetUrl = 'https://api.example.com/v1/users';
try {
const response = await fetch(targetUrl, {
method: 'POST',
headers: {
// 关键配置 1:告知服务端正文是 JSON 格式字符串
'Content-Type': 'application/json',
// 关键配置 2:告知服务端客户端期望返回 JSON
'Accept': 'application/json'
},
// 关键配置 3:必须显式使用 JSON.stringify 序列化
body: JSON.stringify(userData)
});
// 校验响应状态
if (!response.ok) {
// 尝试解析服务端返回的详细错误信息
const errorDetail = await response.json().catch(() => ({ message: response.statusText }));
throw new Error(`创建失败 (${response.status}): ${errorDetail.message || '未知业务错误'}`);
}
// 服务端通常在 201 Created 时返回新生成的带有唯一 ID 的资源对象
const createdResource = await response.json();
console.log('创建用户成功,服务端分配ID:', createdResource.id);
return createdResource;
} catch (error) {
console.error('提交用户数据发生错误:', error.message);
throw error;
}
}
四、健壮的错误处理与超时取消机制
在实际生产环境中,网络请求充满不确定性。一个工业级的请求调用必须同时应对三种不同层面的异常:
1. 区分三种异常分类
-
网络底层异常(Network Error):用户物理离线、DNS 查询超时、服务端服务未启动、或者由于 CORS 未放行被浏览器内核阻断。这类异常会导致
fetch()的 Promise 直接被reject,抛出原生TypeError。 -
HTTP 状态异常(HTTP Status Error):例如
401 Unauthorized(未登录)、403 Forbidden(无权限)、404 Not Found(资源不存在)、500 Server Error(后端崩溃)。如前所述,此类错误必须通过判断!response.ok主动抛出。 -
数据解析异常(SyntaxError):当接口网关或反向代理(如 Nginx)故障返回
502 Bad Gateway时,返回的内容往往是一段 HTML 错误网页。如果代码直接无条件执行await response.json(),JSON 解析器在遇到<!DOCTYPE html>的首字符<时就会崩溃,抛出SyntaxError: Unexpected token '<' in JSON at position 0。
2. 请求超时与主动取消(AbortController)
原生 fetch 默认不会自动超时;只要底层 TCP 连接保持,请求可能会挂起数十秒甚至几分钟。现代 JavaScript 提供了 AbortController 与 AbortSignal.timeout() 来优雅地设置超时限制。
/**
* 发起带有 5 秒超时保护与安全 JSON 解析的 GET 请求
* @param {string} url 请求目标地址
* @param {number} timeoutMs 超时毫秒数,默认 5000ms
*/
async function fetchWithTimeout(url, timeoutMs = 5000) {
// 现代浏览器支持 AbortSignal.timeout 直接生成带有超时信号的控制器
const signal = AbortSignal.timeout(timeoutMs);
try {
const response = await fetch(url, {
method: 'GET',
headers: { 'Accept': 'application/json' },
signal: signal
});
// 1. 拦截 HTTP 状态码错误
if (!response.ok) {
throw new Error(`HTTP 异常: ${response.status}`);
}
// 2. 防御性检查:确认返回的内容确实为 JSON 格式,防止 HTML 错误页导致崩溃
const contentType = response.headers.get('content-type');
if (!contentType || !contentType.includes('application/json')) {
const rawText = await response.text();
throw new TypeError(`期望返回 JSON,但实际收到: ${contentType},内容摘要: ${rawText.slice(0, 100)}`);
}
// 3. 安全解析
return await response.json();
} catch (error) {
if (error.name === 'TimeoutError') {
console.error(`请求在 ${timeoutMs}ms 内未能完成,已强制终止。`);
} else {
console.error('通信或解析异常:', error.message);
}
throw error;
}
}
五、通用请求封装与最佳实践总结
为了避免在每个页面组件中重复编写状态码检查、请求头配置和异常处理代码,开发中通常会将 Fetch 封装为一个通用的请求函数。通过统一封装,可以集中管理身份认证令牌(如 Authorization: Bearer <token>)、全局超时和错误日志上报。
通用请求包装函数实现
/**
* 工业级通用 Fetch 请求封装函数
* @param {string} endpoint 接口路径
* @param {Object} options 请求配置项
* @returns {Promise<any>}
*/
async function request(endpoint, { method = 'GET', data = null, headers = {}, timeout = 8000 } = {}) {
const config = {
method,
headers: {
'Accept': 'application/json',
...headers
},
signal: AbortSignal.timeout(timeout)
};
// 如果包含提交数据,自动序列化并设置正确的 Content-Type
if (data !== null) {
config.headers['Content-Type'] = 'application/json';
config.body = JSON.stringify(data);
}
let response;
try {
response = await fetch(endpoint, config);
} catch (netErr) {
if (netErr.name === 'TimeoutError') {
throw new Error(`接口请求超时 (${timeout}ms): ${endpoint}`);
}
throw new Error(`网络不可达或跨域拦截: ${netErr.message}`);
}
// 统一业务状态码拦截
if (!response.ok) {
let errorPayload;
try {
errorPayload = await response.json();
} catch {
errorPayload = { message: await response.text() };
}
const err = new Error(errorPayload.message || `请求失败,状态码: ${response.status}`);
err.status = response.status;
err.payload = errorPayload;
throw err;
}
// 如果遇到 204 No Content,直接返回 null,不强行解析 JSON
if (response.status === 204) {
return null;
}
// 安全解析响应数据
const contentType = response.headers.get('content-type') || '';
if (contentType.includes('application/json')) {
return await response.json();
}
return await response.text();
}
掌握 Fetch API 发起 HTTP 请求与处理 JSON 数据的核心在于把握两个关键环节:其一是发起阶段针对不同请求方法(GET、POST)做好 URL 参数构建与正文序列化约束;其二是决议阶段必须清晰区分网络连通与 HTTP 业务状态(response.ok),并在调用 response.json() 前做好数据格式的防御性检查。通过合理的流程抽象与超时控制,即可在现代前端工程中构建出高效、稳定且易于维护的数据通信层。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。