typescript-v6

技能：typescript

范围

• 适用范围：TypeScript 6.0+ 类型系统功能、类型安全 API、复杂领域模型、类型推断、编译时保证
• 不涵盖：基础语法、特定框架模式、运行时验证（请另行使用 Zod）

假设

• 主要版本以文件夹中的 package.json typescript 为准（本仓库：@typescript/typescript6 ^6），而非 npm view typescript（可能已是 7）
• 6.0 是最后一个基于 JavaScript 的编译器；7.0 将使用原生实现（Go）。@typescript/native 可能与 tsc 并存，但不属于本技能的主要版本
• 严格模式（"strict": true）
• 目标版本为 ES2020+（6.0 的默认值趋向于 esnext / es2025）
• 6.0 中弃用的选项可通过 "ignoreDeprecations": "6.0" 忽略，直到 7.0 移除这些选项。建议修复弃用项：https://devblogs.microsoft.com/typescript/announcing-typescript-6-0/

原则

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

约束

必须

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

应当

• 联合类型和工具类型使用 type，对象结构使用 interface
• 保持类型可组合且浅层
• 将不可变数据结构标记为 readonly
• 使用品牌类型，防止原始类型混用
• 在采用 TypeScript 7 原生实现之前处理 6.0 的弃用项

避免

• 使用 any（请使用 unknown 和类型守卫）
• 未经验证就使用类型断言
• 过度使用泛型（仅在类型确实会变化时使用）
• 深层类型嵌套（编译缓慢且难以调试）
• 导入断言（assert { type: ... }）；请使用 with 导入属性

交互

• 与 zod 搭配，进行支持类型推断的运行时验证
• 与 next 互补，用于构建类型安全的 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 6.0 发布公告
• TypeScript 手册
• 类型挑战