1 / 4概念
Types: Generics and Operators
泛型的价值不是「能写尖括号」,而是让类型跟着实参走:传进去什么,返回什么,键名是哪几个,参数是几元。判断标准是能否用一句话说清一个泛型函数的推断结果,而不是被编辑器自动补全带着走。
1 概念
1.1 一句话定义
泛型是类型参数,让一段类型描述在不同实参下复用。类型运算是另一套语言:在编译期用 keyof、条件、映射、模板字面量从已有类型算出新类型。
1.2 它解决什么问题
- 复用而不失精度:
pick(user, 'id')返回的类型只含id。 - 约束输入:键必须存在,参数个数必须匹配。
- 派生类型:从 schema、接口或常量推导出请求与响应类型。
- 消除重复声明:一处定义,其余由运算生成,避免手写漂移。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 收窄、判别联合、可赋值性 | Types and Narrowing |
声明文件、tsconfig、模块解析 | Declarations and Config |
| 运行时的数据结构与遍历 | Collections and Iteration |
| 校验库的具体 API | 各库文档 |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 类型参数 | 尖括号里的占位符 | 运行时不存在 |
| 约束 | extends 后的上界 | 不是继承实现 |
| 默认类型参数 | 未传实参时的取值 | 与运行时默认值无关 |
| 推断 | 由实参反推类型参数 | 推断失败会退化成宽类型 |
keyof | 键的联合 | 只对对象类型有意义 |
| 索引访问 | T[K] 取值类型 | K 必须是 keyof T 的子集 |
| 条件类型 | T extends U ? X : Y | 裸类型参数会按联合分配 |
infer | 在条件类型里捕获子类型 | 只能出现在 extends 右侧 |
| 映射类型 | 遍历键生成新类型 | 可加重映射与修饰符 |
| 模板字面量类型 | 字符串模式类型 | 可反向推断 |
| 变型 | 协变、逆变、双变 | 显式注解用 in 与 out |
2 机制
2.1 心智模型
泛型函数是「一组类型的函数」:实参进,类型参数出。类型运算则是另一层:把类型当值来算,输入是类型,输出是类型,编译结束后全部消失。
2.2 机制拆解
- 推断位置:类型参数出现在参数、返回值或约束里,编译器按调用点反推;同一参数多处出现时取并集。
- 约束:
T extends U让T至少具备U的成员;没有约束等于unknown。 - 键运算:
keyof T得到键联合,T[K]得到对应值类型,两者配合就是类型安全的索引。 - 条件类型:裸类型参数在联合上分配,
A \| B extends U ? X : Y等价于对每个成员分别求值。 - 关闭分配:写成
[T] extends [U]就不再逐成员分配。 infer:在extends右侧声明占位符,匹配成功时把子类型绑定进去。- 映射类型:
{[K in keyof T]: ...}遍历键;as可以重命名或过滤,返回never的键被丢弃。 - 修饰符:
+readonly、-readonly、+?、-?控制只读与可选。 - 模板字面量:
`${A}-${B}`产生字符串集合;配合infer可解析字符串。 - 变型注解:
in表示只出现在参数位,out表示只出现在返回值位,用错会报运行时。
2.3 完整枚举
类型算子全表:
| 算子 | 写法 | 结果 |
|---|---|---|
| 键联合 | keyof T | 所有键的字面量联合 |
| 索引访问 | T[K] | 该键对应的值类型 |
| 类型查询 | typeof value | 值的类型 |
| 联合 | A | B | 并集 |
| 交叉 | A & B | 交集 |
| 条件 | T extends U ? X : Y | 按条件选择 |
| 推断 | T extends F<infer U> ? U : never | 捕获子类型 |
| 映射 | {[K in keyof T]: T[K]} | 逐键变换 |
| 键重映射 | {[K in keyof T as New<K>]: T[K]} | 改名或过滤 |
| 模板字面量 | `${A}-${B}` | 字符串模式 |
| 元组展开 | [...T, Last] | 追加或拼接 |
| 只读修饰 | readonly T[]、-readonly 映射 | 不变性 |
| 变型 | interface Box<out T> | 显式协变或逆变 |
内建的二十二个工具类型,这是完整集合:
| 工具类型 | 作用 |
|---|---|
Partial<T> | 全部属性变可选 |
Required<T> | 全部属性变必填 |
Readonly<T> | 全部属性变只读 |
Record<K, V> | 以 K 为键、V 为值 |
Pick<T, K> | 只保留指定键 |
Omit<T, K> | 去掉指定键 |
Exclude<T, U> | 联合中排除 U |
Extract<T, U> | 联合中保留 U |
NonNullable<T> | 去掉 null 与 undefined |
Parameters<F> | 参数元组 |
ConstructorParameters<C> | 构造参数元组 |
ReturnType<F> | 返回类型 |
InstanceType<C> | 实例类型 |
ThisParameterType<F> | 显式 this 参数类型 |
OmitThisParameter<F> | 去掉显式 this 后的签名 |
ThisType<T> | 在对象字面量里标注 this |
Awaited<T> | 递归解包 Promise |
NoInfer<T> | 阻断该位置的推断 |
Uppercase<S> | 全大写 |
Lowercase<S> | 全小写 |
Capitalize<S> | 首字母大写 |
Uncapitalize<S> | 首字母小写 |
映射类型的四个修饰符:
| 修饰符 | 写法 | 效果 |
|---|---|---|
| 加只读 | +readonly 或 readonly | 属性只读 |
| 去只读 | -readonly | 去掉只读 |
| 加可选 | +? 或 ? | 属性可选 |
| 去可选 | -? | 属性必填 |
三种变型:
| 变型 | 含义 | 例子 |
|---|---|---|
| 协变 | 返回位置,方向一致 | Dog 可赋给 Animal |
| 逆变 | 参数位置,方向相反 | 参数为 Animal 的函数可赋给参数为 Dog 的函数 |
| 双变 | 方法参数的默认行为 | 关闭 strictFunctionTypes 时的兼容 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 实例化深度 | 约五十层 | 超过报 excessively deep |
| 联合分配开销 | 与成员数成正比 | 条件类型对每个成员求值一次 |
| 递归类型深度 | 数百层后报错 | 尾递归写法可放宽 |
| 泛型参数数量 | 超过三个难读 | 考虑拆函数或对象参数 |
| 编译耗时 | 与实例数量正相关 | 大库的类型检查可到分钟级 |
3 实践
3.1 最小示例
一个泛型联合加一个映射类型。前者展示「实参决定返回值」,后者展示「从已有类型算出新类型」。
type Result<T, E = Error> =
| {ok: true; value: T}
| {ok: false; error: E};
function unwrap<T, E>(result: Result<T, E>): T {
if (result.ok) return result.value;
throw result.error;
}
type Setters<T> = {
[K in keyof T & string as `set${Capitalize<K>}`]: (value: T[K]) => void;
};
type State = {count: number; title: string};
// Setters<State> 展开为
// {setCount: (value: number) => void; setTitle: (value: string) => void}
追踪 unwrap:实参是 Result<number, RangeError>,T 推断为 number,E 推断为 RangeError,返回类型是 number。判空分支 if (result.ok) 把联合收窄到成功成员,result.value 只有在成功时才可访问。
追踪 Setters<State>:keyof State & string 得到 'count' | 'title';as 子句把每个键重命名成 setCount、setTitle;模板字面量类型 set${Capitalize<K>} 逐键计算;值类型 T[K] 保留原字段类型。
3.2 常用操作与参数
| 操作 | 写法 | 说明 |
|---|---|---|
| 保留字面量推断 | function f<const T>(x: T) | 不把 'a' 放宽成 string |
| 阻断推断 | NoInfer<T> | 只在一个位置推断 |
| 取返回类型 | ReturnType<typeof fn> | 不重复声明 |
| 取参数 | Parameters<typeof fn>[0] | 派生第一个参数 |
| 解 Promise | Awaited<Promise<T>> | 递归解包 |
| 只取部分 | Pick<T, 'id' | 'name'> | 显式列出键 |
| 去掉部分 | Omit<T, 'secret'> | 排除敏感字段 |
| 构造映射 | Record<Key, Value> | 键值表 |
| 显式变型 | interface Cache<out T> | 只读容器 |
| 键改名 | 映射类型的 as 子句 | 事件处理器映射 |
| 过滤键 | as K extends 'id' ? never : K | 去掉指定键 |
3.3 标准流程
- 先写运行时实现,再抽类型参数,不要反过来。
- 类型参数只保留真正随实参变化的那些,其余用具体类型。
- 用约束表达前置条件,把错误留在调用点。
- 能从已有类型派生的,就不要手写第二份。
- 类型运算限制在库或工具层,业务代码最多用现成的工具类型。
- 加类型测试:
expectType断言推断结果,防止重构时悄悄放宽。
3.4 与相邻技术的组合
- 收窄:泛型函数的返回值可以参与收窄,但
T本身无法在函数体内被收窄。 - 框架:泛型组件让
items的元素类型传到renderItem。 - 校验库:schema 加
z.infer让运行时校验与静态类型同源。 - API 客户端:路径参数用模板字面量类型表达,拼错在编译期报错。
- ORM:查询构建器用映射类型把表结构变成查询结果类型。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 多态方式 | 泛型 / 联合 / 重载 | 调用方推断质量 |
| 派生方式 | 工具类型 / 手写 / 代码生成 | 维护成本 |
| 约束强度 | 无 / keyof / 自定义 | 错误发现位置 |
| 读法 | 直接标注 / 类型运算 | 新人理解成本 |
| 发布面 | 不导出 / 导出 .d.ts | 兼容责任 |
3.6 决策规则
- 只有类型随实参变化时才用泛型,否则写具体类型。
- 键相关操作一律用
keyof约束,不要用string。 - 派生类型优先用内建工具类型,其次用映射类型,最后才手写。
- 条件类型只写在库内部;业务层用重载表达分派。
- 递归类型必须写明终止条件,并加类型测试防止深度爆炸。
- 发布给他人使用的泛型接口要显式写变型注解。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| 泛型 | 保留精度 | 签名变复杂 | 容器与工具函数 |
| 联合 | 简单直观 | 分支需要收窄 | 有限集合 |
| 函数重载 | 声明清晰 | 实现签名要兼容 | 参数组合分派 |
| 条件类型 | 表达力强 | 难读、易触发深度限制 | 库的类型推导 |
| 工具类型 | 零成本 | 语义隐藏 | 常见变换 |
| 代码生成 | 完全精确 | 构建步骤 | 协议与 schema |
3.8 何时不该用
- 不要在业务函数里写三个以上嵌套的条件类型。
- 不要为「也许将来会泛型」提前抽象。
- 不要用泛型表达简单的字符串联合。
- 不要用深递归类型处理大结构,会拖慢编辑器。
- 不要在没有约束的地方用
T,它等于unknown,调用方得不到任何帮助。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 条件类型对每个联合成员都生效 | 裸类型参数分配 | 用 [T] extends [U] |
infer 得到 unknown | 结构不匹配 | 调整匹配模式 |
| 映射类型丢键 | as 返回 never | 检查重映射条件 |
报 excessively deep | 递归类型过深 | 加终止条件或改数据结构 |
字面量被放宽成 string | 推断默认放宽 | 用 const 类型参数 |
| 工具类型结果不符合预期 | exactOptionalPropertyTypes 交互 | 显式写映射 |
| 重载选错 | 重载顺序由具体到宽泛 | 调整声明顺序 |
| 变型注解报错 | 参数位与返回值位用反 | 检查 in 与 out 位置 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
| 类型体操 | 无人能读,编译器变慢 | 显式类型或代码生成 |
| 无约束泛型 | 等于 unknown | 加 extends |
| 用条件类型做运行时分派 | 编译后消失 | 运行时 switch |
| 为每个函数写重载 | 维护两份签名 | 泛型加约束 |
| 递归类型不设终止 | 深度爆炸 | 深度计数参数 |
4.3 可观测信号
tsc 总耗时与增量耗时、类型实例化错误数、.d.ts 体积增长、编辑器补全延迟、单文件泛型参数个数。
4.4 安全 / 性能 / 一致性边界
- 性能边界:类型运算在编译期消耗 CPU 与内存,大型联合与深递归会拖慢 CI 与编辑器。
- 发布边界:库的
.d.ts一旦发布就属于公共 API,改名或收窄都是破坏性变更。 - 一致性边界:派生类型必须与源类型同源,手写副本迟早漂移。
- 安全边界:泛型不提供运行时校验,外部数据的形状仍要 schema 保证。