typescript-patterns

TypeScript 模式

概述

利用类型系统防止运行时错误的高级 TypeScript 模式。重点介绍严格模式 TypeScript 中的类型推断、类型收窄和编译时验证模式。不适合初学者。

适用场景： 构建类型安全的 API、复杂数据转换、编写库、通过类型防止运行时错误、使用严格模式标志。

不适用场景： 学习 TypeScript 基础知识（原始类型、接口、类）、JavaScript 迁移到 TypeScript 的指南、工具配置或构建配置。

快速参考

模式	API	要点
工具类型	Pick<T, K>, Omit<T, K>	提取或排除属性
Partial/Required	Partial<T>, Required<T>	将属性设为可选或必需
Record 类型	Record<K, V>	键已知的对象
Awaited 类型	Awaited<T>	解包 Promise 返回类型
ReturnType/Parameters	ReturnType<F>, Parameters<F>	提取函数类型
泛型约束	<T extends Type>	约束泛型参数
类型推断	type Inferred = typeof value	让 TypeScript 根据值进行推断
类型守卫	typeof, instanceof, in	在运行时收窄类型
自定义类型守卫	(x): x is Type	用户定义的类型收窄函数
推断的谓词	(x) => x !== null	自动推断类型谓词的过滤器
可辨识联合	带有字面量 type 属性的联合	穷尽式模式匹配
条件类型	T extends U ? X : Y	类型级条件表达式
映射类型	{ [K in keyof T]: T[K] }	转换所有属性
模板字面量	`${A}-${B}`	操作字符串字面量类型
const 断言	as const	尽可能收窄字面量类型
satisfies 运算符	value satisfies Type	执行类型检查，但不拓宽类型
NoInfer 工具类型	NoInfer<T>	阻止从某个位置进行推断
const 类型参数	<const T extends Type>	无需 as const 即可进行收窄推断
内联类型导入	import { type User }	显式导入类型
模块增强	declare module 'lib' { ... }	扩展第三方类型
断言函数	function assert(x): asserts x is T	类型守卫失败时抛出错误

常见错误

错误	正确做法
无充分理由地使用 any	使用 unknown，并通过类型守卫缩小类型范围
到处手动进行类型断言	让类型推断发挥作用，并为函数返回值标注类型
类型缩小前进行解构	保留对象完整，以便使用可辨识联合
未检查 undefined 就访问索引	启用 noUncheckedIndexedAccess
使用 as Type 转换不安全的值	使用 satisfies Type 保留更精确的类型
在泛型中内联对象	提取为 const 或类型别名
在约束中省略 extends	尽可能始终约束泛型
使用 Parameters<typeof fn>[0]	直接在函数中为参数标注类型
未处理联合类型的穷尽性	在 switch/if-else 中使用 never 检查
使用 value as const satisfies Type	使用 satisfies Type，必要时再使用 as const

委派

• 模式发现：使用 Explore Agent 查找代码库中的现有模式
• 类型错误调试：使用 Task Agent 处理多步骤类型解析
• 代码审查：委派给 code-reviewer 技能进行类型安全审查

参考资料

• 类型工具（Pick、Omit、Partial、Required、Record、Extract、Exclude、ReturnType、Parameters、Awaited）
• 泛型（约束、推断、默认参数、变型）
• 类型守卫与类型缩小（typeof、instanceof、in、自定义守卫、断言函数）
• 可辨识联合（穷尽性检查、never 类型、带标签的联合）
• 条件类型（分布式条件类型、infer 关键字、类型级逻辑）
• 映射类型（键重映射、模板字面量、修饰符）
• 严格模式模式（noUncheckedIndexedAccess、exactOptionalPropertyTypes、const 断言、satisfies）
• 模块模式（内联类型导入、声明文件、模块扩充、环境类型）
• 现代惯用写法（eslint-plugin-unicorn 模式、现代数组/字符串/DOM API、ES 模块）