TypeScript在前端项目的渐进式采用策略

渐进式采用 TypeScript 在前端项目中的策略通常包括:

引入TypeScript

如果我们有一个简单的JavaScript模块utils.js，它包含一个函数用于计算两数之和：

 
// utils.js
export function add(a, b) {
  return a + b;
}

首先，我们将文件扩展名改为.ts，并开始逐步添加类型注解：

 
// utils.ts
export function add(a: number, b: number): number {
  return a + b;
}

设置tsconfig.json

在项目根目录下创建tsconfig.json来配置TypeScript编译器：

 
{
  // 指定编译的目标ECMAScript版本
  "target": "es6",
  
  // 指定模块系统
  "module": "esnext",
  
  // 输出目录，编译后的文件存放位置
  "outDir": "./dist",
  
  // 是否包含源码映射文件，方便调试
  "sourceMap": true,
  
  // 启用严格的类型检查选项
  "strict": true,
  
  // 允许从没有设置默认导出的模块中默认导入
  "esModuleInterop": true,
  
  // 忽略库的类型检查
  "skipLibCheck": true,
  
  // 确保文件名大小写一致
  "forceConsistentCasingInFileNames": true,
  
  // 包含哪些文件进行编译
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx" // 如果项目中使用了TypeScript的JSX
  ],
  
  // 排除哪些文件或目录不进行编译
  "exclude": [
    "node_modules",
    "**/*.spec.ts" // 排除测试文件
  ]
}

高级配置项

paths: 用于路径别名配置，方便模块导入时的路径管理。

 
  "paths": {
    "@components/*": ["src/components/*"]
  }

baseUrl: 设置项目的基础目录，与paths一起使用时，可以提供更简洁的导入路径。


  "baseUrl": "./src"

resolveJsonModule: 允许直接导入JSON文件。


  "resolveJsonModule": true

lib: 指定项目中使用的库文件集合，比如ECMAScript、DOM等。


  "lib": ["es6", "dom"]

jsx: 如果项目使用了JSX语法，需要设置此选项。


  "jsx": "react-jsx"

继承配置

如果你的项目结构比较复杂，可能需要在不同的目录下有不同的配置，可以使用extends属性来继承一个基础的tsconfig.json：

 
// 在子目录下的tsconfig.app.json
{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    // 在这里可以覆盖或添加特定于应用程序的编译选项
  },
  // 可以在这里添加或修改include和exclude
}

集成TypeScript到构建流程

集成TypeScript到构建流程通常涉及到调整构建工具（如Webpack、Rollup或Parcel）的配置。并在配置文件中添加TypeScript处理规则。


npm install --save-dev typescript ts-loader webpack webpack-cli

webpack.config.js配置文件

 
const path = require('path');
 
module.exports = {
  entry: './src/index.ts', // 你的入口文件，通常是index.ts
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx'], // 添加.ts和.tsx扩展名
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/, // 排除node_modules目录
      },
    ],
  },
  devtool: 'source-map', // 生成source map，便于开发时调试
};

在tsconfig.json中，确保已经配置了正确的outDir，以匹配Webpack的输出目录：

 
{
  // ...
  "outDir": "./dist",
  // ...
}

现在，你可以在命令行中运行以下命令来启动构建流程：

npx webpack

这将使用Webpack和ts-loader将TypeScript源代码编译为JavaScript，并输出到dist目录。

如果你使用的是npm scripts，可以在package.json中添加构建脚本：

 
{
  "scripts": {
    "build": "webpack"
  }
}

然后通过npm run build运行构建。

利用类型定义

如果项目中使用到了第三方库，确保安装对应的类型定义包，如@types/lodash。对于没有官方类型定义的库，可以尝试社区提供的定义或自己编写声明文件。

1.安装类型定义包：

大多数流行库都有对应的类型定义包，通常位于@types命名空间下。例如，如果你的项目中使用了lodash，可以运行以下命令安装其类型定义：


   npm install --save-dev @types/lodash

或者使用Yarn：


   yarn add --dev @types/lodash

2. 自动类型推断

安装完类型定义后，TypeScript编译器会自动识别并使用这些类型定义。你无需在代码中显式引入它们，只要在项目中正常引用库即可。

3. 自定义类型定义

如果你使用了一个没有官方类型定义的库，或者官方类型定义不够完整，你可以自己编写类型声明文件（.d.ts）。通常，这个文件应放在与库的JavaScript文件相同的位置，或者放在types或@types目录下。

例如，假设有一个名为customLib的库，其主文件为customLib.js，你可以创建一个customLib.d.ts文件来声明其类型：

 
   declare module 'customLib' {
     export function doSomething(data: string): void;
     export interface CustomInterface {
       property: number;
     }
   }

然后在你的代码中，TypeScript会识别并使用这些类型。

4. 社区类型定义

有时，社区会提供非官方的类型定义。你可以在DefinitelyTyped仓库（https://github.com/DefinitelyTyped/DefinitelyTyped）中查找，或者在GitHub上搜索@types/library-name。

5. 类型定义的局限性

虽然类型定义对提高代码质量很有帮助，但并非所有库都提供完整的类型定义，或者可能与库的实际行为不完全匹配。在这种情况下，你可能需要在代码中使用any类型或// @ts-ignore注释来跳过特定的类型检查。

IDE集成

确保你的IDE（如VSCode）安装了TypeScript插件，以便获得代码补全、类型检查等功能。

逐步迁移其他模块

随着时间推移，可以逐步将其他JavaScript模块转换为TypeScript。例如，假设有一个app.js，可以类似地转换为app.ts并添加类型注解。

将app.js重命名为app.ts。这一步标志着该模块正式进入TypeScript环境。
打开app.ts，开始逐步为变量、函数参数、返回值等添加类型注解。这有助于TypeScript编译器进行类型检查，减少潜在的类型错误。

 
  // JavaScript
  function fetchData(url) {
    return fetch(url).then(response => response.json());
  }
 
  // 转换为TypeScript
  async function fetchData(url: string): Promise<any> {
    const response = await fetch(url);
    return response.json();
  }

对于复杂的数据结构，考虑使用接口（interface）或类型别名（type alias）来定义类型，提高代码的可读性和可维护性。

 
  interface User {
    id: number;
    name: string;
    email: string;
  }
 
  function getUser(): User {
    // ...
  }

强化类型检查

在团队适应TypeScript后，可以在tsconfig.json中逐步开启更严格的类型检查选项，如strictNullChecks。

	// utils.ts
	export function add(a: number, b: number): number {
	return a + b;
	}

	{
	// 指定编译的目标ECMAScript版本
	"target": "es6",

	// 指定模块系统
	"module": "esnext",

	// 输出目录，编译后的文件存放位置
	"outDir": "./dist",

	// 是否包含源码映射文件，方便调试
	"sourceMap": true,

	// 启用严格的类型检查选项
	"strict": true,

	// 允许从没有设置默认导出的模块中默认导入
	"esModuleInterop": true,

	// 忽略库的类型检查
	"skipLibCheck": true,

	// 确保文件名大小写一致
	"forceConsistentCasingInFileNames": true,

	// 包含哪些文件进行编译
	"include": [
	"src/*/.ts",
	"src/*/.tsx" // 如果项目中使用了TypeScript的JSX
	],

	// 排除哪些文件或目录不进行编译
	"exclude": [
	"node_modules",
	"*/.spec.ts" // 排除测试文件
	]
	}

	// 在子目录下的tsconfig.app.json
	{
	"extends": "../tsconfig.json",
	"compilerOptions": {
	// 在这里可以覆盖或添加特定于应用程序的编译选项
	},
	// 可以在这里添加或修改include和exclude
	}

	const path = require('path');

	module.exports = {
	entry: './src/index.ts', // 你的入口文件，通常是index.ts
	output: {
	filename: 'bundle.js',
	path: path.resolve(__dirname, 'dist'),
	},
	resolve: {
	extensions: ['.ts', '.tsx', '.js', '.jsx'], // 添加.ts和.tsx扩展名
	},
	module: {
	rules: [
	{
	test: /\.tsx?$/,
	use: 'ts-loader',
	exclude: /node_modules/, // 排除node_modules目录
	},
	],
	},
	devtool: 'source-map', // 生成source map，便于开发时调试
	};

	declare module 'customLib' {
	export function doSomething(data: string): void;
	export interface CustomInterface {
	property: number;
	}
	}

	// JavaScript
	function fetchData(url) {
	return fetch(url).then(response => response.json());
	}

	// 转换为TypeScript
	async function fetchData(url: string): Promise<any> {
	const response = await fetch(url);
	return response.json();
	}

	interface User {
	id: number;
	name: string;
	email: string;
	}

	function getUser(): User {
	// ...
	}