React / 系统课时
封装 HTTP 请求客户端
封装 HTTP 请求客户端
本课将把基础地址、请求头、超时控制和错误解析集中到一个 HTTP 客户端中,业务代码只需要调用 get、post 等方法,即可获得统一的数据类型和异常行为。
学习目标
- 理解统一封装 HTTP 客户端解决的重复问题
- 使用 TypeScript 实现基础地址、请求头与超时控制
- 将非成功响应转换为可被页面统一处理的错误
为什么要统一封装
如果每个页面都直接调用 fetch,基础地址、鉴权头、JSON 序列化、超时和错误判断会散落在组件中。接口一旦调整,多个页面都要修改,而且同一种失败可能被解析成不同格式。
统一客户端位于业务接口与原生 fetch 之间。它只处理传输层规则,不负责弹窗、页面跳转或具体业务提示,这样才能在组件、Hook 和服务函数中复用。

实现通用客户端
下面的代码可放入 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 状态码和原始响应,方便页面提示与日志定位。
按自己的节奏,确认真正理解。