React / 系统课时

封装 HTTP 请求客户端

封装 HTTP 请求客户端

本课将把基础地址、请求头、超时控制和错误解析集中到一个 HTTP 客户端中,业务代码只需要调用 get、post 等方法,即可获得统一的数据类型和异常行为。

学习目标

  • 理解统一封装 HTTP 客户端解决的重复问题
  • 使用 TypeScript 实现基础地址、请求头与超时控制
  • 将非成功响应转换为可被页面统一处理的错误

为什么要统一封装

如果每个页面都直接调用 fetch,基础地址、鉴权头、JSON 序列化、超时和错误判断会散落在组件中。接口一旦调整,多个页面都要修改,而且同一种失败可能被解析成不同格式。

统一客户端位于业务接口与原生 fetch 之间。它只处理传输层规则,不负责弹窗、页面跳转或具体业务提示,这样才能在组件、Hook 和服务函数中复用。

HTTP 客户端统一请求链路

实现通用客户端

下面的代码可放入 Vite 项目的 src/lib/http.ts,也可以直接在浏览器 TypeScript 环境中运行。示例使用公开测试接口验证 GET 请求。

ts
type RequestOptions = Omit<RequestInit, "body"> & {
  body?: unknown;
  timeoutMs?: number;
  token?: string;
};

class HttpError extends Error {
  constructor(
    public readonly status: number,
    public readonly payload: unknown,
  ) {
    const detail =
      typeof payload === "string" ? payload : JSON.stringify(payload);
    super(`HTTP ${status}: ${detail}`);
    this.name = "HttpError";
  }
}

function createHttpClient(baseURL: string) {
  async function request<T>(
    path: string,
    options: RequestOptions = {},
  ): Promise<T> {
    const { body, timeoutMs = 5000, token, ...init } = options;
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), timeoutMs);

    const headers = new Headers(init.headers);
    headers.set("Accept", "application/json");

    if (body !== undefined) {
      headers.set("Content-Type", "application/json");
    }
    if (token) {
      headers.set("Authorization", `Bearer ${token}`);
    }

    try {
      const response = await fetch(`${baseURL}${path}`, {
        ...init,
        headers,
        signal: controller.signal,
        body: body === undefined ? undefined : JSON.stringify(body),
      });

      const contentType = response.headers.get("content-type") ?? "";
      const payload = contentType.includes("application/json")
        ? await response.json()
        : await response.text();

      if (!response.ok) {
        throw new HttpError(response.status, payload);
      }

      return payload as T;
    } catch (error) {
      if (error instanceof DOMException && error.name === "AbortError") {
        throw new Error(`请求超时:${timeoutMs}ms`);
      }
      throw error;
    } finally {
      clearTimeout(timer);
    }
  }

  return {
    get<T>(path: string, options?: RequestOptions) {
      return request<T>(path, { ...options, method: "GET" });
    },
    post<T>(path: string, body: unknown, options?: RequestOptions) {
      return request<T>(path, { ...options, method: "POST", body });
    },
  };
}

interface User {
  id: number;
  name: string;
}

const http = createHttpClient(
  "https://jsonplaceholder.typicode.com",
);

async function main() {
  const user = await http.get<User>("/users/1");
  console.log(`用户 ${user.id}:${user.name}`);
}

main().catch((error) => console.error(error));

预期输出:

text
用户 1:Leanne Graham

实际网络环境不同,响应时间可能不同;如果接口不可访问,程序会进入 catch,而不会把失败响应当作正常数据返回。

接入业务接口

组件不应直接拼接 URL。建议在 src/api 中按业务域创建函数,例如 getUser、createOrder,函数内部调用统一客户端并声明返回类型。这样组件只关心业务参数与结果,传输细节仍集中在一处。

请求头也应分层处理:固定头由客户端设置,登录令牌由调用方或拦截逻辑注入,单次特殊头通过 RequestOptions 传入。不要在通用客户端中写死某个页面专用字段。

关键边界与验证

超时是客户端主动中止,不等同于服务端确认失败。对于创建订单、支付等非幂等操作,超时后不能直接重复提交,应先根据业务请求号查询结果。

验证封装时至少检查三种情况:正常 JSON 响应、服务端返回非 2xx 状态、请求超过超时时间。错误对象应保留 HTTP 状态码和原始响应,方便页面提示与日志定位。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

封装 HTTP 请求客户端

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通