跳到正文

我所理解的 TypeScript 最佳实践(9):用对象类型表达字段约束

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

一个设置项已经有 label 和 value,只用标签的函数能直接接收它。另一个函数需要每个设置项都有 description 这个键,但允许读取结果是 undefined。TypeScript 的对象类型可以分别写清字段有什么、哪些字段必有、读取会得到什么类型。

对象赋值检查目标需要的字段

{ label: string } 要求对象提供一个字符串类型的 label。现成对象多出 value 也符合要求。给变量标注较窄的接口后,编译器只允许通过这个变量读取接口声明的字段,原对象仍然有 value。

const option = { label: '100%', value: 100 };
const labelOnly: { label: string } = option;

labelOnly.label; // string
option.value; // number

这叫结构类型兼容。接收标签的函数可以复用同一份设置项,即使设置项还带着函数用不到的值。如果把对象字面量直接写在 labelOnly 的赋值位置,检查器知道你正在为一份已知类型构造对象,就会额外检查你在这里写出的属性名。

// @ts-expect-error 直接给出对象字面量时,value 不在目标类型里。
const labelOnly: { label: string } = { label: '100%', value: 100 };

这层检查最有用的时候是拼错可选字段。例如弹窗接受 title 和可选的 closeOnEscape,少写一个字母之后,普通的结构比较仍然能通过,因为 title 在、可选字段也允许缺省。直接把这份配置写在调用里,编译器可以当场指出拼错的名字。

declare function openDialog(options: { title: string; closeOnEscape?: boolean }): void;

// @ts-expect-error 直接传入的配置对象写错了属性名。
openDialog({ closeOnEscap: true, title: '设置' });

const dialog = { closeOnEscap: true, title: '设置' };
openDialog(dialog); // 现成对象有 title,满足结构要求

实际要把配置抽成变量复用时,可以在创建配置的地方用类型标注或 satisfies 保留拼写检查。接收已有对象时,API 仍然可以只要求自己需要的字段。TypeScript 团队在多余属性检查的设计说明里用可选字段的拼写错误解释了这两个目标。

遇到字段缺失、索引签名或对象字面量的报错时,可以从目标类型逐项检查。见《按目标类型判断赋值是否成立》。

交集要求同一个对象同时满足两份类型

A & B 表示能同时赋给 A 和 B 的值。对对象来说,可以先看各自要求的字段,再看同名字段要符合哪些限制。

type Labeled = { label: string };
type Measured = { value: number };
type LabeledMeasure = Labeled & Measured;

const setting: LabeledMeasure = { label: '100%', value: 100 };

这里取交集的是两组允许赋值的对象。setting 有 Labeled 要求的字符串标签,也有 Measured 要求的数字值,能同时赋给两种类型。同名字段也按这条规则处理。

type OptionalLabel = { label?: string };
type RequiredLabel = { label: string };
type Label = OptionalLabel & RequiredLabel;

const present: Label = { label: '缩放' };

// @ts-expect-error 空对象不满足 RequiredLabel。
const absent: Label = {};

Label 的效果就是 { label: string },label 变成了必填字段。{ label: '缩放' } 同时满足两份类型,{} 只能满足允许省略的那一份。下面把结果直接写到普通赋值里,再比较两个约束彼此冲突时会怎样。

type Label = { label?: string } & { label: string };
const caption: Label = { label: '缩放' };
const text: string = caption.label;

type ConflictingLabel = { label: string } & { label: number };
type ConflictingValue = ConflictingLabel['label']; // never

// @ts-expect-error 字符串不能同时满足 string 和 number。
const fromText: ConflictingLabel = { label: '缩放' };

// @ts-expect-error 数字也无法同时满足两个类型。
const fromNumber: ConflictingLabel = { label: 100 };

同名字段的两个约束都生效时,结果可能更精确,也可能像 ConflictingValue 一样没有可用的值。如果同名字段的值也是对象,可以按相同规则继续取交集。见同名字段的嵌套对象示例。

问号控制字段能否省略,undefined 控制字段可以存什么

label?: string 可以省略 label,读取缺失字段会得到 undefined。label: string | undefined 则要求对象带这个键,可以显式给它 undefined。

type OptionalLabel = { label?: string };
type PresentLabel = { label: string | undefined };

const optional: OptionalLabel = {};
const present: PresentLabel = { label: undefined };

// @ts-expect-error PresentLabel 要求 label 这个键存在。
const missing: PresentLabel = {};

这两种声明在严格模式下读取 label 都得到 string | undefined。如果开启 exactOptionalPropertyTypes,label?: string 允许省略这个键,但显式写 { label: undefined } 时,需要把 undefined 写进它的值类型。label: string | undefined 在这个设置下仍允许显式写 undefined。

新项目建议显式开启 exactOptionalPropertyTypes。strict 本身不会打开它。比如保存配置时,缺少 label 可以表示「沿用当前值」,而含有 label: undefined 可以表示「清除当前值」。对象展开和 Object.hasOwn() 都能观察到这个差别。

type Patch = { label?: string | undefined };
const current = { label: '缩放' };
const keep: Patch = {};
const clear: Patch = { label: undefined };

const keptLabel = { ...current, ...keep }.label; // 运行时是 '缩放'
const clearedLabel = { ...current, ...clear }.label; // 运行时是 undefined

维护旧项目时,可以先用 tsc --noEmit --exactOptionalPropertyTypes 查看诊断。需要清除字段的接口,明确写出 | undefined。只需要省略字段的调用,就让键缺席。Vue、Node.js 和 Nuxt 的配置示例见《严格模式》。

readonly 保护通过当前类型进行的写入

收到用户配置后,如果函数只负责读配置,就可以用 readonly 标出不该由它改写的字段。这个约束按字段生效。

type Panel = {
  readonly appearance: { zoom: number };
};

const panel: Panel = { appearance: { zoom: 100 } };
panel.appearance.zoom = 110; // zoom 没有 readonly

// @ts-expect-error appearance 本身是只读字段。
panel.appearance = { zoom: 120 };

普通对象的结构兼容检查一般忽略字段的 readonly 修饰符。同一个对象也可能经由可写引用发生变化。用它表达当前 API 的读写意图时,仍要按需要为内部字段或数组单独声明只读。数组的反向赋值边界见《用元组描述位置固定的数据》。

keyof 取字段名,方括号取字段的类型

下面用一个普通对象类型查键和值。keyof Setting 得到字段名的联合。Setting['zoom'] 取一个字段,Setting['label' | 'zoom'] 取两个字段的值类型再合成联合。问号允许省略 hint,所以查询它的读取类型时结果带 undefined。

type Setting = { hint?: string; label: string; zoom: number };

type SettingKeys = keyof Setting; // 'hint' | 'label' | 'zoom'
type Zoom = Setting['zoom']; // number
type LabelOrZoom = Setting['label' | 'zoom']; // string | number
type Hint = Setting['hint']; // string | undefined

从现成的变量出发,可以先用类型位置的 typeof 拿到类型,再按键查值。settings.zoom 在 JavaScript 运行时读取实际数字,(typeof settings)['zoom'] 在类型声明里读取数字的类型。

const settings = { label: '100%', zoom: 100 };

type Keys = keyof typeof settings; // 'label' | 'zoom'
type Zoom = (typeof settings)['zoom']; // number
const zoom = settings.zoom; // 实际值是 100

映射类型可以逐个生成字段和修饰符

固定几个字段也可以用映射类型。[K in keyof Setting] 表示对每个键各生成一个字段,右侧的 Setting[K] 取这个键对应的类型。这里先不用泛型,用普通对象看出每次代入什么。

type Setting = { label: string; zoom: number };

type BoxedSetting = {
  [K in keyof Setting]: { value: Setting[K] };
};

const boxed: BoxedSetting = {
  label: { value: '100%' },
  zoom: { value: 100 },
};

轮到 'label' 时会生成 label: { value: string }。轮到 'zoom' 时生成 zoom: { value: number }。方括号后的冒号只负责引出值类型,键的可选性由 ? 或 -? 决定。

直接映射 keyof Setting 时的写法 键的可选性
[K in keyof Setting]: … 继承对应字段的可选性。
[K in keyof Setting]?: … 设为可选。+? 的效果相同。
[K in keyof Setting]-?: … 设为必填。

「继承」来自直接按原对象的键映射,冒号在三种写法里都一样。用 readonly [K in keyof Setting] 可以加上只读,-readonly [K in keyof Setting] 可以去掉只读。

type OptionalLabel = { label?: string };

type RequiredLabel = {
  [K in keyof OptionalLabel]-?: OptionalLabel[K];
};

type PresentLabel = { label: OptionalLabel['label'] };
type RequiredRead = RequiredLabel['label']; // string
type PresentRead = PresentLabel['label']; // string | undefined

RequiredLabel 等同于 Required<OptionalLabel>,会去掉可选标记和由此带来的 undefined。PresentLabel 把原字段的读取类型填进必有的键,因此保留了 undefined。同一种变换要应用到多个对象时,可以把 OptionalLabel 换成泛型参数。修饰符的完整写法见映射类型手册。

Required 让字段必填

对普通对象 T = { label?: string },Required<T> 和 T & Required<T> 都要求有一个字符串类型的 label。原来的可选字段也会进入 keyof T,所以这里加交集既没增加键,也没增加字段约束。

可调用对象还有调用签名。Required<T> 映射字段,T & Required<T> 同时要求值能按 T 的签名调用。

type Formatter = ((text: string) => string) & { label?: string };

const fields: Required<Formatter> = { label: '标题' };
const formatter: Formatter & Required<Formatter> = Object.assign((text: string) => text.trim(), { label: '标题' });

formatter(' 示例 ');

// @ts-expect-error fields 缺少调用签名。
const callable: Formatter & Required<Formatter> = fields;

只需要配置字段的 API 可以使用 Required<T>。如果 API 还会调用这个值,类型也要保留调用签名。改动泛型映射后,还可以在实际调用签名里检查赋值。

映射可以改变输出字段名

从一份设置类型生成初始值对象时,可以在映射的 as 后写出新键名。左边的 K 还是原来的字段名,冒号右边可以继续用它读取原类型。

type Setting = { label: string; zoom: number };

type InitialSetting = {
  [K in keyof Setting as `initial_${K}`]: Setting[K];
};

const initial: InitialSetting = { initial_label: '缩放', initial_zoom: 100 };

轮到 'zoom' 时,输出键是 'initial_zoom',值类型取自 Setting['zoom']。as 后如果得到 never,就不会生成那个键。只想删除几个固定字段时,Omit<Setting, 'label'> 更直接。需要根据原名生成新名时,用键重映射可以生成新键名,同时保留原字段的值类型。

已知键用字段声明,运行时键用索引签名

配置只允许几个固定字段时,可以用普通对象、Pick 或 Omit 明确列出范围。比如编辑面板只允许更新 label 和 zoom,可以把这两项挑出来,再用 Partial 允许每次只更新其中一项。

type Setting = { id: string; label: string; zoom: number };
type SettingPatch = Partial<Pick<Setting, 'label' | 'zoom'>>;

const patch: SettingPatch = { zoom: 125 };

按文档 ID 缓存名称时,键要等到运行时才能知道,可以写字符串索引签名。同一对象的具名字段也必须满足索引签名的值类型。noUncheckedIndexedAccess 会让未知键的读取类型包含 undefined。已知键只有 'light' 和 'dark' 时,Record<'light' | 'dark', string> 会要求两项都存在。

type Titles = { [id: string]: string | undefined };
const byDocument: Titles = { intro: '入门' };
const missing = byDocument['appendix']; // string | undefined

const byTheme: Record<'light' | 'dark', string> = {
  dark: '深色',
  light: '浅色',
};

扩展对象契约时保留字段冲突检查

两个命名接口共享字段时,interface … extends … 会在声明时检查继承来的字段是否兼容。直接写 A & B 时,检查器允许先表达这组约束。字段冲突会反映在交集结果里,使用它时才可能暴露为 never。

interface PanelBase {
  id: string;
}

interface ReadingPanel extends PanelBase {
  zoom: number;
}

// @ts-expect-error id 必须与 PanelBase 中的类型兼容。
interface InvalidPanel extends PanelBase {
  id: number;
}

要描述一份具名对象契约,可以用 interface 或 type。这里用接口扩展来检查同名字段的约定。需要从已有类型计算映射、联合或交集时,就用 type 为计算结果命名。

示例按 TypeScript 6.0.3 的严格模式检查。每个代码块都可以单独复制到 example.ts,用 npx --package=typescript@6.0.3 tsc --ignoreConfig --strict --noEmit --target es2023 example.ts 检查。