JavaScript / TypeScript / 系统课时

封装泛型请求函数

封装泛型请求函数

泛型请求函数要解决两个问题:把重复的请求与状态判断集中起来,同时让每个调用点仍然拿到准确的成功数据和错误类型。本篇用泛型与可辨识联合封装最小请求层,并说明它能保证什么、不能保证什么。

学习目标

  • 用两个泛型参数分别表达成功数据与业务错误
  • 通过可辨识联合让调用方安全访问 data 或 error
  • 区分 HTTP 业务失败、网络异常与运行时数据校验

先定义请求函数的返回契约

请求层不要让“成功数据”和“失败数据”混在一个全是可选字段的对象里。更稳妥的做法是返回联合类型:成功分支固定有 data,失败分支固定有 error,两者都带状态码。

这样调用方只需判断 ok,TypeScript 就能完成收窄。错误类型也作为独立泛型传入,避免所有接口都被迫共用一个过于宽泛的错误结构。

封装可复用的泛型请求函数

下面用一个可注入的传输函数模拟 fetch。这种写法便于测试,核心泛型结构与浏览器或 Node.js 中的真实请求封装相同。

ts
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();

预期输出:

text
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 自动变成可信数据。

请求封装的职责应保持克制:集中请求、解析和状态分支,同时把精确类型交还给调用方。只要成功、业务失败和传输异常三条路径没有混为一谈,这个泛型层就能在复用性和类型准确性之间保持清晰边界。

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

目录与阅读设置

阅读设置

17

记录一个想法

封装泛型请求函数

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

登录哪都通