跳到正文

我所理解的 TypeScript 最佳实践(7):用 satisfies 检查类型并保留推断

我所理解的 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. 用逆向映射推断还原字段类型

给 Markdown 阅读器加一张主题表,暖纸只填背景色,雾蓝还要指定前景色。表里缺一套主题,渲染器就少一项配置。可给整张表加了类型注解以后,写 themes.paper.toUpperCase() 又会报错,虽然暖纸的背景色明明是字符串。

检查主题表,也保留每一项的类型

ThemeName 列出应用已经支持的主题名。这里的 Record<ThemeName, ThemeValue> 为每个主题名声明一个必填属性,属性值可以是颜色字符串,也可以是一组配色。

type ThemeName = 'paper' | 'mist';
type ThemeValue = string | { background: string; foreground: string };
type ThemeTable = Record<ThemeName, ThemeValue>;

const themes: ThemeTable = {
  paper: '#f7f2e8',
  mist: { background: '#e6eef3', foreground: '#233545' },
};

themes.paper.toUpperCase(); // 报错,ThemeValue 中的对象成员没有这个方法

注解能在定义处发现漏写的主题和填错的值,也规定了之后通过 themes 读到的类型。每个属性按 ThemeValue 使用,因此调用前要先判断值是哪种。去掉 : ThemeTable 后,编译器能看出 paper 是字符串,但把 mist 写成 msit 时,它也只会如实推断出一个叫 msit 的属性。

保留同一份 ThemeTable,把检查移到对象字面量上。

type ThemeName = 'paper' | 'mist';
type ThemeValue = string | { background: string; foreground: string };
type ThemeTable = Record<ThemeName, ThemeValue>;

const themes = {
  paper: '#f7f2e8',
  mist: { background: '#e6eef3', foreground: '#233545' },
} satisfies ThemeTable;

themes.paper.toUpperCase(); // paper 是 string
themes.mist.background; // mist 的 background 是 string

把 mist 改成 msit,错误会标在拼错的键上。删掉整行 mist,错误会指出缺了必填属性。把 foreground 改成数字,错误会落在这个字段。恢复正确值后,编辑器里仍能看到每一项各自的类型。可以把第二段贴进 TypeScript Playground,开着 strict,依次试这三个改动。TypeScript 4.9 的发布说明用调色板展示了同一个问题。

expr satisfies T 把左侧拿去做一次可赋值检查,就像把 expr 传给一个要求 T 的函数,看看编译器是否接受。整个表达式的类型取自左侧的推断结果。右侧的 T 还会参与左侧的推断。

TypeScript 4.9 为什么需要这个运算符

2016 年的原始提案 #7481 讨论的是,怎样让编译器检查一个表达式符合预期类型。当时可以写类型注解,也可以用 as T,但两种写法承担的职责不同。注解定义了变量对外使用的类型。断言表达的是开发者对值的判断,允许一部分普通赋值检查会拒绝的写法。例如 { type: 'invalidate' } as { type: 'invalidate'; path: string } 可以通过检查,而对象实际缺了 path。

也可以先声明 themes,再写一行 const checked: ThemeTable = themes。下游照常读原来的 themes,具体类型还在,赋值检查也能发现缺项。但检查时右侧已经是变量,原对象多写的键可能通过。这种写法还会在 JavaScript 产物里多出一个变量。

2022 年,Ryan Cavanaugh 在设计讨论 #47920 重新整理了大家想解决的问题。主题表只是其中一种。右侧该写什么类型,取决于业务到底要管键名、覆盖范围,还是每个值的形状。

只允许从已知键中挑选

用户只覆盖自己改过的主题,其他项继续使用应用默认值。用 Partial<Record<ThemeName, string>> 时,每个已知键都可以省略,写出来的键仍要拼对,值必须是字符串。

type ThemeName = 'paper' | 'mist';

const overrides = {
  paper: '#fff7e8',
} satisfies Partial<Record<ThemeName, string>>;

overrides.paper.toUpperCase();
overrides.mist; // 报错,实际对象没有 mist

对这个对象来说,paper 一定存在。把变量声明为 Partial<Record<ThemeName, string>> 后,开启 strictNullChecks 时,读 paper 和读 mist 都要考虑 undefined。这种注解适合先建一个容器,随后还会补字段的代码。例如 const overrides: Partial<Record<ThemeName, string>> = {} 之后可以再写 overrides.mist = '#e6eef3'。声明一份已经写定的覆盖项时,保留实际字段更方便。

每个已知键都要有值

渲染器如果对任意已知主题都要显示一个名称,就需要完整映射。用 Record<ThemeName, string> 检查这份表后,新增主题时,漏补显示名称会在表的定义处报错。

type ThemeName = 'paper' | 'mist';

const themeLabels = {
  mist: '雾蓝',
  paper: '暖纸',
} satisfies Record<ThemeName, string>;

function labelFor(theme: ThemeName) {
  return themeLabels[theme];
}

ThemeName 需要来自独立的约定,例如已支持的主题或公开协议。如果业务允许直接从配置表派生全部主题名,写 type ThemeName = keyof typeof themeLabels 就能少维护一份列表。派生出来的键集合和「必须覆盖外部约定的每个键」是两种需求。

键名开放,只检查值

扩展可以给主题起自己的名字,但登记的值都要包含显示名称。此时用 Record<string, { label: string }>。右侧允许任意字符串键,左侧的结果只保留实际登记的键。

const extensions = {
  nightOwl: { label: '夜读' },
  sepia: { label: '棕褐' },
} satisfies Record<string, { label: string }>;

type ExtensionName = keyof typeof extensions; // 'nightOwl' | 'sepia'

extensions.sepia.label;
extensions.unknownTheme; // 报错,当前表没有这个键

如果变量的职责是接收任意字符串键,并且会在运行时注册或删除主题,就可以用带索引签名的类型注解或 Map。读取动态键时,按实际是否可能缺项处理结果。

给回调提供参数类型

配置表里也可以放函数。下面的两个函数都接收主题名,一个返回长度,另一个返回规范化后的字符串。编译器从函数所处的位置得知 source 是什么类型,这种从外向内获得的类型信息叫上下文类型。

type ThemeTransform = (source: string) => unknown;

const transforms = {
  length: source => source.length,
  normalized: source => source.trim().toLowerCase(),
} satisfies Record<string, ThemeTransform>;

const themeLength = transforms.length(' paper '); // number
const normalizedTheme = transforms.normalized(' PAPER '); // string

右侧给两个 source 提供了 string 上下文。左侧各个函数仍从函数体推断出自己的返回类型。给整张表加 Record<string, ThemeTransform> 注解,则把两项函数的返回类型统一成了 unknown。

三种结果类型分别会留下什么

设计讨论考虑了三种结果。假设目标类型是 T = Partial<{ fontSize: number; zoom: number }>,左侧是 { fontSize: 16 },并且编译器已推断出 E = { fontSize: number }。

候选结果 此后怎样看待 fontSize 和 zoom
T 两项都按可选属性处理。开启严格空值检查时,调用 fontSize.toFixed() 前也要确认它有值。
T & E fontSize 保持必填,zoom 却也进入了结果,可以读取或赋值。
E fontSize 保持必填。访问 zoom 会报错,因为这份对象的类型里没有该属性。

交叉类型 T & E 表示同时符合两份类型,它确实适合「以后允许加 zoom」的需求。但如果目标是 Record<string, string>,同样的处理也会把字符串索引签名带进来。这样一来,即使原表只有 paper,类型也会允许写入 themes.papper = '#fff'。用左侧的类型作为结果,既能保住已知字段,也能让对拼错字段的访问继续报错。

提案还讨论过安全拓宽,也就是想先检查初始化值,再让变量以后能接受同一联合类型的其他成员。这和保留当前值的具体形状是两个方向。例如一个偏好对象的 mode 后续会在 'light' 和 'dark' 间切换。用类型注解声明时,属性可以接收两种值。用 satisfies 检查初始化对象时,属性可以保留初始化时的 'light',后续写入 'dark' 就会报错。最终合入的实现 PR #46827 让 satisfies 检查表达式,同时采用其推断类型。需要拓宽变量时,类型注解仍能直接表达。

type Preferences = { mode: 'light' | 'dark' };

const state: Preferences = { mode: 'light' };
state.mode = 'dark';

const defaults = { mode: 'light' } satisfies Preferences;
defaults.mode = 'dark'; // 报错,mode 的类型是 'light'

配置表自己决定有哪些键时,可以把键名、字段值和使用方的类型都从这张表派生。外部协议已经规定键名时,可以用它检查表是否写全。两种做法的完整例子见《从一份定义派生配置、命令和事件的类型》。

右侧类型会影响左侧推断

const plain = { enabled: true } 的 plain.enabled 通常推断为 boolean,因为对象属性还可以改写。写上 satisfies { enabled: boolean } 后,右侧给属性提供了上下文。在这个例子里,编译器会保留字面量类型 true。这也是 TypeScript 团队在 #55189 中确认的行为。

右侧的 boolean 提供上下文,左侧保留 true,赋值检查通过后得到 enabled 为 true 的类型。

const defaults = { enabled: true } satisfies { enabled: boolean };
defaults.enabled = false; // 报错,enabled 的类型是 true

const state: { enabled: boolean } = { enabled: true };
state.enabled = false;

同样的机制也能把数组字面量推断成元组。反过来,在严格模式下,嵌在对象里的空数组仍会推断成 never[],即便它可以赋给 string[]。要把它用作队列,直接把字段声明为 string[]。

const range = [16, 100] satisfies [number, number];
range[2]; // 报错,两项元组只有索引 0 和 1

const defaults = { items: [] } satisfies { items: string[] };
defaults.items.push('notes.md'); // 报错,items 是 never[]

const queue: { items: string[] } = { items: [] };
queue.items.push('notes.md');

普通字符串字段仍可能推断为 string。如果要保留具体的字符串值供后面的类型使用,可以组合 satisfies 与 TypeScript 3.4 引入的 as const 断言。下面的 labels.paper 是 '暖纸',对象属性在类型层面是只读的。只读配置数组也可以按 readonly Value[] 这一类契约检查。

const labels = {
  mist: '雾蓝',
  paper: '暖纸',
} as const satisfies Record<'paper' | 'mist', string>;

type PaperLabel = (typeof labels)['paper']; // '暖纸'

在实参、返回值和分支末尾使用

satisfies 跟在它检查的表达式后面。写多行对象时,把关键字放在结束花括号的同一行。形如 expr satisfies T 的结果可以继续作为实参或返回值。它随类型语法一起从 JavaScript 产物中擦除,运行时仍然执行左侧表达式。

给 Worker 消息补协议检查

索引 Worker 通过消息接收停止和失效通知。失效通知需要路径。Node.js 的 postMessage 能传多种值,项目还要约束自己发送的消息形状。把检查写在实参里,既能让错误落在发送行,也省得给一次性的对象起变量名。

import type { Worker } from 'node:worker_threads';

type IndexRequest = { type: 'stop' } | { path: string; type: 'invalidate' };

declare const worker: Worker;

worker.postMessage({ type: 'stop' } satisfies IndexRequest);
worker.postMessage({ path: 'notes.md', type: 'invalidate' } satisfies IndexRequest);
worker.postMessage({ type: 'invalidate' } satisfies IndexRequest); // 报错,缺少 path

如果项目已经有参数类型是 IndexRequest 的发送函数,直接传入对象就能检查协议。测试里的全局替身也可以按同一个思路处理。例如 vi.stubGlobal 接受 unknown,可以在 mock 对象旁写 satisfies Partial<MarkerBridge> 来校对写出的几个方法。假如整条测试路径必须使用某个方法,可以用 Pick<MarkerBridge, 'getAppearance'> 把它声明为必填,避免 Partial 允许漏写。

在函数内部检查每块返回值

外观设置常常分成窗口和排版两块恢复。每块需要按同一份 Appearance 检查字段,合并时又要知道哪几个字段一定存在。下面用两项设置简化这个例子。两个 helper 分别就地检查自己的返回对象,公开函数负责检查合并结果是否完整。

interface Appearance {
  fontSize: number;
  zoom: number;
}

function normalizeReading(fontSize: unknown) {
  return {
    fontSize: typeof fontSize === 'number' ? fontSize : 16,
  } satisfies Partial<Appearance>;
}

function normalizeWindow(zoom: unknown) {
  return {
    zoom: typeof zoom === 'number' ? zoom : 100,
  } satisfies Partial<Appearance>;
}

function normalizeAppearance(fontSize: unknown, zoom: unknown): Appearance {
  return { ...normalizeReading(fontSize), ...normalizeWindow(zoom) };
}

如果在 normalizeReading 里写错字段名,错误在那一块就能发现。去掉其中一个 helper 的展开时,错误会出现在最外层的返回值。如果两个 helper 都写成 : Partial<Appearance>,编译器只知道两份结果都有可能缺任何字段,也就无法证明合并后一定完整。

让遗漏的联合分支在编译时报错

当 switch 已经处理了联合类型的所有成员,走到最后的值会收窄为 never。可以直接在这里加一条检查。

type IndexRequest = { type: 'stop' } | { path: string; type: 'invalidate' };

function describe(request: IndexRequest): string {
  switch (request.type) {
    case 'stop':
      return '停止索引';
    case 'invalidate':
      return '重新检查 ' + request.path;
  }
  request satisfies never;
  throw new Error('收到未知的索引请求');
}

给 IndexRequest 加一个 { type: 'refresh' } 后,如果漏写 case,走到检查行的 request 就还有这个成员,编译器会指出它无法赋给 never。代码里的 throw 则负责运行时的异常路径。项目如果已经有接收 never 并抛错的 assertNever,直接调用它也能同时满足两项要求。

在开启 checkJs 的 JavaScript 文件里,可以使用 TypeScript 5.0 新增的 JSDoc @satisfies。例如在声明前写 /** @satisfies {{ label: string }} */,也可以把注释放到调用参数里的括号表达式前。

检查放在哪里

检查放到对象刚写出来的位置时,还能触发 TypeScript 的额外属性检查。下面的 papper 直接写在字面量里,编译器会提示它不是允许的键。对象先放进变量后,只要它已经包含要求的字段且类型兼容,结构类型允许附带其他字段。通过展开带入的额外属性也可能保留下来。

type ThemeLabels = Record<'paper' | 'mist', string>;

const labels = {
  mist: '雾蓝',
  paper: '暖纸',
  papper: '暖纸', // 报错,多写了一个键
} satisfies ThemeLabels;

const existing = { mist: '雾蓝', paper: '暖纸', papper: '暖纸' };

const checked = existing satisfies ThemeLabels;
checked.papper; // 仍然存在,类型是 string

值来自 JSON、磁盘或跨进程消息时,检查要落到运行时。比如 JSON.parse() 的返回类型是 any,紧接着写 satisfies Appearance 也会通过类型检查。把输入先接为 unknown,再通过字段判断、校验器或规范化函数得到可用类型。读入端负责验证真实数据,发送端的 satisfies 可以约束自己写的消息。

总结

我会先看这份类型由谁决定。应用已经有主题名、消息协议或配置接口时,可以在对象写出来的地方用 satisfies 检查契约,后面继续使用实际存在的键和各自推断出的值。变量要逐步补字段、要在联合成员间切换,或者模块想公开统一的接口时,类型注解更直接。对象本身就是唯一来源时,也可以从它派生类型,例如用 keyof typeof config 得到实际的键集合。

拿不准时,可以在编辑器里试两个改动。先把一个字段拼错,看报错能不能落在对象创建处。再悬停一个下游实际要读的字段,看得到的是确定存在的属性,还是契约允许的全部可能性。这两个结果决定了这处代码有没有必要同时保留契约检查和具体推断。