跳到正文

我所理解的 TypeScript 最佳实践(8):用 import type 区分类型依赖和运行时依赖

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

一个阅读组件收到 DocumentSnapshot,只用它声明 props 的类型。另一个模块调用 readDocument(),需要在运行时加载读文件的实现。两者都要引用同一个模块,但生成的 JavaScript 对它的依赖不同。只需要类型时写 import type,同一处还需要值时,可以在值导入里用内联 type 标出类型项。

类型导入让逐文件转译有明确依据

Flow 在 2015 年就引入了 import type,让代码可以只引用另一个模块中类的类型,并在转译时删去这条导入。TypeScript 后来的实现 PR 把 Flow 列为已有做法。TypeScript 2.9 也已经支持 import('./document').DocumentSnapshot 这样的类型表达式,允许在类型位置直接引用模块成员。

TypeScript 3.8 加入 import type 和 export type 前,编译器可以根据类型和用途推断哪些导入能在生成 JavaScript 时省略,这个过程叫 import elision。原始实现 PR 记录了两个方向的问题。一边是普通导入只被用作类型,整条导入被省略后,原模块的初始化也没执行。另一边是 Babel 或 transpileModule 这样的逐文件转译器,看见 export { DocumentSnapshot } from './document' 时,单凭当前文件无法知道那个名称只在类型系统中存在,可能把本应删除的转导出留在 JavaScript 里。

有了 export type { DocumentSnapshot } from './document',转译器看到 type 就能删去整条语句。需要执行模块初始化时,用 import './document' 明确表达这条运行时依赖。项目可以用 isolatedModules 让 TypeScript 提前报告某些逐文件转译无法安全解释的写法。这个选项增加检查,编译器仍可按项目做类型检查。

TypeScript 4.5 又允许在具名导入项上单独加 type。它与当时的 preserveValueImports 有直接关系。Vue 或 Svelte 的值可能只在模板里使用,逐文件工具需要保留这些值,同时知道同一条导入里哪些名称可以删掉。内联写法让编译器能逐项决定,也省掉了同一个模块路径出现两次的重复。

整条 type 和内联 type 的编译结果不同

TypeScript 5.0 用 verbatimModuleSyntax 简化了导入省略规则。声明级 type 删去整条导入或导出,内联 type 删去它修饰的单个名称。普通导入声明按书写的模块语法保留。下面用 TypeScript 6.0.3 的 transpileModule 验证 ESNext 输出,启用 verbatimModuleSyntax,各行只列出与 ./document 有关的 JavaScript。

TypeScript 写法 生成的 JavaScript 模块会被加载吗
import type { DocumentSnapshot } from './document' 没有这条导入 不会因这条语句加载
import { type DocumentSnapshot } from './document' import {} from './document' 会
import { type DocumentSnapshot, readDocument } from './document' import { readDocument } from './document' 会
import './document' import './document' 会

空的 import {} 虽然没有绑定名字,仍然是运行时模块请求。整条只需要类型时,使用 import type。同一处还会调用 readDocument 时,用内联 type:

import { type DocumentSnapshot, readDocument } from './document';

export async function loadSnapshot(path: string): Promise<DocumentSnapshot> {
  return readDocument(path);
}

如果整个文件只剩类型,TypeScript 可能在产物里留下一个 export {},用来保持这个文件的模块身份。它不再引用 ./document。要验证模块是否会被加载,可以查产物有没有对应的导入路径。对照 verbatimModuleSyntax 的输出规则,还可以判断某条导入会不会留下。

类用作类型时也能通过 import type 引用

类名可以出现在类型位置和运行时表达式里。同一个 Client,作为参数类型时只参与检查,传给 new 或用于 extends 时需要实际的类值。即使只导入类型,也可以在类型位置写 typeof Client,取得构造器的类型:

import type { Client } from './client';

export type DocumentClient = Client;
export type ClientConstructor = typeof Client;

根据 TypeScript 3.8 对类型导入的约定,把同一个导入用于 new Client() 或 class NamedClient extends Client {} 时,TypeScript 会报错。此时应该使用普通值导入。判断依据是这个名字在当前文件里的用途。

如果模块提供默认导出,可以写 import type Client from './client'。需要用命名空间访问多个类型时,也可以写 import type * as ClientTypes from './client'。声明级 import type 的默认导入和具名导入要分开写。

跨文件只引用一处类型时,可以直接写 type Snapshot = import('./document').DocumentSnapshot。这里的 import() 是类型表达式。值表达式里的 import('./document') 则会发起运行时动态导入。

模块入口也明确标出类型导出

如果 index.ts 把文档相关的接口和函数汇总起来,转导出也要标出类型。这样只引入契约的调用方可以沿着公开入口访问它,生成的 JavaScript 里也能看清哪些转导出需要加载实现。

export type { DocumentSnapshot } from './document';
export { readDocument } from './document';

一个专门汇总类型的入口,可以用 TypeScript 5.0 加入的 export type * from './document-types'。明确的类型导入和转导出可以避免仅因共享契约就在 JavaScript 中增加模块依赖。两个模块如果还会相互调用运行时函数,实际的运行时循环仍需要从模块职责上处理。

编译器管模块语义,Lint 管写法

使用 verbatimModuleSyntax 的项目,可以先靠 TypeScript 检查哪些名称需要显式标成类型。直接用 Node.js 的类型擦除功能执行 TypeScript 时,type 标记也很重要。Node.js 只擦除类型语法,普通导入会被视为值导入。目标模块只定义了接口时,缺少 type 可能在加载模块时才报错。编译选项仍要按 实际运行环境 选择。

  • 希望编辑器根据用途提示并修复类型导入时,可以选 @typescript-eslint/consistent-type-imports。它的部分诊断会和 verbatimModuleSyntax 重叠,项目可以按是否需要 Lint 的自动修复来选择。consistent-type-imports 文档
  • 想拦住整条都是内联 type 的导入,用 @typescript-eslint/no-import-type-side-effects,它会建议把 type 提到声明上。no-import-type-side-effects 文档
  • 同一模块的值和具名类型分成两条时,可以用 import-x/no-duplicates 的 prefer-inline 检查。手动整理时,把类型合并到原来的值导入处。遇到带构建查询或有初始化顺序要求的导入,先确认是同一个模块请求,再核对生成的 JavaScript。import-x 的重复导入规则