typescript-advanced-patterns

TypeScript 高级模式

专家级指南：利用 TypeScript 的高级类型系统功能，构建健壮、类型安全的应用，实现复杂的类型推断、编译时保证和易于维护的领域模型。

何时使用此技能

• 构建具有严格契约和验证的类型安全 API
• 实现由编译时强制执行的复杂领域模型
• 创建具有复杂类型推断能力的可复用库
• 通过类型系统强制执行业务规则
• 构建类型安全的状态机和构建器
• 开发需要高级类型的框架集成
• 实现具有类型级保证的运行时验证

核心概念

TypeScript 的类型系统通过以下方式实现编译时安全：

1. 条件类型：根据条件选择类型（类型级 if/else）
2. 映射类型：系统性地转换对象类型（Partial、Readonly、Pick、Omit）
3. 模板字面量类型：在编译时处理字符串
4. 类型守卫：通过运行时检查缩小类型范围（value is Type）
5. 可辨识联合：支持穷尽性检查的类型安全状态机
6. 品牌类型：用于防止原始类型混用的名义类型
7. 构建器模式：通过逐步施加类型约束实现类型安全的流式 API
8. 高级泛型：约束、推断和高阶类型模式
9. 工具类型：深层转换与组合
10. 类型推断：常量断言和上下文类型

快速参考

按需加载详细参考资料：

主题	参考文件
条件类型	skills/typescript-advanced-patterns/references/conditional-types.md
映射类型	skills/typescript-advanced-patterns/references/mapped-types.md
模板字面量类型	skills/typescript-advanced-patterns/references/template-literal-types.md
类型守卫	skills/typescript-advanced-patterns/references/type-guards.md
可辨识联合	skills/typescript-advanced-patterns/references/discriminated-unions.md
品牌类型	skills/typescript-advanced-patterns/references/branded-types.md
构建器模式	skills/typescript-advanced-patterns/references/builder-pattern.md
高级泛型	skills/typescript-advanced-patterns/references/advanced-generics.md
工具类型	skills/typescript-advanced-patterns/references/utility-types.md
类型推断	skills/typescript-advanced-patterns/references/type-inference.md
装饰器	skills/typescript-advanced-patterns/references/decorators.md
性能最佳实践	skills/typescript-advanced-patterns/references/performance-best-practices.md
常见陷阱	skills/typescript-advanced-patterns/references/common-pitfalls.md
类型测试	skills/typescript-advanced-patterns/references/testing-types.md

实现工作流

1. 确定模式需求

• 分析类型安全要求
• 确定运行时约束与编译时约束
• 从快速参考中选择合适的模式

2. 加载参考资料

• 阅读相应模式的参考文件
• 查看示例和使用场景
• 了解权衡取舍

3. 实现模式

• 从简单方案开始，按需增加复杂度
• 使用严格模式（在 tsconfig.json 中设置 "strict": true）
• 使用类型断言进行测试

4. 验证

• 确保类型错误能在编译时被捕获
• 验证运行时行为与类型相符
• 检查性能（避免类型过度复杂）

5. 编写文档

• 为公共 API 添加 JSDoc 注释
• 记录类型约束和假设
• 提供用法示例

应避免的常见错误

1. 使用 any 而非 unknown：会失去所有类型安全性

   • 使用 unknown 和类型守卫来替代

2. 未经验证就进行类型断言：可能导致不安全的运行时行为

   • 优先使用类型守卫（value is Type），而非 as Type

3. 过度使用泛型：会带来不必要的复杂性

   • 仅在类型确实会变化时使用泛型

4. 类型嵌套过深：编译速度慢，难以调试

   • 保持类型可组合且层次浅

5. 忘记使用 readonly：可能导致意外修改

   • 将不可变数据结构标记为 readonly

6. 未启用严格模式：缺少空值检查，且可能出现类型错误

   • 始终在 tsconfig.json 中使用 "strict": true

7. 错误地混用类型和接口：语义容易混淆

   • 联合类型和工具类型使用 type，对象结构使用 interface

快速模式

类型安全的 ID

type UserId = string & { readonly __brand: 'UserId' };
function createUserId(id: string): UserId { return id as UserId; }

可辨识联合

type State =
  | { status: 'loading' }
  | { status: 'success'; data: string }
  | { status: 'error'; error: Error };

映射类型转换

type Readonly<T> = { readonly [P in keyof T]: T[P] };
type Partial<T> = { [P in keyof T]?: T[P] };

类型守卫

function isString(value: unknown): value is string {
  return typeof value === 'string';
}

资源

• TypeScript 手册：https://www.typescriptlang.org/docs/handbook/
• Type Challenges：https://github.com/type-challenges/type-challenges
• ts-toolbelt：高级类型工具库
• zod：借助 TypeScript 推断进行运行时验证
• tsd：测试 TypeScript 类型定义