typescript

TypeScript 最佳实践

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

适用场景

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

• 为新项目或现有项目配置 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 限制类型递归深度 — HIGH（在适用情况下防止类型扩展呈指数级增长）
   • 1.6 优先使用接口而非类型交叉 — CRITICAL（类型解析速度提升 2-5 倍）
   • 1.7 简化复杂的映射类型 — HIGH（在适用情况下将类型计算量减少 50-80%）
2. 编译器配置 — CRITICAL
   • 2.1 正确配置 Include 和 Exclude — CRITICAL（避免扫描数千个不必要的文件）
   • 2.2 启用增量编译 — CRITICAL（重新构建速度提升 50-90%）
   • 2.3 启用 isolatedDeclarations 以并行生成声明 — CRITICAL（无需类型检查器即可并行生成 .d.ts）
   • 2.4 启用 skipLibCheck 以加快构建 — CRITICAL（编译速度提升 20-40%）
   • 2.5 启用 strictFunctionTypes 以加快变异性检查 — CRITICAL（支持优化变异性检查）
   • 2.6 使用 erasableSyntaxOnly 配合 Node.js 原生 TypeScript — HIGH（避免 100% 的 Node.js 类型剥离运行时错误）
   • 2.7 使用 isolatedModules 进行单文件转译 — CRITICAL（配合打包工具时，转译速度提升 80-90%）
   • 2.8 在大型代码库中使用项目引用 — CRITICAL（增量构建速度提升 60-80%）
3. 异步模式 — HIGH
   • 3.1 为异步函数标注返回类型 — HIGH（防止运行时错误，改善类型推断）
   • 3.2 避免在循环中使用 await — HIGH（N 次迭代可快 N 倍，10 个用户时性能提升 10 倍）
   • 3.3 避免不必要的 async/await — HIGH（消除简单的 Promise 包装器，改善堆栈跟踪）
   • 3.4 延迟 await，直到需要该值时再使用 — HIGH（支持隐式并行化）
   • 3.5 对独立操作使用 Promise.all — HIGH（I/O 密集型代码的性能提升 2-10 倍）
4. 模块组织 — HIGH
   • 4.1 避免从 Barrel 文件导入 — 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 启用 noUncheckedIndexedAccess — MEDIUM-HIGH（在编译时防止 100% 的未检查索引访问错误）
   • 5.2 启用 strictNullChecks — MEDIUM-HIGH（防止 null/undefined 运行时错误）
   • 5.3 优先使用 unknown 而非 any — MEDIUM-HIGH（强制缩窄类型，防止运行时错误）
   • 5.4 使用断言函数进行验证 — MEDIUM-HIGH（将验证样板代码减少 50-70%）
   • 5.5 使用 const 断言保留字面量类型 — MEDIUM-HIGH（保留字面量类型，支持更好的类型推断）
   • 5.6 对联合类型使用穷尽性检查 — MEDIUM-HIGH（在编译时防止 100% 的遗漏分支错误）
   • 5.7 使用类型守卫进行运行时类型检查 — 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