跳到正文

我所理解的 TypeScript 最佳实践(10):用联合类型表达备选,用交集类型叠加约束

我所理解的 TypeScript 最佳实践

  1. 为什么选择 TypeScript
  2. 严格模式
  3. 使用常量枚举来管理状态
  4. 按运行环境处理 TypeScript 代码
  5. 类型检查、Lint 与测试
  6. TypeScript 7 升级与工具链兼容
  7. 用 satisfies 检查类型并保留推断
  8. 用 import type 区分类型依赖和运行时依赖
  9. 用对象类型表达字段约束
  10. 用联合类型表达备选,用交集类型叠加约束(当前)
  11. 用元组描述位置固定的数据
  12. 用泛型保留类型关系,用 extends 写约束和条件
  13. 按目标类型判断赋值是否成立
  14. 按输入和输出设计泛型的协变与逆变
  15. 先校验外部数据,再使用收窄后的类型
  16. 让局部实现保留推断,用注解约束公开接口
  17. 从一份定义派生配置、命令和事件的类型
  18. 用判别联合排除互斥的状态组合
  19. 用 never 表示没有值的类型
  20. 用逆向映射推断还原字段类型

编辑器里的文档可能正在加载、已经读到内容,或者读取失败。把三个状态写成一个联合,代码拿到任意状态都能用同一个类型接收。另一处代码需要对象同时带有文档 ID 和修改时间,可以用交集把两份要求合起来。

联合允许满足任意一份类型

string | number 接受字符串或数字。对对象也一样,A | B 允许能赋给 A 或 B 的对象。一份对象同时满足两边也可以通过。下面把对象先存入变量,便于单独观察结构类型的赋值规则。

type Named = { name: string };
type Measured = { width: number };
type Source = Named | Measured;

const icon = { name: 'logo' };
const banner = { name: 'cover', width: 960 };

const first: Source = icon;
const second: Source = banner;

读 Source 时,只能直接使用每一种可能都具备的字段。想读某一个成员独有的属性,可以用 in、typeof 或一个固定的标记字段缩小范围。keyof (A | B) 也只给出对整个联合都有效的键。

type FromFile = { source: 'file'; path: string };
type FromNetwork = { source: 'network'; url: string };
type Input = FromFile | FromNetwork;
type CommonKey = keyof Input; // 'source'

function locate(input: Input) {
  return input.source === 'file' ? input.path : input.url;
}

用判别联合把状态和字段写在一起

文档加载成功时才能使用 content,失败时才有错误原因。给每个成员一个不同的 state,判断它以后,TypeScript 就知道该读哪个字段。这种结构叫判别联合。

type DocumentState = { state: 'loading' } | { content: string; state: 'ready' } | { reason: string; state: 'failed' };

function getStatusText(document: DocumentState) {
  switch (document.state) {
    case 'loading': {
      return '正在加载';
    }
    case 'ready': {
      return document.content;
    }
    case 'failed': {
      return document.reason;
    }
    default: {
      const exhaustive: never = document;
      return exhaustive;
    }
  }
}

如果新增 { state: 'cancelled' },原来的 switch 会让这种状态落到 default,never 赋值就会报错。每种状态的字段各自必填,调用方也就无法构造一个成功但没有内容的对象。

如果状态还会随异步任务变化,可以把更新、读取和穷尽检查放在同一个例子里看。见《用判别联合排除互斥的状态组合》。

交集要求同一个值符合两边的约束

A & B 接受能同时赋给 A 和 B 的值。对象字段名不重叠时,结果同时拥有两边要求的字段。同名字段则取它们值类型的交集。比如一个面板接受浅色或深色主题,嵌入式阅读器另有一条约束,只接受浅色主题。

type Panel = { theme: 'light' | 'dark' };
type Embedded = { documentId: string; theme: 'light' };
type ReadingPanel = Panel & Embedded;

const reading: ReadingPanel = { documentId: 'guide', theme: 'light' };

// @ts-expect-error Embedded 要求浅色主题。
const darkReading: ReadingPanel = { documentId: 'guide', theme: 'dark' };

如果同名字段一边要求字符串、一边要求数字,这个字段就只能是 never。当彼此冲突的是判别字段,例如 { state: 'ready' } & { state: 'failed' },TypeScript 可以把整个交集化简为 never。编译器不能从两份冲突的声明里自动选择优先级。

同名字段是对象时继续取交集

两份类型也可以同时要求有一个 options 对象,只是在对象里要求不同的字段。取 Combined['options'] 时,两边都声明了 options,所以取出来的类型是 { id: string } & { count: number }。两份约束都落在同一个 options 对象上。规则见 TypeScript 手册的交集类型。

type WithId = { options: { id: string } };
type WithCount = { options: { count: number } };
type Combined = WithId & WithCount;

type Options = Combined['options']; // { id: string } & { count: number }
const options: Options = { count: 3, id: 'outline' };

// @ts-expect-error options 同时要有右侧要求的 count。
const withoutCount: Options = { id: 'outline' };

对这份普通对象,把 Options 展开成 { id: string; count: number } 就能读懂有哪些字段。类型提示可能会保留 &,访问 options.id 和 options.count 时仍然可以分别读到两边的类型。如果下一层也有同名字段,仍适用同一条规则。比如把右侧改成 { options: { id: number } },内层的 id 就同时要满足 string 和 number,所以 Combined['options']['id'] 会是 never。

用相同结构做对象展开,运行时会依次复制顶层属性。同名的 options 出现两次,结果保留后赋进去的整个对象。可以用下面的例子对照读取结果。

const left = { options: { id: 'outline' } };
const right = { options: { count: 3 } };
const spread = { ...left, ...right }; // { options: { count: number } }

spread.options.count; // number
// @ts-expect-error 右边的 options 覆盖了左边的 options。
spread.options.id;

要建模「先用默认配置,再由用户配置覆盖」,可以用对象展开表达运行时顺序。需要表达对应类型时,用 Omit 从默认类型中移除会覆盖的键,再加上新类型的字段。

type Defaults = { retries: number; theme: 'light' };
type Override = { theme: 'dark' };
type Resolved = Omit<Defaults, keyof Override> & Override;

const config: Resolved = { retries: 2, theme: 'dark' };

never、unknown 和 any 会影响组合的结果

never 表示没有值。给字符串再加一种没有值的选择,结果还是字符串。要求一个值同时符合字符串和 never,结果只能是 never。unknown 接受所有输入,作为交集的另一边时,字符串仍须满足原来的约束。any 允许绕过许多静态检查,和字符串组合时两种结果都会变宽。

type KeepString = string | never; // string
type Empty = string & never; // never
type AnyInput = string | unknown; // unknown
type StillString = string & unknown; // string
type UncheckedChoice = string | any; // any
type UncheckedBoth = string & any; // any

用联合描述确实可能出现的多种输入或状态,用交集描述同一个值要满足的多份要求。字段重名时,可以先写出每边允许的值,再看它们是否有重叠。关于字段、可选标记和对象赋值,见《用对象类型表达字段约束》。

示例用 TypeScript 6.0.3 的严格模式验证,每个代码块都可以独立检查。