JavaScript / TypeScript / 系统课时
判别联合
判别联合
业务状态通常拥有不同字段,如果用大量可选属性描述,调用方很容易组合出无效数据。本课通过共同的判别字段构造联合类型,使每个状态只携带自己需要的信息,并让分支内自动获得准确类型。
学习目标
- 使用字面量字段构造判别联合
- 在
switch分支中自动收窄类型 - 避免用可选字段表示互斥状态
设计共同判别字段
判别联合要求每个成员都包含同名字段,并为该字段使用不同的字面量值。下面用 status 区分支付处理中、成功和失败三种状态。
// 状态与载荷一起定义,阻止缺失必要字段
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));
}预期输出:
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 模块约定。
