跳到正文

我所理解的 TypeScript 最佳实践(13):按目标类型判断赋值是否成立

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

草稿编辑器同时保存标题、正文和未保存状态。把编辑器里的对象交给 saveDraft() 时,函数的参数类型只需要列出标题和正文。TypeScript 用这两个要求检查实参,已有对象可以带着编辑器自己的字段一起传入。

赋值时由目标类型决定哪些操作必须成立

在 const a: A = b 里,A 是目标类型,右侧表达式 b 的类型是源类型。检查方向是 源类型 → 目标类型。写 a.title 时,编译器只知道 A 对 title 作出了什么保证,因此右边必须能兑现这个保证。

type Draft = { body: string; title: string };

const editorState = { body: '第一段', isDirty: true, title: '周报' };
const draft: Draft = editorState;

draft.title.toUpperCase(); // 通过

// @ts-expect-error Draft 没有声明编辑器状态。
draft.isDirty;

editorState 提供了两个类型正确的字段,多出来的 isDirty 可以留给编辑器用。赋值也没有复制对象或剥掉字段。后续代码通过 draft 访问这个对象时,看到的是 Draft 声明的结构。这个判断会递归到内部对象和函数属性,规则见 TypeScript 的类型兼容文档。

必须存在的键和可能读到的值要分别检查

目标类型如果写了 title: string,就同时要求有这个键和读到字符串。title?: string 缺少第一项保证,title: string | undefined 缺少第二项。

type DraftHeader = { title: string };

const incomplete: { title?: string } = {};
const pending: { title: string | undefined } = { title: undefined };

// @ts-expect-error incomplete 可能缺少 title。
const missingKey: DraftHeader = incomplete;
// @ts-expect-error pending 的 title 也可能是 undefined。
const missingValue: DraftHeader = pending;

const completed: DraftHeader = { title: '周报' };
const optional: { title?: string } = completed;
const normalized: DraftHeader = { title: incomplete.title ?? '未命名草稿' };

optional 允许省略 title,接收一个带标题的对象也成立。normalized 则在数据进入要求标题的流程前补上了默认值。只有实际业务允许缺席时,才把目标字段写成可选。可选字段和 exactOptionalPropertyTypes 的写法见对象类型篇。

索引签名允许按键读取,具名字段才能保证某个键存在

搜索结果用文档 ID 作键时,字典一开始可以是空的。{ [id: string]: string } 允许使用字符串作索引,也约束已有条目的值。它没有承诺某个 ID 一定存在。

type TitlesById = { [id: string]: string };
type PinnedTitle = { pinned: string };

const titles: TitlesById = {};

// @ts-expect-error 字典没有保证 pinned 这个条目存在。
const pinned: PinnedTitle = titles;

如果 API 依赖一组必有条目,可以列出字段,也可以用 Record<'pinned' | 'recent', string>。如果业务会传入运行时才知道的 ID,就允许查找失败并处理缺失值。noUncheckedIndexedAccess 会让未声明的索引读取得到可能为 undefined 的类型。相关选项见严格模式篇。

any 放在哪里会改变赋值结果

把字典的值类型改成 any,字典仍可能为空。给整个值标注 any 时,TypeScript 则会放行赋值,即使运行时缺少目标要求的字段。

type PinnedTitle = { pinned: string };

const dictionary: { [id: string]: any } = {};
const unchecked: any = {};

const uncheckedTitle: PinnedTitle = unchecked;
// @ts-expect-error 字典可能没有 pinned,值类型为 any 也不会补出这个键。
const missingTitle: PinnedTitle = dictionary;

const title = dictionary['pinned']; // 类型是 any,实际值为 undefined。

如果 API 确实需要 pinned,接到字典后先确认它是字符串,再交给 API。允许从任意输入读数据时,可以用 unknown 接住它,把检查留在输入边界。

在创建配置的地方检查多余字段

对象结构兼容允许已有对象带额外字段。直接把对象字面量交给有明确参数类型的函数时,TypeScript 还会做多余属性检查,能在配置创建处发现拼错的属性。

type SaveOptions = { keepHistory?: boolean; title: string };
declare function saveDraft(options: SaveOptions): void;

// @ts-expect-error keepHistroy 拼错了。
saveDraft({ keepHistroy: true, title: '周报' });

const fromEditor = { keepHistory: true, title: '周报', zoom: 100 };
saveDraft(fromEditor);

const options = { keepHistory: true, title: '周报' } satisfies SaveOptions;
saveDraft(options);

配置需要抽成变量时,可以在字面量处用 satisfies 检查。调用时传入完整的业务对象也可以,只要它已经具备保存函数需要的字段。要给对象保留额外字段的约定,最好在来源类型中表达。关于 satisfies 怎样保留推断,见配置检查篇。

外部输入先检查,再交给有明确契约的函数

读文件或接收消息时,可以先用 unknown 接住尚未验证的值,再检查需要的字段。any 会让赋值直接通过,编译器也就失去了指出格式不符的机会。unknown 会把这项检查留给输入边界的代码。需要检查整份外部数据时,可以接着看类型收窄和输入校验。

type DraftHeader = { title: string };

function hasDraftTitle(value: unknown): value is DraftHeader {
  return typeof value === 'object' && value !== null && 'title' in value && typeof value.title === 'string';
}

function readDraftTitle(raw: unknown): string {
  if (hasDraftTitle(raw)) {
    return raw.title;
  }
  throw new Error('草稿缺少字符串标题');
}

写参数类型时,先列出函数真正会读取、写入或调用的成员。遇到赋值诊断时,从目标类型要求的成员开始找,依次检查键是否存在、值是否兼容,以及报错是否发生在一个函数成员的参数上。最后一种情况要顺着实参传递的方向推导,见《按输入和输出设计泛型的协变与逆变》。

每段示例都可单独放进 example.ts,用 npx --package=typescript@6.0.3 tsc --ignoreConfig --strict --noEmit --target es2023 example.ts 检查。