跳到正文

我所理解的 TypeScript 最佳实践(16):让局部实现保留推断,用注解约束公开接口

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

把草稿列表从读取本地文件改成读取缓存时,函数内部的数据结构可能会变。调用方只需要标题和标识,缓存路径和修改时间属于实现细节。这类跨模块接口适合先写出返回类型,让 TypeScript 在实现改动时检查它是否还符合调用约定。函数内部的局部变量和简单辅助函数,通常可以让编译器从表达式推断。

局部变量和回调可以沿用已有的类型信息

下面的函数整理草稿标题列表,去掉标题两端的空白和空字符串。参数类型说明调用方要传入什么。函数体里的标题、过滤结果和最终返回值都有足够的信息可以推断。

function getDraftTitles(rawTitles: readonly string[]) {
  const titles = rawTitles.map(title => title.trim());
  return titles.filter(title => title.length > 0);
}

rawTitles 的元素是 string,所以 .map() 给回调参数 title 提供了 string 类型。这就是上下文类型。编译器继续沿着返回值推断出 titles 和整个函数的返回类型都是 string[]。如果已经给一个箭头函数指定了函数类型,参数也能从这份签名获得。单独写参数注解适合签名需要自己定义的地方。变量推断和回调上下文见 TypeScript 手册的类型注解。

在返回值上写出调用方可以依赖的字段

假设草稿列表最初返回文件标识和标题,后来为了显示缓存提示,维护者给返回对象加了 cachePath。下面同时保留两种写法,观察调用方得到什么类型。

type DraftRecord = {
  cachePath: string;
  id: string;
  title: string;
};

export type DraftSummary = {
  id: string;
  title: string;
};

export function getDraftDetails(record: DraftRecord) {
  const { cachePath, id, title } = record;
  return { cachePath, id, title };
}

export function getDraftSummary(record: DraftRecord): DraftSummary {
  const { id, title } = record;
  return { id, title };
}

getDraftDetails() 的推断结果包含 cachePath,调用方可以直接依赖它。若以后删除这个字段,依赖它的调用就需要跟着修改。对于已经约定只返回标题和标识的接口,DraftSummary 把约定写在函数签名上。若有人把返回字面量里的 id 错写成 key,编译器会直接指出实现不符合签名,调用方仍然按 DraftSummary 读取。导出异步函数时,同一份约定可以写成 Promise<DraftSummary>。参见 TypeScript 手册的返回类型注解。

限制可见的类型和限制实际返回的字段是两步。例如直接 return record 也能通过 DraftSummary 的结构检查,因为记录已经有 id 和 title。运行时返回的仍是原记录。接口确实只应交出两个字段时,像上面那样构造一个新对象。这一点在 IPC 返回值、JSON 响应和 SDK 接口上尤其容易影响调用方。

回调先用上下文,公共签名按契约决定

组件内部的小函数和只给同一模块使用的回调,可以优先使用推断。即使函数有 export,如果它只在同一应用内部使用,而且调用方确实需要随实现获得精确类型,例如测试工厂或泛型包装函数,保留推断仍然有用。需要跨包维护兼容性、让实现对齐接口,或从模块声明直接了解可用字段时,写出边界类型更合适。

如果只想检查一份配置或回调符合约定,还要在当前模块读取它推断出的细节,可以用 satisfies。如果希望调用方只依赖签名列出的字段,就用类型注解。两种写法的配置对照见《用 satisfies 检查类型并保留推断》。

有些包还会开启 isolatedDeclarations。这个选项要求导出声明提供足够的信息,方便工具从单个文件生成声明。它可能要求给推断不够直接的导出补注解。是否启用取决于声明生成流程。见 TypeScript 的 isolatedDeclarations 选项。