JavaScript / TypeScript / 系统课时

判别联合

判别联合

业务状态通常拥有不同字段,如果用大量可选属性描述,调用方很容易组合出无效数据。本课通过共同的判别字段构造联合类型,使每个状态只携带自己需要的信息,并让分支内自动获得准确类型。

学习目标

  • 使用字面量字段构造判别联合
  • 在 switch 分支中自动收窄类型
  • 避免用可选字段表示互斥状态

设计共同判别字段

判别联合要求每个成员都包含同名字段,并为该字段使用不同的字面量值。下面用 status 区分支付处理中、成功和失败三种状态。

ts
// 状态与载荷一起定义,阻止缺失必要字段
type PaymentState =
  | {
      status: "pending";
      createdAt: string;
    }
  | {
      status: "success";
      transactionId: string;
    }
  | {
      status: "failed";
      reason: string;
    };

function describePayment(state: PaymentState): string {
  switch (state.status) {
    case "pending":
      return `Pending since ${state.createdAt}`;
    case "success":
      return `Paid: ${state.transactionId}`;
    case "failed":
      return `Failed: ${state.reason}`;
  }
}

const states: PaymentState[] = [
  { status: "pending", createdAt: "2026-07-30 10:00" },
  { status: "success", transactionId: "TX1001" },
  { status: "failed", reason: "Insufficient balance" }
];

for (const state of states) {
  console.log(describePayment(state));
}

预期输出:

text
Pending since 2026-07-30 10:00
Paid: TX1001
Failed: Insufficient balance

进入 case "success" 后,TypeScript 知道当前值一定包含 transactionId;访问其他状态专属字段会立即报错。

为什么优于可选字段

把 transactionId、reason 等字段全部写成可选属性,无法阻止“成功状态没有交易号”或“处理中状态携带失败原因”等非法组合。判别联合把业务规则直接编码进类型系统,使无效状态无法通过编译。

设计判别字段的原则

判别字段应稳定、含义单一,并使用字符串或数字字面量。常见命名包括 type、kind、status。不要让多个成员共享同一个判别值,否则编译器无法唯一确定当前成员。

类型约束与真实状态迁移

这个联合规定某一时刻的数据形态,没有定义状态迁移是否合法。例如把失败状态直接改成成功状态是否允许重试,仍须由业务操作校验。不要只修改 status 字段而遗留旧状态的专属字段,应构造一个完整的新成员,保证状态与载荷一起更新。

给主示例添加一个成功状态但删除 transactionId,编译器应拒绝;给成功状态读取 reason,也应报错。这两项检查说明字段与判别值的关联存在,不能只验证控制台文字。外部接口返回的 JSON 仍需检查 status 和对应载荷,类型别名不会在网络边界运行。

如果把对象先赋给无类型注解的可变变量,status 可能被推断成普通 string,随后不能赋给这个联合。可在创建处显式标注 PaymentState,或使用满足约束的字面量写法;不要为了通过编译把所有状态都放宽为 string。扩展状态时应同步更新分支处理,有限成员的遗漏可用下一节的 never 检查。

独立验证

使用 TypeScript 5.9.3 和 Node.js 22 检查本节。支付状态的三条输出应分别来自各自成员。临时删除成功状态的 transactionId,确认类型检查失败;撤销负例后再运行,输出应恢复一致。把主示例保存为独立目录的 main.ts,执行 npx tsc main.ts --strict --target ES2022 --module commonjs --outDir dist,预期退出码为 0;再执行 node dist/main.js 核对上述结果。说明性片段按其上下文编译,练习目录保持 CommonJS 模块约定。

支付状态与专属载荷

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

目录与阅读设置

阅读设置

17

记录一个想法

判别联合

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

登录哪都通