我所理解的 TypeScript 最佳实践(16):让局部实现保留推断,用注解约束公开接口
- 为什么选择 TypeScript
- 严格模式
- 使用常量枚举来管理状态
- 按运行环境处理 TypeScript 代码
- 类型检查、Lint 与测试
- TypeScript 7 升级与工具链兼容
- 用 satisfies 检查类型并保留推断
- 用 import type 区分类型依赖和运行时依赖
- 用对象类型表达字段约束
- 用联合类型表达备选,用交集类型叠加约束
- 用元组描述位置固定的数据
- 用泛型保留类型关系,用 extends 写约束和条件
- 按目标类型判断赋值是否成立
- 按输入和输出设计泛型的协变与逆变
- 先校验外部数据,再使用收窄后的类型
- 让局部实现保留推断,用注解约束公开接口(当前)
- 从一份定义派生配置、命令和事件的类型
- 用判别联合排除互斥的状态组合
- 用 never 表示没有值的类型
- 用逆向映射推断还原字段类型
把草稿列表从读取本地文件改成读取缓存时,函数内部的数据结构可能会变。调用方只需要标题和标识,缓存路径和修改时间属于实现细节。这类跨模块接口适合先写出返回类型,让 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 选项。