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,否则调用方无法区分“没有数据”和“请求失败”。
按自己的节奏,确认真正理解。