跳到正文

我所理解的 TypeScript 最佳实践(12):用泛型保留类型关系,用 extends 写约束和条件

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

设置页的选项可以保存字符串,也可以保存数字。读取一个选项时,传进去的值如果是字符串,返回值也应该保留字符串类型。泛型可以把这两处连起来,让一次调用的输入决定这次调用的返回类型。对象字段、keyof 和索引访问的写法可以先读《用对象类型表达字段约束》。

如果已经拿到了两个具体类型,需要判断它们能否在回调或存储接口里互相替换,见《按输入和输出设计泛型的协变与逆变》。

泛型类型通过类型实参生成具体类型

Option<Value> 声明的是一份可以重复使用的对象类型,Value 只在这个类型别名里有效。写 Option<number> 就是在类型位置给它一个实参,value 的类型随之确定。整个过程发生在类型检查期间。

type Option<Value> = { label: string; value: Value };

const frame: Option<string> = { label: '原生标题栏', value: 'native' };
const zoom: Option<number> = { label: '100%', value: 100 };

这里变量的类型已经写出来了,检查器用它检查右侧对象。普通类型别名要求写出类型实参,或者使用声明时提供的默认类型。

泛型函数可以从每次调用的实参推断类型

type Option<Value> = { label: string; value: Value };

function getOptionValue<T>(option: Option<T>) {
  return option.value;
}

const frame = getOptionValue({ label: '原生标题栏', value: 'native' }); // string
const zoom = getOptionValue({ label: '100%', value: 100 }); // number
const exactFrame = getOptionValue<'native'>({ label: '原生标题栏', value: 'native' }); // 'native'

getOptionValue<T> 自己声明了 T,再把它传给 Option<Value>,让参数的 value 和返回类型共用一份类型信息。前两次调用由 TypeScript 根据实参推断 T,最后一次显式指定字面量类型 'native'。函数体用 T 检查实现是否对每次调用成立,实际运行时只读取 option.value。

函数声明也可以显式写上返回类型 : T。这里直接返回 option.value,检查器已经能推断出相同的结果。

extends 在泛型声明里限制可传入的类型

给同一个 getOptionValue() 加上 <T extends string | number>,读取字段的逻辑照旧,调用方只能传值类型能赋给 string | number 的选项。

type Option<T> = { label: string; value: T };

function getOptionValue<T extends string | number>(option: Option<T>) {
  return option.value;
}

const frame = getOptionValue<'native'>({ label: '原生标题栏', value: 'native' }); // 'native'
const zoom = getOptionValue<number>({ label: '100%', value: 100 }); // number
const mixed = getOptionValue<string | number>({ label: '缩放', value: 100 }); // string | number

// @ts-expect-error boolean 无法赋给 string | number。
getOptionValue<boolean>({ label: '启用', value: true });

// @ts-expect-error 联合中仍有 boolean。
getOptionValue<string | boolean>({ label: '启用', value: 'native' });

把类型看作它允许的值的集合。A | B 允许 A 或 B 中的值,T extends A | B 要求 T 能赋给这个联合。A、B、A | B 以及更窄的成员类型都可能符合。假如 C 里有联合之外的值,C 和 A | C 都不符合。示例里即使实际传入的值是 'native',显式指定的类型 string | boolean 仍有 boolean 成员,所以那次调用报错。any 有特殊的可赋值规则,也能被显式传进约束。

JavaScript 子类可以比父类多出属性。按 TypeScript 的对象结构来想,两件事能同时成立。子类实例的成员更多,满足父类要求的值也包含这些子类实例,因此子类实例类型所描述的值可以是更窄的集合。把一个已有的 { label: string; value: number } 对象交给只要求 { label: string } 的函数也是同样的道理。它已经具备 label,value 仍留在原对象上。具体例子见对象赋值怎样匹配字段。

对象约束要求必备字段,保留额外字段

T extends { x: number; y: number } 让函数体能读取两个数字坐标。额外字段可以保留在 T 里,调用者仍然能用它。下面用两个能通过的实参和两个会报错的实参对照。

function retainPoint<T extends { x: number; y: number }>(point: T) {
  return point;
}

const point = retainPoint({ x: 0, y: 1, z: 2 });
point.z; // number

// @ts-expect-error 缺少必填字段 y。
retainPoint({ x: 0 });

// @ts-expect-error y 必须是数字。
retainPoint({ x: 0, y: '1' });
给 T 的类型 是否符合约束 原因
{ x: number; y: number } 是 两个必填字段都存在。
{ x: number; y: number; z: number } 是 z 会留在推断结果里。
{ x: number } 否 缺少 y。
{ x: number; y?: number } 否 y 仍可能缺席。
{ x: number; y: string } 否 y 的类型不同。
unknown 否 还没有证据表明它是带两个数字字段的对象。
any 是 any 可以越过这层静态检查。
never 是 never 能赋给任意类型,但正常运行时没有可传入的 never 值。

如果给函数的是 unknown,要先检查对象及字段。这里的约束还允许直接传带 z 的对象字面量,因为函数会把整份对象推断为 T。显式把 T 写成只有 x 和 y 的具体类型后,直接传对象字面量会按这个具体目标做多余属性检查。

条件类型用 extends 在两个结果之间选择

在类型别名右侧,A extends B ? X : Y 会检查 A 能否赋给 B,成立就得到类型 X,否则得到 Y。例如 100 extends number ? 'numeric' : 'other' 的结果是字面量类型 'numeric'。把 100 换成类型参数,就能让同一个别名根据传入的类型选择结果。

type BooleanValueKey<T> = T extends boolean ? 'value' : never;

type FrameKey = BooleanValueKey<'native'>; // never
type EnabledKey = BooleanValueKey<true>; // 'value'

计算 BooleanValueKey<'native'> 时,把 T 换成 'native'。'native' 不能赋给 boolean,于是选 never。换成 true,条件成立,得到 'value'。never 表示没有可用的值,和其他类型做联合时不会增加成员。

泛型约束已经可用,条件类型仍可能待求值

假设一个文档读取 API 支持两种模式。'text' 返回字符串,'bytes' 返回字节数组。调用方知道自己传的是哪一种时,返回类型也应该跟着确定。

type ReadMode = 'text' | 'bytes';
type ReadResult<Mode extends ReadMode> = Mode extends 'text' ? string : Uint8Array;

declare function readDocument<Mode extends ReadMode>(path: string, mode: Mode): ReadResult<Mode>;

const text = readDocument('notes.md', 'text'); // string
const bytes = readDocument('notes.md', 'bytes'); // Uint8Array

function readPreview<Mode extends ReadMode>(mode: Mode) {
  const result = readDocument('notes.md', mode);
  const content: string | Uint8Array = result;

  // @ts-expect-error 调用者也可能传入 'bytes'。
  const textOnly: string = result;

  return result;
}

const preview = readPreview('text'); // string

检查 readPreview() 的函数体时,Mode extends ReadMode 只约束调用者可以传什么。函数体把读取结果保留为 ReadResult<Mode>,等调用者传入具体模式再选择返回类型。这就是条件类型的延迟求值。虽然此时还没选中分支,赋给 string | Uint8Array 仍然安全,因为这个目标能接住两种结果。调用 readPreview('text') 时,Mode 推断为 'text',同一份返回类型这时算成了 string。这里的 declare 只用于演示 API 的类型签名。

把这个 API 包进另一个函数时,可以像 readPreview() 一样继续传递泛型参数。给包装函数标注 string | Uint8Array 会抹掉这层对应关系,传入 'text' 时也只能得到联合类型。模式和结果已经由一份固定的类型表描述时,可以用 ResultByMode[Mode] 直接查表。条件类型适合按输入的结构选择结果,例如从数组取元素类型。

有时约束看起来已经足够窄,条件却还留在类型里。可以用布尔键的赋值对照弹窗观察这个差异。TypeScript 的条件类型说明也给出了条件何时可以先保留。

直接检查类型参数会逐个处理联合成员

条件左边直接写类型参数 T 时,TypeScript 会给联合中的每个成员算一次条件,再把各次结果用 | 合并。这叫分布式条件类型。所有普通类型都能赋给 unknown,写 T extends unknown 就可以让各成员各走一遍真分支。

type ArrayOfEach<T> = T extends unknown ? T[] : never;
type ArrayOfWhole<T> = [T] extends [unknown] ? T[] : never;

type Separate = ArrayOfEach<string | number>; // string[] | number[]
type Together = ArrayOfWhole<string | number>; // (string | number)[]
  1. ArrayOfEach<string | number> 分两次代入。第一次用 string,所以真分支的 T[] 是 string[]。第二次用 number,得到 number[]。合并后,数组要么全是字符串,要么全是数字。
  2. ArrayOfWhole<string | number> 的左侧是元组 [T],编译器按普通条件检查整个 [string | number]。条件仍然成立,但此时真分支里的 T 还是 string | number。同一个数组可以同时装字符串和数字。

官方示例用 any,把这两行的 unknown 换成 any,结果一样。写 T[K] extends U 时,左边是索引访问类型,编译器会先取出 T[K] 的结果,再做一次整体检查。想按每个键分别查值,就先写 K extends unknown,再在真分支里查当前的 T[K]。

这里的 [T] 是只有一个位置的元组类型。它保留整个 T 作为第一个元素的类型。数组和元组的位置、长度与只读约束见《用元组描述位置固定的数据》。

infer 从匹配成功的类型里取出一部分

如果有 readonly string[],想得到元素类型 string,可以写一个数组形状,把想取出的部分标成 infer Item。infer 声明的是条件类型里的局部类型变量,写在 extends 右边用于匹配的类型中。匹配成功后,? 右边的真分支可以使用它。

type ElementOf<T> = T extends readonly (infer Item)[] ? Item : never;
type MutableElementOf<T> = T extends (infer Item)[] ? Item : never;

type Word = ElementOf<readonly string[]>; // string
type Score = ElementOf<number[]>; // number
type Missing = ElementOf<boolean>; // never
type ReadonlyIsNotMutable = MutableElementOf<readonly number[]>; // never

对 readonly string[],TypeScript 找到一个 Item,让 readonly Item[] 和输入匹配,于是 Item 是 string。boolean 匹配不到数组形状,走 never 分支。要提取函数返回类型,可以把匹配形状换成 () => infer Result。

number[] 可以交给只读数组的使用方,所以也匹配 readonly (infer Item)[]。反过来,用 T extends (infer Item)[] 匹配时,readonly number[] 会落到假分支,因为目标数组允许 push() 等写操作。元组也有这个方向的区别。对象字段的 readonly、可选字段 ? 有各自的兼容规则,见《用对象类型表达字段约束》。

type GetterResult<T> = T extends () => infer Result ? Result : never;

type Message = GetterResult<() => string>; // string
type CountList = GetterResult<() => readonly number[]>; // readonly number[]
type Missing = GetterResult<string>; // never

把 GetterResult 的输入换成 () => readonly number[],Result 得到完整的数组类型。遇到带参数的函数,可以照手册的返回类型示例把匹配形状写宽。下面的例子只提取返回值,保留 Promise 那一层。

type FunctionResult<F> = F extends (...args: never[]) => infer Result ? Result : never;

type RenderPreview = (documentPath: string, zoom: number) => Promise<boolean>;
type PreviewResult = FunctionResult<RenderPreview>; // Promise<boolean>

这里的 ...args: never[] 只出现在条件类型的匹配形状里,用来匹配参数各异的函数签名。它没有调用 RenderPreview,也没有改变该函数要求的两个参数。需要把函数的参数和返回类型都提取出来时,可以用内置的 Parameters<F> 和 ReturnType<F>。

重载根据这一次传入的实参匹配签名

同一个函数名可以有多条重载签名。下面的声明让一个实参的调用返回值本身,让两个实参的调用返回一个带 value 字段的对象。declare 只声明类型,供编译器检查调用。

declare function readSetting<T>(value: T): T;
declare function readSetting<P, K extends keyof P>(object: P, key: K): { value: P[K] };

const settings = { frame: 'native', zoom: 100 };
const byValue = readSetting(settings.zoom); // number
const byKey = readSetting(settings, 'zoom'); // { value: number }

byValue 调用只传了数字,T 推断成 number,套用第一条的返回类型。byKey 调用传了对象和键名,P 是设置对象,K 是 'zoom',返回类型按第二条的 { value: P[K] } 计算。匹配重载后,调用表达式按这条签名来检查。至于函数怎样运行,则由 JavaScript 函数体决定。

any 和 unknown 会让同一个条件得到不同结果

any 可以参与绝大多数赋值,unknown 表示具体类型未知,读取它的属性前需要先做检查。一个交集可以用来观察两者的区别。

type DetectAny<T> = 0 extends 1 & T ? true : false;

type DetectedAny = DetectAny<any>; // true
type DetectedUnknown = DetectAny<unknown>; // false
type DetectedNumber = DetectAny<number>; // false

1 & any 的结果仍是 any,所以 0 能赋给它。1 & unknown 和 1 & number 都只允许 1,这时 0 无法赋值。这种条件适合工具类型在处理 any 时切换到专门的分支。

| 和 & 的常见组合,以及它们遇到 never、unknown、any 时的区别,见《用联合类型表达备选,用交集类型叠加约束》。

读一段带 extends 的声明时,先找出这一次代入的类型,再看 extends 在类型参数列表里还是在 ? 的左边。前者决定调用能不能通过,后者决定产出什么类型。拿不准条件是否已经化简时,可以分别把结果赋给某一分支的类型和覆盖两个分支的类型,观察编译器能保证哪一步。

示例按 TypeScript 6.0.3 的严格模式检查。可以把任意一个代码块单独复制到 example.ts,执行 npx --package=typescript@6.0.3 tsc --ignoreConfig --strict --noEmit --target es2023 example.ts。

泛型布尔键与具体布尔键的赋值对照

这里把 T 限制在 string | number,再观察一个筛选布尔键的条件。具体传入字符串时能直接得到 never,在泛型函数体里,同一条条件还能留在参数类型上。

type BooleanValueKey<T> = T extends boolean ? 'value' : never;
type PendingKey<T extends string | number> = BooleanValueKey<T>;
type ConcreteKey = PendingKey<'native'>; // never
type UncheckedKey = PendingKey<any>; // 'value'

function checkBooleanKey<T extends string | number>(value: T, key: PendingKey<T>) {
  const allowed: string | number = value;
  const possibleKey: 'value' = key;

  // @ts-expect-error 编译器还不能把 key 当成 never。
  const noKey: never = key;
}

传入具体类型时得到 never,传入受约束的泛型 T 时条件仍留在类型中

按约束检查时,value 可以赋给 string | number。key 则可以赋给覆盖两条分支的 'value',却还不能赋给 never。通常的字符串、数字及其字面量会走到 never。显式传入 any 也能通过泛型约束,但 PendingKey<any> 会保留 'value'。

这个条件进入 Vue 的属性映射后,连没有用到泛型的相邻字段也可能受到影响。Vue 专题中的纯 TypeScript 例子对照了直接读取与类型索引,并给出对应的检查器实现。