JavaScript / TypeScript / 系统课时
封装泛型请求函数
封装泛型请求函数
泛型请求函数要解决两个问题:把重复的请求与状态判断集中起来,同时让每个调用点仍然拿到准确的成功数据和错误类型。本篇用泛型与可辨识联合封装最小请求层,并说明它能保证什么、不能保证什么。
学习目标
- 用两个泛型参数分别表达成功数据与业务错误
- 通过可辨识联合让调用方安全访问
data或error - 区分 HTTP 业务失败、网络异常与运行时数据校验
先定义请求函数的返回契约
请求层不要让“成功数据”和“失败数据”混在一个全是可选字段的对象里。更稳妥的做法是返回联合类型:成功分支固定有 data,失败分支固定有 error,两者都带状态码。
这样调用方只需判断 ok,TypeScript 就能完成收窄。错误类型也作为独立泛型传入,避免所有接口都被迫共用一个过于宽泛的错误结构。
封装可复用的泛型请求函数
下面用一个可注入的传输函数模拟 fetch。这种写法便于测试,核心泛型结构与浏览器或 Node.js 中的真实请求封装相同。
type RequestOptions = {
method?: "GET" | "POST";
headers?: Record<string, string>;
body?: string;
};
type JsonResponse = {
ok: boolean;
status: number;
json(): Promise<unknown>;
};
type FetchLike = (
url: string,
options?: RequestOptions
) => Promise<JsonResponse>;
type RequestResult<TData, TError> =
| { ok: true; status: number; data: TData }
| { ok: false; status: number; error: TError };
async function requestJson<TData, TError>(
transport: FetchLike,
url: string,
options?: RequestOptions
): Promise<RequestResult<TData, TError>> {
const response = await transport(url, options);
const payload = await response.json();
if (response.ok) {
return { ok: true, status: response.status, data: payload as TData };
}
return { ok: false, status: response.status, error: payload as TError };
}
interface User {
id: string;
name: string;
}
interface ApiError {
code: string;
message: string;
}
const fakeFetch: FetchLike = async (url) => {
if (url === "/users/u-1") {
return {
ok: true,
status: 200,
async json() {
return { id: "u-1", name: "Ada" };
}
};
}
return {
ok: false,
status: 404,
async json() {
return { code: "USER_NOT_FOUND", message: "User not found" };
}
};
};
async function main() {
const found = await requestJson<User, ApiError>(
fakeFetch,
"/users/u-1"
);
if (found.ok) {
console.log(`USER ${found.data.name}`);
}
const missing = await requestJson<User, ApiError>(
fakeFetch,
"/users/u-404"
);
if (!missing.ok) {
console.log(`ERROR ${missing.error.code}`);
}
}
main();预期输出:
USER Ada
ERROR USER_NOT_FOUND调用 requestJson<User, ApiError> 后,成功分支中的 data 是 User,失败分支中的 error 是 ApiError。如果直接在未判断 ok 前访问 data,TypeScript 会阻止这种不安全用法。
区分业务失败与传输异常
上面的 ok: false 只表示服务器已经返回 HTTP 失败状态,并且响应体仍符合约定的错误结构。DNS 失败、超时、连接中断或 JSON 解析失败通常会直接抛出异常,不应该伪装成某个业务错误码。
调用方因此可以把两层错误分开处理:联合类型负责“服务器明确拒绝了请求”,try...catch 负责“请求根本没有得到可解析的协议响应”。如果产品需要统一错误展示,可以在更上层再把两者转换成应用级错误。
泛型不会自动校验 JSON
payload as TData 只是在编译期告诉 TypeScript 按某个类型理解值,它不会检查服务器是否真的返回了这些字段。泛型能保证调用代码在静态类型层面保持一致,却不能把不可信 JSON 自动变成可信数据。
请求封装的职责应保持克制:集中请求、解析和状态分支,同时把精确类型交还给调用方。只要成功、业务失败和传输异常三条路径没有混为一谈,这个泛型层就能在复用性和类型准确性之间保持清晰边界。