联合类型与交叉类型

是什么，为什么存在

联合类型表示一组可能性。string | number 的值可能是字符串，也可能是数字，调用方可以提供任意一种。接收方在确认具体成员之前，只能执行对每种可能值都安全的操作。

交叉类型表示多项约束必须同时成立。Identified & Timestamped 要求一个值既有身份字段，也有时间字段。它适合组合独立能力和对象片段，不要求这些声明存在继承关系。

两者解决的是静态模型中的不同问题：联合类型描述选择，交叉类型累积要求。函数输入、解析结果、状态机和事件载荷常用联合类型；权限、元数据和可复用能力常用交叉类型。

TypeScript 按 结构类型（structural typing） 判断兼容性。一个值只要拥有所需结构，就可以同时满足多个声明，因此联合类型是包含式的“或”，不是排他的二选一。

不要把联合与交叉机械等同于运行时容器。它们会在编译后被擦除，不创建标签、不复制属性，也不验证外部数据。类型定义必须与真实对象构造和运行时检查相配合。

工作原理

可以把普通类型近似看成可能值的集合。A | B 包含属于 A 或 B 的值，范围通常更宽；A & B 只包含同时属于两者的值，范围通常更窄。这个模型能解释赋值方向和 never，但 any 等特殊类型会破坏简单集合直觉。

若表达式的类型是 A，它可以赋给 A | B，因为联合类型接受更多可能性。反过来通常不成立：一个 A | B 值可能只满足 B。若表达式是 A & B，则它可以分别赋给 A 和 B，因为它已经满足两边的要求。

对象联合不会自动成为“所有字段都可选”的对象。{ email: string } | { phone: string } 表示至少匹配其中一种结构，而且某个运行时对象也可能两种都匹配。要保留字段之间的对应关系，应使用可辨识联合，而不是把每个字段改成可选。

交叉类型也不限于对象。string & "ready" 会缩小为字面量类型 "ready"，而 string & number 没有正常值，会得到 never。对象交叉只是在结构类型系统中最常见的用法。

联合上的安全操作

当变量是 string | number 时，编译器必须考虑两种成员。toString() 对两者都存在，因此可直接调用；toUpperCase() 只属于字符串，toFixed() 只属于数字，所以必须先收窄。

“共有成员”指类型检查器能证明安全的成员和调用方式，不只是属性名相同。若两个成员都有同名函数，但参数契约不兼容，知道属性存在仍不表示可以安全调用它。

下面的关系表从使用方角度概括了两种组合：

收窄与可辨识联合

收窄（narrowing）用运行时事实排除联合成员。typeof、instanceof、相等比较、in 检查和自定义类型谓词都能提供不同证据。检查必须真实反映运行时值，类型断言不会产生证据。

对象联合最好共享一个字面量判别字段。status: "paid" 与 status: "failed" 既能在运行时读取，也能让编译器把整个对象连同载荷一起收窄。这种模式叫作 可辨识联合（discriminated union） 。

处理完每个成员后，剩余值的类型是 never，即 底类型（bottom type） 。把默认分支的值传给接受 never 的函数，可以在以后新增成员却忘记处理时产生编译错误。

这项穷尽性保证只覆盖编译器已信任的联合。JSON、消息队列和 JavaScript 调用方可以提供任意值，因此外部数据仍应从 unknown 开始验证，再进入可辨识联合。

交叉、重名属性与运行时值

对象交叉把约束叠加到同一个值上。若 A 要求 id: string，B 要求 createdAt: Date，那么 A & B 同时要求这两个字段。类型别名本身不会生成拥有这些字段的对象。

重名且兼容的属性会继续缩小。例如 { mode: string } & { mode: "safe" } 的 mode 是 "safe"。重名但不兼容的属性会交叉成 never，例如 { id: string } & { id: number }。

属性冲突不会按对象展开顺序选择“最后一个值”。JavaScript 的对象展开确实会覆盖重名属性，但那是运行时求值规则；交叉类型要求一个最终值同时满足两项静态约束。把两者混为一谈，常会诱发不安全的 as A & B。

组合第三方类型前应先查看重名键及其含义。若业务上确实要替换字段，应先用 Omit 移除旧约束再添加新约束；若两个字段含义不同，应直接改名，而不是用断言压过冲突。

示例

下面四个程序依次展示原始类型联合、可辨识联合、对象交叉，以及带公共交叉上下文的联合。每段代码都使用 TypeScript 6.0.3 的 strict 模式完成类型检查，并由本地 tsx 实际执行。

收窄联合类型

标识符可以来自数字数据库键，也可以来自外部字符串。函数先用 typeof 确定成员，再调用该成员专属的方法。

数字分支可以调用 padStart()，因为 toString() 已经产生字符串。字符串分支不需要断言；前一个分支提前返回后，控制流中只剩 string。

这里的联合只表达接受两种输入，并不规定两个表示法是否可能指向同一客户。去重、范围和空字符串属于领域规则，仍要由函数或更外层的验证器明确处理。

用判别字段保持状态与载荷对应

每个支付状态都有自己的必填载荷。switch 检查 status 后可以直接访问对应字段，默认分支则证明当前联合已被穷尽。

type PaymentState =
  | { status: "pending"; attempt: number }
  | { status: "paid"; receipt: string }
  | { status: "failed"; reason: string };

function assertNever(value: never): never {
  throw new Error(`Unhandled payment: ${JSON.stringify(value)}`);
}

function summarize(state: PaymentState): string {
  switch (state.status) {
    case "pending":
      return `pending attempt ${state.attempt}`;
    case "paid":
      return `paid with ${state.receipt}`;
    case "failed":
      return `failed: ${state.reason}`;
    default:
      return assertNever(state);
  }
}

const states: PaymentState[] = [
  { status: "pending", attempt: 2 },
  { status: "paid", receipt: "rcpt-81" },
  { status: "failed", reason: "card expired" },
];

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

pending attempt 2
paid with rcpt-81
failed: card expired

如果加入 { status: "refunded"; reference: string } 却不增加 case，默认分支中的 state 就不再是 never，TypeScript 会在 assertNever(state) 处报错。

将模型改成 { status: "pending" | "paid" | "failed"; attempt?: number; receipt?: string; reason?: string } 会丢失对应关系。那种类型允许 paid 缺少 receipt，也允许它携带互相矛盾的字段。

用交叉类型组合独立能力

订阅者同时满足身份与偏好两份契约。接收 Subscriber 的函数可以安全使用两侧字段，因为调用方必须提供完整交叉类型。

type HasIdentity = {
  id: string;
  email: string;
};

type HasPreferences = {
  locale: "en" | "zh";
  digest: boolean;
};

type Subscriber = HasIdentity & HasPreferences;

function deliveryLabel(subscriber: Subscriber): string {
  const schedule = subscriber.digest ? "daily" : "off";
  return `${subscriber.id}:${subscriber.locale}:${schedule}`;
}

const subscriber: Subscriber = {
  id: "acct-17",
  email: "[email protected]",
  locale: "zh",
  digest: true,
};

console.log(deliveryLabel(subscriber));
console.log(Object.keys(subscriber).sort().join(","));

acct-17:zh:daily
digest,email,id,locale

第二行输出来自实际对象的键，而不是 Subscriber 类型。删除对象字面量中的 email 会产生编译错误；删除类型别名却不会改变任何运行时对象。

这里两份契约没有重名键，所以组合直接。实际项目中若两侧都声明 locale，应先确认类型与语义一致，再决定保留交叉、重命名还是显式重塑对象。

给联合的每个成员附加公共上下文

导入结果仍由判别字段保留两种载荷，但每个成员还必须携带 batchId。括号先形成联合，外层交叉再把批次上下文应用到所有成员。

type ImportResult = (
  | { kind: "accepted"; records: number }
  | { kind: "rejected"; errors: string[] }
) & { batchId: string };

function report(result: ImportResult): string {
  if (result.kind === "accepted") {
    return `${result.batchId}:accepted:${result.records}`;
  }

  return `${result.batchId}:rejected:${result.errors.join("|")}`;
}

const results: ImportResult[] = [
  { kind: "accepted", records: 18, batchId: "batch-4" },
  {
    kind: "rejected",
    errors: ["missing email", "invalid locale"],
    batchId: "batch-5",
  },
];

for (const result of results) {
  console.log(report(result));
}

batch-4:accepted:18
batch-5:rejected:missing email|invalid locale

batchId 可在收窄之前读取，因为联合的每条路径都有这项交叉约束。records 与 errors 仍属于各自成员，只有检查 kind 后才能使用。

括号表达了运算分组，也让维护者一眼看出公共上下文的作用范围。公共部分继续扩大时，应给它命名，而不是重复粘贴到每个联合成员。

陷阱

把联合类型当作属性合集

修复方法： 添加稳定的字面量判别字段并先收窄。若两个字段确实总要同时存在，模型需要的是交叉或一份完整对象类型，而不是联合。

用可选字段模拟不同状态

修复方法： 为每种状态定义一个完整成员，让同一个字面量字段区分它们。只在字段对该成员本身确实可缺少时才使用 ?。

以为 & 会合并运行时对象

修复方法： 通过显式对象字面量、经过审查的展开或构造函数创建真实值，然后让编译器检查结果。不要把 as A & B 当作对象合并操作。

忽略交叉中的重名冲突

修复方法： 在组合前审查 keyof 的重叠部分。需要替换字段时使用 Omit<Old, "id"> & NewId 明确写出意图，并为运行时转换添加测试。

用通用默认分支吞掉新成员

修复方法： 让剩余值赋给 never 或传入 assertNever()。外部未知值应在进入联合之前验证，不能借默认分支混入静态状态处理。

在外部边界直接断言联合类型

修复方法： 立即把解析结果放进 unknown，验证非空对象、精确判别值和每个成员的必填字段，再返回领域联合。解析失败和未知判别值都要有明确结果。

延伸阅读

• TypeScript Handbook：Everyday Types
• TypeScript Handbook：Object Types
• TypeScript Handbook：Narrowing
• TypeScript Handbook：Discriminated unions