TypeScript 怎么用区分联合表示请求状态

前端请求通常不只有“成功”和“失败”：页面还要区分首次加载、重新加载、空数据和接口异常。如果把这些状态揉成一个对象，再给每个字段加上可选标记，组件里很快就会出现大量非空断言。更稳的做法是使用区分联合：让每个成员都有同名的字面量字段 status，并只声明自己拥有的数据。

把请求状态拆成带有固定 status 值的互斥对象，组件用 status 判断后，TypeScript 就能自动收窄到对应成员；再用 never 检查 switch，新增状态也不容易漏掉。

先把请求状态拆成互斥对象

先定义三个互相排斥的状态。加载中没有结果数据，成功状态必须有 data，失败状态必须有 message。这一步的重点不是字段名，而是把“状态”和“允许出现的字段”放在同一个联合成员里。

type RequestState =
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; message: string };

// 请求层只返回联合成员，不让调用方猜测可选字段
async function loadUser(): Promise> {
  try {
    const response = await fetch("/api/user");
    if (!response.ok) {
      return { status: "error", message: `HTTP ${response.status}` };
    }
    return { status: "success", data: await response.json() };
  } catch (error) {
    // 网络异常也归入可展示的 error 状态
    return { status: "error", message: String(error) };
  }
}

这里的 "loading"、"success" 和 "error" 是字面量类型。若把它们写成 status: string，TypeScript 就无法用字段值准确排除其他成员。

组件分支如何自动得到正确字段

消费状态时直接检查 status 即可。判断成功后，当前变量已经被收窄为带 data 的成员；失败分支同理，不需要写 state.data! 或先把整个对象转成另一个类型。

function renderUser(state: RequestState): string {
  if (state.status === "loading") {
    return "正在加载";
  }
  if (state.status === "error") {
    // error 分支可以安全读取 message
    return `加载失败：${state.message}`;
  }
  // 剩余分支已收窄为 success，可以安全读取 data
  return `用户：${state.data.name}`;
}

这种建模还会阻止错误访问：在 loading 分支读取 state.data 会报属性不存在，而在 success 分支读取 state.message 也同样不成立。TypeScript 官方手册把这种“每个成员都有共同字面量字段”的联合称为区分联合，并说明 if 和 switch 都能据此收窄。

用 never 检查状态是否漏分支

当状态会继续增加时，建议把展示函数改成 switch，并在默认分支接住 never。当前联合成员全部处理完时，默认分支里的变量就是 never；如果后来增加 "empty"，编译器会提示它没有被处理。

function assertNever(value: never): never {
  // 只有“不可能存在”的值才能进入这里
  throw new Error(`未处理的请求状态：${String(value)}`);
}

function renderState(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "正在加载";
    case "success":
      return `用户：${state.data.name}`;
    case "error":
      return `加载失败：${state.message}`;
    default:
      return assertNever(state);
  }
}

如果把类型扩展为 { status: "empty" }，却不增加对应 case，传给 assertNever 的就不再是 never，编辑器会直接给出类型错误。这比上线后才发现空状态没有界面更早、更明确。

接口数据不要把断言当校验

区分联合解决的是 TypeScript 如何分析“已经被正确建模的数据”。它不会在运行时检查服务器返回值，所以不能把 await response.json() as RequestState 当作接口校验。真实项目应在边界处检查 status、字段类型和必填关系，再把通过检查的结果转换成联合成员。

还要区分“没有数据”和“请求失败”：空列表是成功响应中的业务结果，不一定应该复用 error。只有当界面行为、字段约束或恢复动作不同，才值得增加新的联合成员。这样状态模型不会膨胀，组件也能保持清晰。

相关规则可参考 TypeScript Handbook 的 Narrowing，其中同时介绍了区分联合、never 和穷尽检查。

常见问题

为什么不用一个对象加三个可选字段？

因为可选字段允许不合理组合，例如同时出现 data 和 message，或者三者都没有。区分联合把这些组合从类型层面排除。

if 判断和 switch 应该选哪个？

只有一两个分支时 if 足够；状态成员会持续扩展，或需要保证每种状态都有界面时，使用 switch 配合 never 更容易维护。