JavaScript Fetch API 发起 GET 和 POST 请求详解

作者:代码拾荒时间:2026-11-16 14:29:00浏览:329

深入详解 JavaScript Fetch API 的核心用法,涵盖 GET 与 POST 请求发起、URL 参数拼接、JSON 载荷传输、HTTP 响应校验及常见异常处理与最佳实践。

JavaScript Fetch API 发起 GET 和 POST 请求详解
图 0:Fetch API 发起 GET 与 POST 请求的核心差异概览

Fetch API 是现代浏览器与 Node.js 原生提供的基于 Promise 的异步网络请求接口。在日常业务开发中,从远端获取只读数据(GET)与向服务端提交结构化载荷(POST)构成了网络交互的主体。本文将针对 GET 与 POST 两种核心请求方式,逐步拆解 URL 参数装配、JSON 序列化配置、HTTP 响应校验及异常中断控制等完整开发流程。

一、Fetch API 的工作机制与两阶段响应模型

在深入具体语法之前,必须准确理解 fetch() 的执行过程。Fetch API 在设计上采用了基于流(Stream)的两阶段处理模型。当调用 fetch(url, options) 发起调用时,其返回的 Promise 并不是在全部数据下载完成时才兑现,而是经历以下两个独立步骤:

  • 第一阶段(接收响应头):当浏览器连接到目标服务器并接收到完整的 HTTP 响应头部信息时,fetch() 返回的 Promise 即兑现(Resolve),得到一个 Response 对象。此时尚未读取消息主体。
  • 第二阶段(读取与解析响应体):通过调用 response.json()、response.text() 或 response.blob() 等方法,异步读取并解析后续传输的流式数据体。
JavaScript Fetch API 发起 GET 和 POST 请求详解
图 1:Fetch API 的两阶段流式处理生命周期及校验节点
核心避坑准则: fetch() 的 Promise 只在遭遇真实网络故障(例如断网、DNS解析失败、跨域被CORS阻止)时才会被 reject。服务器返回的 404 Not Found 或 500 Internal Server Error 属于合法的 HTTP 响应,Promise 依然处于 resolve 状态。因此,必须检查 response.ok 属性。

二、发起 GET 请求与安全传递查询参数

GET 请求主要用于从服务端获取数据。根据 HTTP 规范,GET 请求没有请求体(Request Body),所有参数均通过 URL 的查询字符串(Query String)携带。

1. 基础 GET 请求语法

当调用 fetch() 仅传入 URL 字符串时,默认使用 GET 方法:

async function fetchSimpleData() {
    try {
        const response = await fetch('https://api.example.com/v1/articles');
        if (!response.ok) {
            throw new Error(`HTTP 错误: ${response.status} ${response.statusText}`);
        }
        const data = await response.json();
        console.log('获取到的数据:', data);
        return data;
    } catch (error) {
        console.error('网络或解析故障:', error);
    }
}

2. 使用 URL 与 URLSearchParams 组装参数

初学者常通过字符串拼接构建带参 URL,例如 url + '?category=' + cat + '&keyword=' + kw。这种方式极易出现编码错误(如空格或特殊符号未转义),还可能引发格式错乱。推荐使用原生 URL 和 URLSearchParams 对象进行结构化组装:

JavaScript Fetch API 发起 GET 和 POST 请求详解
图 2:基于 URLSearchParams 的 GET 请求参数安全编码流程

3. GET 请求完整规范代码

async function searchArticles(keyword, page = 1) {
    const baseUrl = 'https://api.example.com/v1/articles';
    
    // 1. 构造原生 URL 对象
    const url = new URL(baseUrl);
    
    // 2. 利用 searchParams 装配参数
    url.searchParams.set('keyword', keyword);
    url.searchParams.set('page', String(page));
    url.searchParams.set('limit', '10');

    try {
        // 3. 发送 GET 请求并设置必要请求头
        const response = await fetch(url.toString(), {
            method: 'GET',
            headers: {
                'Accept': 'application/json'
            }
        });

        // 4. 校验状态码
        if (!response.ok) {
            throw new Error(`请求失败,状态码: ${response.status}`);
        }

        // 5. 解析并返回数据
        return await response.json();
    } catch (err) {
        console.error('搜索请求异常:', err.message);
        throw err;
    }
}

三、发起 POST 请求与提交数据载荷

POST 请求用于向服务器提交数据,常用于创建资源、提交表单或执行复杂的查询。与 GET 请求不同,POST 请求必须在配置对象(Options)中明确声明请求方法、设置正确的请求头,并将数据载荷放置在 body 字段中。

JavaScript Fetch API 发起 GET 和 POST 请求详解
图 3:Fetch POST 配置项与底层 HTTP 报文结构的对应关系

1. POST 发送 JSON 数据的标准写法

async function createUser(userData) {
    const url = 'https://api.example.com/v1/users';

    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                // 必须指定 Content-Type,告知后端采用 JSON 反序列化
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            },
            // 数据主体必须通过 JSON.stringify 转换为字符串
            body: JSON.stringify(userData)
        });

        if (!response.ok) {
            // 如果后端返回了错误详情 JSON,可尝试读取
            const errorDetails = await response.json().catch(() => null);
            throw new Error(`创建失败 [${response.status}]: ${errorDetails?.message || response.statusText}`);
        }

        const createdUser = await response.json();
        console.log('用户创建成功:', createdUser);
        return createdUser;
    } catch (err) {
        console.error('提交发生异常:', err);
        throw err;
    }
}

2. POST 常见失误与排查

  • 遗漏 Content-Type: application/json:服务器未收到明确的媒体类型声明时,可能不会自动解析载荷,导致后端请求体(如 Express 的 req.body 或 Spring Boot 的 @RequestBody)为空。
  • 直接传递对象给 body:若编写为 body: userData,JavaScript 默认调用其 toString() 方法,发送给服务端的将是无意义的文本 "[object Object]",必然解析失败。
  • 跨域预检请求(Preflight / OPTIONS):当设置自定义请求头或非简单请求类型(包括 application/json)时,浏览器会先发送一次 HTTP OPTIONS 探测请求。服务端必须对该 OPTIONS 请求返回允许的 CORS 头部(如 Access-Control-Allow-Methods 与 Access-Control-Allow-Headers),否则即使实际 POST 接口正常,浏览器也会中断请求。

四、响应状态校验与异常拦截范式

在生产环境中,网络请求必须具备健全的容错能力。完整的异常处理机制应当能够区分底层网络连通性异常、HTTP 协议状态错误以及请求超时取消三种情况。

JavaScript Fetch API 发起 GET 和 POST 请求详解
图 4:Fetch API 异常多级拦截与 HTTP 状态校验判定流

超时控制:结合 AbortController

原生 fetch() 默认不会超时,如果服务端响应挂起,请求可能会一直处于 Pending 状态。利用现代浏览器内置的 AbortSignal.timeout() 或 AbortController 可以轻松设置最大等待时限:

async function fetchWithTimeout(resource, options = {}, timeoutMs = 8000) {
    // 采用 AbortController 实现通用超时熔断
    const controller = new AbortController();
    const timerId = setTimeout(() => controller.abort(), timeoutMs);

    try {
        const response = await fetch(resource, {
            ...options,
            signal: controller.signal
        });

        clearTimeout(timerId); // 请求成功返回,清除定时器

        if (!response.ok) {
            throw new Error(`HTTP 异常状态: ${response.status}`);
        }

        return await response.json();
    } catch (error) {
        clearTimeout(timerId);
        if (error.name === 'AbortError') {
            console.error(`请求在 ${timeoutMs}ms 后超时被强行终止`);
        } else {
            console.error('请求执行失败:', error.message);
        }
        throw error;
    }
}

五、GET 与 POST 对比决策及最佳实践总结

在进行接口联调与 API 设计时,清晰理解两者的适用边界能够规避性能与安全性隐患。

对比维度 GET 请求 POST 请求
语义与目的 只读获取资源,不产生服务端状态变更 向目标资源提交数据,产生创建或更新
数据传输位置 URL 查询字符串(?key=value) HTTP 请求体(Request Body)
数据容量限制 受各浏览器及 Web 服务器 URL 长度限制(通常建议 2KB~8KB 以内) 理论上无协议级上限,受服务器配置限制(可传输大文本或文件)
幂等性与安全性 具有幂等性与安全特征(多次执行结果一致) 非幂等且不安全(多次调用可能产生重复记录)
浏览器缓存行为 可被浏览器、CDN 与代理服务器自动缓存 默认不缓存(除非明确指定缓存头)
JavaScript Fetch API 发起 GET 和 POST 请求详解
图 5:Fetch API 请求方法判定树与工程实践指导

工程实践检查清单

  1. 始终校验 response.ok:切勿仅依赖 try...catch,显式校验 HTTP 状态码才能正确处理 404/500 等业务级服务端错误。
  2. 规范设置 Content-Type:在 POST/PUT 等带实体的请求中,明确声明 'Content-Type': 'application/json'。
  3. 序列化与反序列化对齐:发送前使用 JSON.stringify() 转化对象,接收后调用 response.json() 解析数据。
  4. 配置超时保护:结合 AbortController 设置合理的超时时限,避免由于网络拥塞导致客户端线程或资源长期待决。
  5. 严谨拼接 URL 参数:使用 URL 和 URLSearchParams 替代手工字符串拼装,防止因未转义字符引发异常。
作者最新文章
相关文章
更多