我所理解的 TypeScript 最佳实践(14):按输入和输出设计泛型的协变与逆变
- 为什么选择 TypeScript
- 严格模式
- 使用常量枚举来管理状态
- 按运行环境处理 TypeScript 代码
- 类型检查、Lint 与测试
- TypeScript 7 升级与工具链兼容
- 用 satisfies 检查类型并保留推断
- 用 import type 区分类型依赖和运行时依赖
- 用对象类型表达字段约束
- 用联合类型表达备选,用交集类型叠加约束
- 用元组描述位置固定的数据
- 用泛型保留类型关系,用 extends 写约束和条件
- 按目标类型判断赋值是否成立
- 按输入和输出设计泛型的协变与逆变(当前)
- 先校验外部数据,再使用收窄后的类型
- 让局部实现保留推断,用注解约束公开接口
- 从一份定义派生配置、命令和事件的类型
- 用判别联合排除互斥的状态组合
- 用 never 表示没有值的类型
- 用逆向映射推断还原字段类型
一个保存回调能处理所有草稿,放到「保存已发布文档」的入口里仍然可以工作,因为已发布文档也有草稿所需的字段。另一个回调只会处理已发布文档,把它挂到「保存任意草稿」的入口就有问题。判断函数能否替换,先看谁提供参数、谁产生结果。这两个方向决定了泛型在函数里的协变和逆变。下面沿用赋值篇的两个术语,赋值左边的声明是目标类型,右边表达式的类型是源类型。
输入要接住调用方能传的所有值
假设 PublishedDraft 多了一个必有的 publishedAt。PublishedDraft 可以赋给 Draft,因为它已经有了草稿需要的字段。让两个类型分别出现在回调参数里,就要从调用方开始检查。
type Draft = { title: string };
type PublishedDraft = Draft & { publishedAt: string };
type Handler<T> = (draft: T) => void;
const saveDraft: Handler<Draft> = draft => {
console.log(draft.title);
};
const savePublished: Handler<PublishedDraft> = draft => {
console.log(draft.publishedAt.toUpperCase());
};
const publishedHandler: Handler<PublishedDraft> = saveDraft;
publishedHandler({ publishedAt: '2026-11-13', title: '周报' });
// @ts-expect-error 调用方可以只传 title,savePublished 还需要 publishedAt。
const draftHandler: Handler<Draft> = savePublished;
左边的 Handler<PublishedDraft> 告诉调用方,每次调用都要提供完整的已发布文档。右边的 saveDraft 能接住它,所以赋值成立。反向赋值如果通过,调用方就能写 draftHandler({ title: '周报' }),而 savePublished 会读取缺失的 publishedAt。
PublishedDraft 能赋给 Draft,回调的可替换方向却是 Handler<Draft> → Handler<PublishedDraft>。这叫逆变。在 const target = source 的函数赋值中,可以把检查方向记成 目标参数 → 源参数。这里使用 strictFunctionTypes 下的函数类型。
输出必须兑现调用方期待的结果
函数如果只返回数据,值由右侧的实现产生,调用方再按左侧声明来读。返回已发布文档的加载器也能当草稿加载器,因为它保证返回草稿所需的字段。
type Draft = { title: string };
type PublishedDraft = Draft & { publishedAt: string };
type Loader<T> = () => T;
const loadPublished: Loader<PublishedDraft> = () => ({
publishedAt: '2026-11-13',
title: '周报',
});
const loadDraft: Loader<Draft> = () => ({ title: '周报' });
const draftLoader: Loader<Draft> = loadPublished;
draftLoader().title;
// @ts-expect-error loadDraft 没有保证返回 publishedAt。
const publishedLoader: Loader<PublishedDraft> = loadDraft;
这次 Loader<PublishedDraft> → Loader<Draft> 与内部类型的方向相同,叫协变。用同一对类型,可以把两种检查写在一起。
| 类型参数出现的位置 | 能通过的赋值方向 | 检查依据 |
|---|---|---|
Loader<T> 的返回值 |
Loader<PublishedDraft> → Loader<Draft> |
右侧实现产生的值能满足左侧承诺。 |
Handler<T> 的参数 |
Handler<Draft> → Handler<PublishedDraft> |
左侧调用方传来的值能被右侧实现处理。 |
同时读写一种数据时,两个方向都要成立
存储接口能读也能写,T 同时出现在输出和输入。用已发布文档存储代替草稿存储,调用方就可能写入一个缺少 publishedAt 的值。反过来用草稿存储代替已发布文档存储,读取结果又可能缺少这个字段。这两个文档类型原本可以单向赋值,放进 Store<T> 后两个方向都无法替换。Store<T> 对 T 是不变的。
type Draft = { title: string };
type PublishedDraft = Draft & { publishedAt: string };
type Store<T> = {
read: () => T;
write: (value: T) => void;
};
declare const drafts: Store<Draft>;
declare const published: Store<PublishedDraft>;
// @ts-expect-error 通用入口可能写入普通草稿。
const draftStore: Store<Draft> = published;
// @ts-expect-error 读取时无法保证拿到已发布文档。
const publishedStore: Store<PublishedDraft> = drafts;
function getDraftTitle(reader: Pick<Store<Draft>, 'read'>) {
return reader.read().title;
}
getDraftTitle(published); // 调用者只需要读取能力
可以按调用方实际使用的能力写接口。只展示标题的代码只接收读取能力,写入路径继续遵守自己的数据约束。这样,同一个已发布文档存储可以安全地供展示代码复用。
用函数属性保留回调参数的严格检查
接口里的 handle: (value: T) => void 是函数属性,handle(value: T): void 是方法签名。开启 strictFunctionTypes 后,TypeScript 仍对方法参数使用更宽松的双变检查。两边参数只要有一个方向兼容,就可能通过,因此写给调用方传入实现的回调契约时,优先用函数属性。
type Draft = { title: string };
type PublishedDraft = Draft & { publishedAt: string };
interface PropertyHandler<T> {
handle: (draft: T) => void;
}
interface MethodHandler<T> {
handle(draft: T): void;
}
declare const strictHandler: PropertyHandler<PublishedDraft>;
declare const methodHandler: MethodHandler<PublishedDraft>;
// @ts-expect-error 函数属性会拒绝只接受 PublishedDraft 的实现。
const strictDraft: PropertyHandler<Draft> = strictHandler;
const looseDraft: MethodHandler<Draft> = methodHandler; // 方法签名允许这次赋值
阅读第三方声明时,先辨认成员是函数属性还是方法。遇到回调类型报错,检查实现能不能处理调用方声明的所有输入。确实只应处理已发布文档时,可以收窄入口,或者在回调里先判断状态,再调用专用实现。TypeScript 2.6 的严格函数类型说明解释了方法例外的兼容性背景。
TypeScript 有时直接比较泛型实参
比较同一个泛型声明的两个实例时,编译器有时能利用推断出的型变方向,直接比较传给泛型的类型。比较下面的两个接口时,则可以逐个比较成员。即使成员用了不同的参数名,只要调用签名兼容,赋值也成立。
type Draft = { title: string };
type PublishedDraft = Draft & { publishedAt: string };
interface Handler<T> {
handle: (draft: T) => void;
}
interface Sink<T> {
handle: (value: T) => void;
}
declare const handler: Handler<Draft>;
const sameDeclaration: Handler<PublishedDraft> = handler;
const differentDeclaration: Sink<PublishedDraft> = handler;
两次赋值中,值的传递方向相同。目标的调用者会给 handle 一个 PublishedDraft,源实现接收 Draft,它能处理这个输入。区别在于比较发生在哪一层。
| 比较方式 | 编译器检查的内容 |
|---|---|
| 按泛型实参比较 | 两边来自同一个 Handler<T>。利用 T 的逆变关系,检查目标实参 PublishedDraft 能否赋给源实参 Draft。 |
| 按结构比较 | 比较两个接口的 handle 签名。因为 handle 是函数属性,检查目标签名的参数 PublishedDraft 能否赋给源签名的参数 Draft。 |
同一泛型也可能回到结构比较。映射类型参与时,只看编辑器展开后的字段,无法推断编译器会选择哪种比较方式。哪条路径会被采用是编译器的实现细节,可能随版本变化。相关行为见 TypeScript 泛型文档中的型变说明。
TypeScript 4.7 加入了 in、out 和 in out 来标注逆变、协变和不变。日常的回调和存储接口可以由编译器根据使用位置推断型变。显式标注只在基于泛型实参的比较中生效。结构比较仍然会检查成员。
写或修改泛型工具时,可以做两次类型检查。先用具体对象检查生成的字段,再把工具放进真实 API 的参数或返回值里,检查调用方依赖的赋值。回调入口若写了 any,还要看它出现在泛型实参、整个值还是字段值的位置。编译通过只表示该次类型检查放行,运行时依赖的字段仍要由调用契约或校验来保证。
每段示例都可单独放进 example.ts,用 npx --package=typescript@6.0.3 tsc --ignoreConfig --strict --noEmit --target es2023 example.ts 检查。