JavaScript / TypeScript / 系统课时

封装类型安全的 API

封装类型安全的 API

API 封装的目标不是给 fetch 加一个泛型就结束,而是让请求参数、成功数据和失败状态都可被调用方正确处理。本课实现一个可复用客户端,并明确静态类型与运行时响应之间的边界。

学习目标

  • 为请求参数和响应结果定义稳定类型
  • 使用判别联合表达成功与失败
  • 避免把未经校验的响应直接断言为业务类型

设计响应模型

先定义订单与统一结果。ok 是判别字段,调用方通过分支即可获得正确的类型收窄:

ts
interface Order {
  id: string;
  status: "pending" | "paid" | "cancelled";
}

interface ApiError {
  code: string;
  message: string;
}

type ApiResult =
  | { ok: true; data: T }
  | { ok: false; status: number; error: ApiError };

判别联合能让控制流根据固定字面量字段缩小类型范围,避免同时访问成功和失败分支中不存在的属性。:contentReference[oaicite:3]{index=3}

封装请求函数

下面示例使用注入的 fetcher,因此可以在浏览器、Node.js 或测试中替换实现。返回体先保持为 unknown,再交给解析函数处理:

ts
type Fetcher = (
  input: string,
  init?: RequestInit
) => Promise;

async function requestJson(
  fetcher: Fetcher,
  url: string,
  init: RequestInit,
  parse: (value: unknown) => T
): Promise> {
  const response = await fetcher(url, init);
  const raw: unknown = await response.json();

  if (!response.ok) {
    const message =
      typeof raw === "object" &&
      raw !== null &&
      "message" in raw &&
      typeof raw.message === "string"
        ? raw.message
        : "Request failed";

    return {
      ok: false,
      status: response.status,
      error: { code: "HTTP_ERROR", message }
    };
  }

  return { ok: true, data: parse(raw) };
}

泛型 T 连接解析函数的返回类型与 API 结果,但不会自动验证网络数据。类型断言在运行时不执行检查,因此真正的安全边界仍然是 parse。:contentReference[oaicite:4]{index=4}

调用 API

本课先使用最小解析器;下一课会补充完整校验:

ts
function parseOrder(value: unknown): Order {
  if (
    typeof value !== "object" ||
    value === null ||
    !("id" in value) ||
    typeof value.id !== "string" ||
    !("status" in value) ||
    !["pending", "paid", "cancelled"].includes(String(value.status))
  ) {
    throw new Error("Invalid order response");
  }

  return value as Order;
}

async function getOrder(
  fetcher: Fetcher,
  id: string
): Promise> {
  return requestJson(
    fetcher,
    `/api/orders/${encodeURIComponent(id)}`,
    { method: "GET" },
    parseOrder
  );
}

使用模拟响应验证:

ts
const mockFetch: Fetcher = async () =>
  new Response(
    JSON.stringify({ id: "ORD-1001", status: "paid" }),
    { status: 200, headers: { "Content-Type": "application/json" } }
  );

const result = await getOrder(mockFetch, "ORD-1001");

if (result.ok) {
  console.log(result.data.id, result.data.status);
} else {
  console.log(result.status, result.error.message);
}

预期输出

text
ORD-1001 paid

处理错误与异常

HTTP 非成功状态属于可预期业务结果,可返回 ApiResult;网络中断、JSON 解析失败或校验失败通常属于异常,可在更上层捕获并记录。不要把所有失败都压缩成 null,否则调用方无法区分“没有数据”和“请求失败”。

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

目录与阅读设置

阅读设置

17

记录一个想法

封装类型安全的 API

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

登录哪都通