typescript-advanced-patterns

技能：typescript

范围

• 适用：TypeScript v5+ 高级类型系统功能、类型安全的 API、复杂领域模型、高级类型推断、编译时保证
• 不适用：TypeScript 基础语法、特定框架模式、运行时校验库（请单独使用 Zod）

前提

• TypeScript v5+
• 已启用严格模式（在 tsconfig.json 中设置 "strict": true）
• 目标：ES2020+ 或更高版本

原则

• 使用条件类型，根据条件选择类型
• 使用映射类型，系统地转换对象类型
• 使用类型守卫（value is Type）进行运行时检查和类型收窄
• 使用可辨识联合，构建支持穷尽性检查的类型安全状态机
• 使用品牌类型，避免基本类型混用
• 为确保类型安全，优先使用 unknown 而非 any
• 优先使用类型守卫，而非类型断言（as Type）
• 保持类型可组合且浅层（避免深层嵌套）
• 将不可变数据结构标记为 readonly

约束

必须

• 启用严格模式（在 tsconfig.json 中设置 "strict": true）
• 对未类型化的值使用 unknown，而非 any
• 尽可能使用类型守卫（value is Type），而非类型断言

应当

• 联合类型和工具类型使用 type，对象结构使用 interface
• 保持类型可组合且浅层
• 将不可变数据结构标记为 readonly
• 使用品牌类型，避免基本类型混用

避免

• 使用 any（使用带类型守卫的 unknown）
• 未经验证就使用类型断言
• 过度使用泛型（仅在类型确实会变化时使用）
• 深层类型嵌套（编译速度慢，难以调试）

关联

• 配合 zod 使用，可进行运行时校验并推断类型
• 与 nextjs 配合，为 API 路由提供类型安全
• 与 fastify 配合，为路由架构提供类型安全

模式

映射类型

系统地转换对象类型：

type Partial<T> = { [P in keyof T]?: T[P] }
type Readonly<T> = { readonly [P in keyof T]: T[P] }
type Pick<T, K extends keyof T> = { [P in K]: T[P] }

类型守卫

通过类型收窄进行运行时类型检查：

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

function isSuccess(result: Result): result is Success {
  return result.status === 'success'
}

品牌类型

创建名义类型以确保类型安全：

type UserId = string & { readonly __brand: 'UserId' }
type PostId = string & { readonly __brand: 'PostId' }

function createUserId(id: string): UserId {
  return id as UserId
}

可辨识联合

构建支持穷尽性检查的类型安全状态机：

type LoadingState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: string[] }
  | { status: 'error'; error: Error }

参考

• 条件类型 - 根据条件选择类型
• 高级泛型 - 泛型约束和推断模式
• 可辨识联合 - 类型安全的状态机

资源

• TypeScript 手册
• 类型挑战
• ts-toolbelt - 高级类型工具库