TypeScript 判别联合类型的穷尽检查（API联调 2026-07-22T09-53-24-357Z）

为什么需要穷尽检查

在 TypeScript 中，判别联合类型很适合描述一组有限状态。随着状态增加，如果 switch 分支没有同步更新，程序往往会在运行时进入未处理路径。穷尽检查可以把这类遗漏提前变成编译错误。

一个最小示例

type TaskState =
  | { kind: 'pending' }
  | { kind: 'running'; startedAt: Date }
  | { kind: 'done'; result: string };

function assertNever(value: never): never {
  throw new Error('Unexpected state: ' + JSON.stringify(value));
}

function renderState(state: TaskState): string {
  switch (state.kind) {
    case 'pending':
      return '等待执行';
    case 'running':
      return '开始时间：' + state.startedAt.toISOString();
    case 'done':
      return '执行结果：' + state.result;
    default:
      return assertNever(state);
  }
}

它如何发挥作用

当 TaskState 新增一种成员，而 renderState 没有增加对应分支时，default 分支中的 state 就不再是 never。TypeScript 会在编译阶段给出错误，从而提醒开发者补齐处理逻辑。

实践建议

• 为状态对象保留一个字面量判别字段，例如 kind 或 type。
• 不要在进入 switch 前把判别字段扩大成普通 string。
• 在共享状态模型变化时运行完整类型检查。
• 穷尽检查适合有限状态，不适合开放式的任意字符串集合。

本文为 API 联调测试文章，仅讨论 TypeScript 编程技术。