一项要求还是多种可能:联合与交叉

从值的集合理解 | 与 &,解释字段为何看起来相反,以及 keyof、字段冲突和业务建模的关系。

本章目录CONTENTS ↓

通知有邮件和短信两种形式:一条通知可以选择其中一种,但无论选择哪种,都必须带上公共的任务 ID。这里有两种不同要求:“满足其中一种”和“同时满足”。如果只靠把所有字段放在一个对象里并设为可选,就无法说明哪些字段必须一起出现。

联合 | 表达候选,交叉 & 叠加要求。要准确使用它们,先用小的值集合看清运算,再回到对象与通知例子。关键是区分哪些值符合类型,以及类型声明了哪些字段要求;不能把对象交叉理解为覆盖式字段合并。

第一节:对符合类型的值求并集与交集

类型可以理解为一组条件;所有符合条件的值构成这个类型描述的集合。例如,"red" | "blue" 描述两个可能的字符串值,string 描述所有字符串值。

type RedBlue = "red" | "blue";
type BlueGreen = "blue" | "green";
type ColorUnion = RedBlue | BlueGreen;
// "red" | "blue" | "green"
type ColorIntersection = RedBlue & BlueGreen;
// "blue"

A | B 对值取并集:至少符合一边就可以,也允许同时符合两边。A & B 对值取交集:同一个值必须同时符合两边。

值 符合 RedBlue 符合 BlueGreen 符合联合 符合交叉
"red" 是 否 是 否
"blue" 是 是 是 是
"green" 否 是 是 否

类型中的 | 是包含“同时成立”的或,不要求两边互斥。这里的运算是类型运算;JavaScript 表达式中的同名位运算符处理的是运行时值。

把有限集合换成更大的类型,仍然按同一思路推导:

type TextOrNumber = string | number;
type TextAndNumber = string & number; // never
type BlueText = string & "blue"; // "blue"
type AnyText = string | "blue"; // string

普通值不能同时是字符串和数字,因此 string & number 没有可能值,结果是 never。但 "blue" 本来就是字符串,所以与 string 的交集仍是 "blue",并集则仍是 string。一个集合完全包含在另一个集合里时,并集留下较大的集合,交集留下较小的集合。

值集合模型适合解释这里的普通类型;any 会绕开许多检查,函数兼容性等也有专门规则,不能把编译器的所有行为都当作纯集合代数。联合的基本含义参见官方 Union Types。

第二节:对象字段为何看起来相反

对象类型描述结构要求

type HasName = { name: string };
const person = { name: "小林", age: 20 };
const named: HasName = person; // 通过
// @ts-expect-error 新对象字面量会接受额外属性检查
const fresh: HasName = { name: "小林", age: 20 };

HasName 要求对象具有字符串 name,通常不意味着只能有这一个字段。因此已经存在的 person 能符合它,即使还具有 age。新对象字面量另有额外属性检查,用于发现契约之外的属性;这项检查不把对象类型变成精确字段清单。

这一点来自 TypeScript 的结构兼容规则,字面量检查参见 Excess Property Checks。

交叉叠加要求,因此缩小值的范围

接下来一直使用这两个类型:

type A = { id: string | number; name: string };
type B = { id: number; age: number };
type I = A & B;
// 本例中,I 的字段要求等价于:
type IFields = { id: number; name: string; age: number };
const namedObject = { id: "u1", name: "小林" };
const agedObject = { id: 1, age: 20 };
const completeObject = { id: 1, name: "小林", age: 20 };
const intersectionValue: I = completeObject;
// @ts-expect-error 不满足 B:缺 age,且 id 为 string
const missingAge: I = namedObject;
// @ts-expect-error 不满足 A:缺 name
const missingName: I = agedObject;

符合 I 的同一个对象,必须同时符合 A、B。A 要求 name,B 要求 age,两个字段都必须有;id 则同时受两边约束,(string | number) & number 留下 number。

字段要求增加了,符合要求的值却变少了。 集合里的元素是完整对象值,而不是字段名。completeObject 本来就在两边的值集合中,所以属于交集;& 没有在运行时把两个对象拼接起来。

联合保留完整成员,使用时只能依赖共同信息

type U = A | B;
// 将别名展开后,仍是两个完整结构的联合:
type UExpanded =
| { id: string | number; name: string }
| { id: number; age: number };
const unionA: U = namedObject;
const unionB: U = agedObject;
const unionBoth: U = completeObject;
function inspect(value: U) {
const id: string | number = value.id;
// @ts-expect-error B 没有声明 name
value.name;
// @ts-expect-error A 没有声明 age
value.age;
if ("name" in value) value.name.toUpperCase();
}

三种对象都能进入 U,因为它们至少符合一边。但 inspect 必须能处理所有合法输入:namedObject 没有 age,agedObject 没有 name,因此未收窄时只能直接读取两边都声明的 id。它的值可能来自任一成员,所以类型是 string | number。

这两个问题的答案可以不同:联合接受的值更多,能对每个值共同保证的信息却更少。 官方 Working with Union Types 用同样的区别解释联合的属性访问。

U 不等于只含 id 的对象,也不等于把其余字段都设成可选的对象。以下反例能区分它们:

type OnlyId = { id: string | number };
type LooseObject = { id: string | number; name?: string; age?: number };
const tooSmall: OnlyId = { id: "u2" };
const alsoLoose: LooseObject = { id: "u2" };
// @ts-expect-error 既不符合 A,也不符合 B
const rejectedUnion: U = { id: "u2" };

原联合保留了各成员的完整要求。把 name、age 都设成可选,会放宽这些要求,允许原本不合法的值。收窄的具体方式见类型收窄。

keyof 是语言定义的键名运算

keyof 把问题换成键名。对于本章这样没有索引签名的普通对象类型:

type KeysA = keyof A; // "id" | "name"
type KeysB = keyof B; // "id" | "age"
type IntersectionKeys = keyof I; // "id" | "name" | "age"
type UnionKeys = keyof U; // "id"
type CommonKeys = keyof (A | B); // "id"
type EveryKey = (keyof A) | (keyof B); // "id" | "name" | "age"
type SharedKeyNames = (keyof A) & (keyof B); // "id"
function read(value: U, key: keyof U) {
return value[key];
}

keyof U 取每个联合成员共同声明的键,所以 read 可以直接使用 key 索引,而不必先区分成员。它只提取键名,不会删除 U 中其他字段的要求。keyof I 则包含两边的键,因为交叉要求同一个对象满足两边。

这是 TypeScript 对运算符语义的定义;集合论本身没有预先规定 keyof 如何工作。官方仓库 issue 12948 将普通对象联合取共有键标记为预期行为。上面的读取函数说明这种规则的使用收益,不是对设计历史的推测。

如果需要所有成员出现过的键,可以先对各成员取 keyof,再把键名联合起来。此时 id、name、age 这些键名本身也是字符串值,键名之间的 |、& 仍按并集、交集理解。

观察本例中的什么 A 与 B 的交叉 A 与 B 的联合
符合类型的对象值 两边共同的值 至少符合一边的值
类型声明的键 包含两边的键 只有共同声明的键
id 的值类型 number string 或 number

要对任意对象联合逐成员取键,可以使用分配条件类型;见共有键与全部键。带索引签名、never 等特殊输入应按具体规则核对,不把本例的表格套到所有类型上。官方入口:Keyof Type Operator。

同名字段同时受约束,不按右侧覆盖

type BadName = { name: string } & { name: number };
type ImpossibleName = BadName["name"]; // never
const left = { name: "小林" };
const right = { name: 20 };
const merged = { ...left, ...right };
// merged.name 的类型为 number,后面的同名属性覆盖前面的属性

BadName 要求同一个 name 值同时是 string 和 number,因此该字段的类型为 never。准确结论是字段为 never,不必把整个 BadName 都称为编译器已归约的 never。类型交叉的约束同时生效;对象展开有执行顺序,使用后面的值覆盖前面的值,两者的语义不同。

如果发生冲突的是不同的判别字面量,TypeScript 可以把整个交叉类型归约为 never;通知任务中就会遇到这种情况。普通字段冲突参见 Intersection Types,整体归约参见 Intersections Reduced By Discriminant Properties。

完整案例:通知渠道与共同任务信息

每个通知任务都要有 taskId。邮件任务要有收件地址 to,短信任务要有 phone,而且 channel 应与所需字段对应。如果只把 channel 写成联合,再让两个收件字段都可选,就无法保证这种对应关系。

type LooseDelivery = {
taskId: string;
channel: "email" | "sms";
to?: string;
phone?: string;
};
// 可以通过 LooseDelivery,但邮件任务缺少 to
const incomplete: LooseDelivery = {
taskId: "welcome-1", channel: "email", phone: "10086"
};

将每种渠道的完整要求放入一个成员,再与共同要求组合:

type Base = { taskId: string };
type Email = { channel: "email"; to: string };
type Sms = { channel: "sms"; phone: string };
type Delivery = Base & (Email | Sms);
type ExpandedDelivery = (Base & Email) | (Base & Sms);
const emailTask: Delivery = {
taskId: "welcome-2", channel: "email", to: "reader@example.com"
};
const smsTask: Delivery = {
taskId: "reminder-1", channel: "sms", phone: "10086"
};
// @ts-expect-error 邮件渠道必须有 to
const missingRecipient: Delivery = { taskId: "welcome-3", channel: "email" };
type BothChannels = Email & Sms; // never

Delivery 表示共同的 Base 要求始终成立,同时允许 Email 或 Sms。ExpandedDelivery 把这组要求分别写进两个分支,约束等价;这是这里交叉对联合的分配,与条件类型的分配不是同一个语法机制。

BothChannels 则要求 channel 同时为 email 和 sms,没有值能满足,因此整个类型归约为 never。字段越多并不意味着更合理;增加互相矛盾的条件会让模型没有合法实例。

这个设计保留了渠道与必填字段的关系,但不验证地址格式,也不承诺禁止一切额外属性。可选字段模型适合允许数据尚未齐全的草稿;已经确定渠道、准备发送的任务需要更强的约束。类型应跟随业务允许的状态,而不是为了消除报错而放宽。相关完整建模见请求状态。

查阅与验证

阅读类型时,先将 & 翻译成“同一个值同时满足两边”,将 | 翻译成“至少满足一边”;然后分别追踪允许的值、字段要求以及 keyof 提取的键名。遇到联合时保留完整成员,再判断当前位置能共同依赖哪些信息。

本章示例按普通业务对象、严格模式理解;所有 TypeScript 代码块按本章顺序合并后使用 TypeScript 6.0.3 strict/noEmit 检查,包含预期报错。该检查验证静态契约,不代替运行时代码测试。类型集合的整体位置见类型系统全景。

这一页,先记到这里。