typescript

TypeScript 最佳实践

TypeScript 应用的全面性能优化指南。包含 8 个类别中的 42 条规则，并根据影响优先级排序，以指导自动重构和代码生成。

适用场景

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

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

按优先级划分的规则类别

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

目录

1. 类型系统性能 — CRITICAL
   • 1.1 为导出的函数添加显式返回类型 — CRITICAL（声明生成速度提高 30-50%）
   • 1.2 避免使用深层嵌套的泛型类型 — CRITICAL（防止实例化开销呈指数级增长）
   • 1.3 避免使用大型联合类型 — CRITICAL（避免平方级 O(n²) 比较开销）
   • 1.4 将条件类型提取为命名别名 — CRITICAL（启用编译器缓存，防止重复求值）
   • 1.5 限制类型递归深度 — CRITICAL（防止类型展开呈指数级增长）
   • 1.6 优先使用接口，而非类型交叉 — CRITICAL（类型解析速度提高 2-5 倍）
   • 1.7 简化复杂的映射类型 — CRITICAL（减少 50-80% 的类型计算）
2. 编译器配置 — CRITICAL
   • 2.1 正确配置 Include 和 Exclude — CRITICAL（避免扫描数千个不必要的文件）
   • 2.2 启用增量编译 — CRITICAL（重建速度提高 50-90%）
   • 2.3 启用 skipLibCheck 加快构建 — CRITICAL（编译速度提高 20-40%）
   • 2.4 启用 strictFunctionTypes 加快变体检查 — CRITICAL（启用优化的变体检查）
   • 2.5 使用 isolatedModules 进行单文件转译 — CRITICAL（使用打包器时，转译速度提高 80-90%）
   • 2.6 在大型代码库中使用项目引用 — CRITICAL（增量构建速度提高 60-80%）
3. 异步模式 — HIGH
   • 3.1 为异步函数标注返回类型 — HIGH（防止运行时错误，改善类型推断）
   • 3.2 避免在循环中使用 await — HIGH（N 次迭代时速度提高 N 倍；10 个用户时提升 10 倍）
   • 3.3 避免不必要的 async/await — HIGH（消除微任务队列开销）
   • 3.4 延迟 await，直到需要该值时再执行 — HIGH（支持隐式并行化）
   • 3.5 对相互独立的操作使用 Promise.all — HIGH（I/O 密集型代码性能提升 2-10 倍）
4. 模块组织 — HIGH
   • 4.1 避免从桶文件导入 — HIGH（导入耗时 200-800ms，打包体积增大 30-50%）
   • 4.2 避免循环依赖 — HIGH（防止运行时出现 undefined 错误及编译变慢）
   • 4.3 控制 @types 包的引入 — HIGH（防止类型冲突并减少内存使用）
   • 4.4 对大型模块使用动态导入 — HIGH（初始打包体积减少 30-70%）
   • 4.5 对类型使用仅类型导入 — HIGH（消除类型信息对应的运行时导入）
5. 类型安全模式 — MEDIUM-HIGH
   • 5.1 启用 strictNullChecks — MEDIUM-HIGH（防止 null/undefined 导致的运行时错误）
   • 5.2 优先使用 unknown，而非 any — MEDIUM-HIGH（强制收窄类型，防止运行时错误）
   • 5.3 使用断言函数进行验证 — MEDIUM-HIGH（减少 50-70% 的验证样板代码）
   • 5.4 对字面量类型使用 const 断言 — MEDIUM-HIGH（保留字面量类型，支持更好的类型推断）
   • 5.5 对联合类型进行穷尽检查 — MEDIUM-HIGH（在编译时防止 100% 的遗漏分支错误）
   • 5.6 使用类型守卫进行运行时类型检查 — MEDIUM-HIGH（消除类型断言，在边界处捕获错误）
6. 内存管理 — MEDIUM
   • 6.1 避免闭包内存泄漏 — MEDIUM（防止长期存在的回调保留引用）
   • 6.2 避免全局状态累积 — MEDIUM（防止内存无限增长）
   • 6.3 清理事件监听器 — MEDIUM（防止内存无限增长）
   • 6.4 清除定时器和间隔计时器 — MEDIUM（防止回调被保留并重复执行）
   • 6.5 使用 WeakMap 存储对象元数据 — MEDIUM（防止内存泄漏，支持自动清理）
7. 运行时优化 — LOW-MEDIUM
   • 7.1 避免在热点循环中使用对象展开 — LOW-MEDIUM（对象分配次数减少 N 倍）
   • 7.2 在循环中缓存属性访问 — LOW-MEDIUM（属性查找次数减少 N 倍）
   • 7.3 优先使用原生数组方法，而非 Lodash — LOW-MEDIUM（消除库开销，支持摇树优化）
   • 7.4 简单迭代时使用 for-of — LOW-MEDIUM（迭代样板代码减少 30-50%）
   • 7.5 使用现代字符串方法 — LOW-MEDIUM（处理简单模式时，速度比正则表达式快 2-5 倍）
   • 7.6 使用 Set/Map 实现 O(1) 查找 — LOW-MEDIUM（每次查找的复杂度从 O(n) 降至 O(1)）
8. 高级模式 — LOW
   • 8.1 使用品牌类型确保 ID 类型安全 — LOW（防止混用不兼容的 ID 类型）
   • 8.2 使用 satisfies 验证类型并保留类型推断 — LOW（防止属性访问错误，实现 100% 准确的自动补全）
   • 8.3 使用模板字面量类型定义字符串模式 — LOW（在编译时防止 100% 的字符串格式错误）

References

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