异步与 API 类型

这一课你将能做到

1. 给 Promise、async/await 函数标注正确类型，处理 Promise<T> 与 Promise<void>
2. 用判别联合建模 API 响应，写出类型安全的 fetch 封装
3. 用 zod 做运行时校验，弥补 TS「编译期类型」在运行时的盲区

为什么要学

前面学的所有 TS 知识，最终都要落在「和后端打交道」上。而异步操作是前端最不可靠的环节：网络会超时、后端会返回意料之外的数据、Promise 会 reject、JSON 解析会出错。

TS 的类型系统有个根本局限：类型只在编译期存在。interface User { name: string } 在编译后消失得无影无踪。如果后端返回 { name: 123 }，TS 编译时不会报错，运行时你的代码就崩了。

所以异步 API 开发要双保险：编译期用 TS 类型建模，运行时用 zod 校验。这一课把两条线都打通。

先建立图像

异步类型的核心模型：

Promise<T> = 未来某个时刻会产出类型 T 的值

async function fetchUser(): Promise<User>
        │
        ▼
  await 之后得到 User 类型
        │
        ▼
  但运行时可能返回任何数据
        │
        ▼
  需要 zod 在运行时校验「这真的是 User 吗？」

跟着做

新建 async-demo.ts，逐步实操。

步骤 1：Promise 类型基础

// Promise 的泛型参数表示 resolve 出来的值的类型
function delay(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function fetchNumber(): Promise<number> {
  return new Promise((resolve) => {
    setTimeout(() => resolve(42), 100);
  });
}

// async 函数的返回值自动包装成 Promise<T>
async function getUserName(): Promise<string> {
  await delay(100);
  return "小明";
}

// 使用
async function main() {
  const num = await fetchNumber();     // num: number
  const name = await getUserName();    // name: string
  console.log(num, name);              // 42 "小明"
}

main();

步骤 2：Promise 的错误处理

interface User {
  id: number;
  name: string;
}

async function fetchUser(id: number): Promise<User> {
  const response = await fetch(`https://api.example.com/users/${id}`);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }
  return response.json(); // 返回 any，需要处理
}

// 调用方用 try/catch 捕获
async function loadUser() {
  try {
    const user = await fetchUser(1);
    console.log(user.name);
  } catch (error) {
    // error 默认是 unknown 类型（TS 4.4+）
    if (error instanceof Error) {
      console.error("加载失败：", error.message);
    }
  }
}

步骤 3：判别联合建模 API 响应

// API 响应的两种形态
interface ApiSuccess<T> {
  code: 0;
  data: T;
  message: "success";
}

interface ApiError {
  code: 400 | 401 | 403 | 500;
  error: string;
}

type ApiResult<T> = ApiSuccess<T> | ApiError;

// 类型守卫
function isSuccess<T>(result: ApiResult<T>): result is ApiSuccess<T> {
  return result.code === 0;
}

// 使用
async function handleUserResponse(result: ApiResult<User>) {
  if (isSuccess(result)) {
    // 这里 result 是 ApiSuccess<User>，data 存在
    console.log(`欢迎 ${result.data.name}`);
  } else {
    // 这里 result 是 ApiError，error 存在
    console.error(`失败：${result.error}`);
  }
}