typescript

TypeScript 最佳实践

全面兼容 TypeScript 7 的指南，包含 8 个类别的 44 条规则，涵盖编译器配置、类型系统性能、异步代码、模块、安全性和基于测量的运行时优化。

适用场景

以下情况可参考这些指南：

• 为新项目或现有项目配置 tsconfig.json
• 编写复杂的类型定义或泛型
• 优化 async/await 模式和数据获取
• 组织模块并管理导入
• 审查代码的编译或运行时性能

按优先级划分的规则类别

优先级	类别	影响	前缀
1	类型系统性能	CRITICAL	type-
2	编译器配置	CRITICAL	tscfg-
3	异步模式	HIGH	async-
4	模块组织	HIGH	module-
5	类型安全模式	MEDIUM-HIGH	safety-
6	内存管理	MEDIUM	mem-
7	运行时优化	LOW-MEDIUM	runtime-
8	高级模式	LOW	advanced-

目录

1. 类型系统性能 — 严重
   • 1.1 为导出的函数添加显式返回类型 — 严重（加快声明生成）
   • 1.2 避免使用深度嵌套的泛型类型 — 严重（防止实例化成本呈指数级增长）
   • 1.3 避免使用大型联合类型 — 严重（避免二次方 O(n²) 比较成本）
   • 1.4 将条件类型提取为具名别名 — 严重（启用编译器缓存，避免重复求值）
   • 1.5 限制类型递归深度 — 严重（防止类型呈指数级扩展）
   • 1.6 优先使用接口而非类型交集 — 严重（加快类型解析）
   • 1.7 简化复杂的映射类型 — 严重（减少类型计算）
2. 编译器配置 — 严重
   • 2.1 正确配置 include 和 exclude — 严重（避免扫描数千个不必要的文件）
   • 2.2 启用增量编译 — 严重（加快重新构建）
   • 2.3 审慎选择 skipLibCheck — 严重（加快编译）
   • 2.4 启用 strictFunctionTypes 以确保函数赋值安全 — 严重（启用经过优化的变型检查）
   • 2.5 为单文件转译器使用 isolatedModules — 严重（配合打包工具加快转译）
   • 2.6 为大型代码库使用项目引用 — 严重（加快增量构建）
   • 2.7 审慎迁移 TypeScript 7 配置 — 严重
3. 异步模式 — 高
   • 3.1 为异步函数标注返回类型 — 高（避免运行时错误，改善类型推断）
   • 3.2 避免在循环中使用 await — 高（随迭代次数线性扩展）
   • 3.3 避免不必要的 async/await — 高（消除微任务队列开销）
   • 3.4 在需要值时再使用 await — 高（实现隐式并行化）
   • 3.5 对独立操作使用 Promise.all — 高（改善 I/O 密集型代码的性能）
4. 模块组织 — 高
   • 4.1 避免从桶文件导入 — 高（导入开销更大，打包体积更大）
   • 4.2 避免循环依赖 — 高（避免运行时 undefined 错误和编译缓慢）
   • 4.3 控制 @types 包的引入 — 高（避免类型冲突并减少内存使用）
   • 4.4 对大型模块使用动态导入 — 高（缩小初始打包体积）
   • 4.5 对类型使用仅类型导入 — 高（消除类型信息对应的运行时导入）
5. 类型安全模式 — 中高
   • 5.1 启用 strictNullChecks — 中高
   • 5.2 优先使用 unknown 而非 any — 中高
   • 5.3 使用断言函数进行验证 — 中高
   • 5.4 使用 const 断言表示字面量类型 — 中高
   • 5.5 对联合类型使用穷尽性检查 — 中高
   • 5.6 使用类型守卫进行运行时类型检查 — 中高
6. 内存管理 — 中
   • 6.1 避免闭包内存泄漏 — 中（避免长期存在的回调保留引用）
   • 6.2 避免全局状态不断累积 — 中（避免内存无限增长）
   • 6.3 清理事件监听器 — 中（避免内存无限增长）
   • 6.4 清除计时器和间隔定时器 — 中（避免回调被保留并重复执行）
   • 6.5 使用 WeakMap 存储对象元数据 — 中（避免内存泄漏，并支持自动清理）
7. 运行时优化 — 低中
   • 7.1 避免在热点循环中使用对象展开 — 低中
   • 7.2 在经过测量的热点路径中提升循环不变量计算 — 低中
   • 7.3 优先使用原生数组方法而非 Lodash — 低中
   • 7.4 简单迭代时使用 for-of — 低中
   • 7.5 使用现代字符串方法 — 低中
   • 7.6 使用 Set/Map 实现 O(1) 查找 — 低中
8. 高级模式 — 低
   • 8.1 使用品牌类型实现类型安全的 ID — 低（避免混用不兼容的 ID 类型）
   • 8.2 使用 satisfies 在类型验证时保留推断 — 低（避免属性访问错误，并实现可靠的自动补全）
   • 8.3 使用模板字面量类型表示字符串模式 — 低（在编译时避免字符串格式错误）

使用方法

首先在项目根目录中运行：

npx -y @pymodel/react-frontend-skills detect                   # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill typescript  # deprecated APIs → rule IDs

对于上述与任务匹配的每条规则，以及每个 scan 命中项，阅读 references/<rule-id>.md，了解其重要性以及错误代码与正确代码的对比。

参考资料

1. https://github.com/microsoft/TypeScript/wiki/Performance
2. https://www.typescriptlang.org/docs/handbook/
3. https://v8.dev/blog
4. https://nodejs.org/en/learn/diagnostics/memory