一项要求还是多种可能:联合与交叉
从值的集合理解 | 与 &,解释字段为何看起来相反,以及 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; // nevertype 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 为 stringconst missingAge: I = namedObject;// @ts-expect-error 不满足 A:缺 nameconst 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,也不符合 Bconst 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,但邮件任务缺少 toconst 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 邮件渠道必须有 toconst missingRecipient: Delivery = { taskId: "welcome-3", channel: "email" };
type BothChannels = Email & Sms; // neverDelivery 表示共同的 Base 要求始终成立,同时允许 Email 或 Sms。ExpandedDelivery 把这组要求分别写进两个分支,约束等价;这是这里交叉对联合的分配,与条件类型的分配不是同一个语法机制。
BothChannels 则要求 channel 同时为 email 和 sms,没有值能满足,因此整个类型归约为 never。字段越多并不意味着更合理;增加互相矛盾的条件会让模型没有合法实例。
这个设计保留了渠道与必填字段的关系,但不验证地址格式,也不承诺禁止一切额外属性。可选字段模型适合允许数据尚未齐全的草稿;已经确定渠道、准备发送的任务需要更强的约束。类型应跟随业务允许的状态,而不是为了消除报错而放宽。相关完整建模见请求状态。
查阅与验证
阅读类型时,先将 & 翻译成“同一个值同时满足两边”,将 | 翻译成“至少满足一边”;然后分别追踪允许的值、字段要求以及 keyof 提取的键名。遇到联合时保留完整成员,再判断当前位置能共同依赖哪些信息。
本章示例按普通业务对象、严格模式理解;所有 TypeScript 代码块按本章顺序合并后使用 TypeScript 6.0.3 strict/noEmit 检查,包含预期报错。该检查验证静态契约,不代替运行时代码测试。类型集合的整体位置见类型系统全景。
这一页,先记到这里。