第12章：性能优化与最佳实践

项目中 TypeScript 的渐进式引入

1. 为什么需要渐进式引入？

在已有 JavaScript 项目中直接全面迁移到 TypeScript 可能存在以下挑战：

  • 代码库规模庞大，一次性迁移成本高
  • 团队成员对 TypeScript 熟悉程度不一
  • 第三方库可能缺乏完善类型定义

渐进式引入允许团队以较低风险逐步享受 TypeScript 的优势，包括：

  • 按模块或功能逐步迁移
  • 与现有 JavaScript 代码共存
  • 逐步培养团队类型化思维

2. 渐进式迁移策略

2.1 初始配置

  1. 安装基础依赖：
npm install typescript @types/node --save-dev
  1. 创建最小化 tsconfig.json：
{
  "compilerOptions": {
    "target": "ES6",
    "module": "commonjs",
    "allowJs": true,
    "checkJs": false,
    "outDir": "./dist",
    "strict": false
  },
  "include": ["src/**/*"]
}

2.2 分阶段实施

阶段目标关键配置
1. 混合模式允许.js和.ts共存allowJs: true
2. 基础类型检查对JS文件进行基础检查checkJs: true
3. 严格模式逐步启用严格检查分步开启strict系列选项

3. 具体实施步骤

3.1 从新代码开始

  1. 所有新文件使用 .ts 扩展名
  2. 为新模块添加完整类型定义
  3. 示例：
// 新模块采用完整TS写法
interface User {
  id: number;
  name: string;
}

export function createUser(user: User): void {
  // 实现逻辑
}

3.2 改造现有代码

  1. 重命名 .js 为 .ts（保留原始逻辑）
  2. 逐步添加类型注解：
// 改造前
function calculateTotal(price, quantity) {
  return price * quantity;
}

// 改造后
function calculateTotal(price: number, quantity: number): number {
  return price * quantity;
}
  1. 使用JSDoc辅助迁移（对暂不修改的JS文件）：
/**
 * @param {number} price
 * @param {number} quantity
 * @returns {number}
 */
function calculateTotal(price, quantity) {
  return price * quantity;
}

4. 处理第三方库

4.1 类型声明安装

npm install @types/react @types/lodash --save-dev

4.2 无类型库处理方案

  1. 创建 types/ 目录
  2. 添加自定义声明文件（如 custom.d.ts）：
declare module 'untyped-library' {
  const content: any;
  export default content;
}

5. 团队协作建议

5.1 代码审查重点

  • 新增代码必须包含完整类型
  • 修改文件时逐步添加类型
  • 禁止使用 any 作为最终方案

5.2 培训路线图

  1. 基础类型系统（2周）
  2. 接口与泛型（2周）
  3. 高级类型工具（4周）

6. 常见问题解决方案

6.1 类型错误阻塞开发

// 临时方案（需后续处理）
const data = someUntypedFunction() as unknown as MyType;

6.2 增量编译配置

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./buildcache"
  }
}

7. 迁移效果评估

建立类型覆盖率检查机制：

npx type-coverage

建议里程碑目标：

  • 阶段1：30% 类型覆盖率
  • 阶段2：70% 类型覆盖率
  • 阶段3：95%+ 类型覆盖率（禁用any）

最佳实践提示：每周设立"类型日"，集中处理遗留代码的类型问题，同时进行团队知识分享。

Last Updated::