TypeScript 模块

在 TypeScript 中，模块（Module）是一种组织代码的方式，它可以将相关的代码分组到一个文件中，并通过 import 和 export 关键字来管理模块之间的依赖关系。本文将详细介绍 TypeScript 中的模块。

1. 模块的基本概念

什么是模块？

模块是一个独立的文件，它包含相关的代码，并通过 export 关键字暴露其公共 API，通过 import 关键字导入其他模块的 API。每个模块都有自己的作用域，模块内部的变量、函数、类等默认是私有的，只有通过 export 导出后才能被其他模块访问。

为什么使用模块？

• 代码组织：模块可以将相关的代码分组到一个文件中，提高代码的可读性和可维护性。
• 依赖管理：模块可以明确地声明其依赖关系，使代码更加模块化。
• 避免命名冲突：模块有自己的作用域，避免了全局命名冲突。
• 代码复用：模块可以被多个其他模块导入和使用，提高代码的复用性。

2. 模块的导出

基本导出

使用 export 关键字导出模块的公共 API。

// 导出变量
export const PI = 3.14;

// 导出函数
export function calculateArea(radius: number): number {
  return PI * radius * radius;
}

// 导出类
export class Circle {
  constructor(private radius: number) {}

  getArea(): number {
    return calculateArea(this.radius);
  }
}

// 导出接口
export interface Shape {
  getArea(): number;
}

导出语句

可以使用 export 语句导出多个成员。

const PI = 3.14;

function calculateArea(radius: number): number {
  return PI * radius * radius;
}

class Circle {
  constructor(private radius: number) {}

  getArea(): number {
    return calculateArea(this.radius);
  }
}

interface Shape {
  getArea(): number;
}

// 导出语句
export { PI, calculateArea, Circle, Shape };

重命名导出

可以使用 as 关键字重命名导出的成员。

const PI = 3.14;

function calculateArea(radius: number): number {
  return PI * radius * radius;
}

// 重命名导出
export { PI as MathPI, calculateArea as calcArea };

默认导出

每个模块可以有一个默认导出，使用 export default 关键字。

// 默认导出函数
export default function add(a: number, b: number): number {
  return a + b;
}

// 默认导出类
export default class Calculator {
  add(a: number, b: number): number {
    return a + b;
  }

  subtract(a: number, b: number): number {
    return a - b;
  }
}

// 默认导出对象
export default {
  add: (a: number, b: number) => a + b,
  subtract: (a: number, b: number) => a - b
};

3. 模块的导入

基本导入

使用 import 关键字导入其他模块的 API。

// 导入所有导出的成员
import * as MathUtils from './math';

console.log(MathUtils.PI); // 输出：3.14
console.log(MathUtils.calculateArea(5)); // 输出：78.5

const circle = new MathUtils.Circle(10);
console.log(circle.getArea()); // 输出：314

// 导入特定的成员
import { PI, calculateArea, Circle } from './math';

console.log(PI); // 输出：3.14
console.log(calculateArea(5)); // 输出：78.5

const circle = new Circle(10);
console.log(circle.getArea()); // 输出：314

重命名导入

可以使用 as 关键字重命名导入的成员。

// 重命名导入
import { PI as MathPI, calculateArea as calcArea } from './math';

console.log(MathPI); // 输出：3.14
console.log(calcArea(5)); // 输出：78.5

导入默认导出

导入默认导出时，不需要使用花括号。

// 导入默认导出
import add from './math';
console.log(add(1, 2)); // 输出：3

// 同时导入默认导出和命名导出
import Calculator, { PI } from './math';

const calculator = new Calculator();
console.log(calculator.add(1, 2)); // 输出：3
console.log(PI); // 输出：3.14

4. 模块的路径

相对路径

使用相对路径导入同一目录或子目录中的模块。

// 导入同一目录中的模块
import { add } from './math';

// 导入子目录中的模块
import { User } from './models/user';

// 导入父目录中的模块
import { utils } from '../utils';

绝对路径

使用绝对路径导入模块，通常用于导入第三方库或项目的核心模块。

// 导入第三方库
import * as React from 'react';
import * as lodash from 'lodash';

// 导入项目的核心模块（需要配置 tsconfig.json）
import { User } from '@/models/user';
import { utils } from '@/utils';

5. 模块的配置

tsconfig.json 配置

在 tsconfig.json 文件中配置模块相关的选项。

{
  "compilerOptions": {
    "module": "commonjs", // 模块系统（commonjs, es2015, esnext 等）
    "moduleResolution": "node", // 模块解析策略
    "baseUrl": ".", // 基础路径
    "paths": { // 路径映射
      "@/*": ["src/*"]
    }
  }
}

package.json 配置

在 package.json 文件中配置模块相关的选项。

{
  "type": "module", // 使用 ES 模块系统
  "main": "dist/index.js", // 主入口文件
  "module": "dist/index.esm.js", // ES 模块入口文件
  "types": "dist/index.d.ts" // 类型声明文件
}

6. 模块与命名空间的区别

特性	模块	命名空间
定义方式	使用 import 和 export 关键字	使用 namespace 关键字
文件结构	每个文件是一个独立的模块	可以跨多个文件，自动合并
依赖管理	使用 import 语句	使用 /// <reference path="..." />
作用域	模块作用域	全局作用域
编译方式	通常编译为多个文件	可以编译为单个文件
现代性	现代标准，推荐使用	传统方式，逐渐被模块取代

7. 模块的最佳实践

1. 单一职责原则

每个模块应该只负责一个功能，保持模块的简洁和专注。

2. 清晰的命名

模块的文件名应该清晰、有意义，反映其包含的代码的功能。

3. 合理的导出

只导出需要在其他模块中使用的成员，保持模块的封装性。

4. 明确的依赖关系

模块应该明确地声明其依赖关系，避免隐式依赖。

5. 使用 ES 模块

对于现代 TypeScript 项目，推荐使用 ES 模块系统，因为它是标准的模块系统，具有更好的工具支持。

6. 合理使用路径映射

使用路径映射可以简化模块的导入路径，提高代码的可读性。

8. 常见错误

1. 循环依赖

避免模块之间的循环依赖，这会导致编译错误或运行时错误。

// 文件 A.ts
import { B } from './B';
export class A {
  constructor(private b: B) {}
}

// 文件 B.ts
import { A } from './A'; // 循环依赖
export class B {
  constructor(private a: A) {}
}

2. 导入路径错误

确保导入路径正确，否则会导致编译错误。

// 错误：路径错误
// import { add } from './maths'; // 应该是 './math'

// 正确：路径正确
import { add } from './math';

3. 导出和导入不匹配

确保导出和导入的成员名称匹配，否则会导致编译错误。

// 文件 math.ts
export const PI = 3.14;

// 文件 main.ts
// 错误：导入的成员不存在
// import { pi } from './math'; // 应该是 PI

// 正确：导入的成员存在
import { PI } from './math';

4. 默认导出和命名导出混淆

默认导出和命名导出的导入方式不同，不要混淆。

// 文件 math.ts
export default function add(a: number, b: number): number {
  return a + b;
}

// 文件 main.ts
// 错误：默认导出不需要花括号
// import { add } from './math';

// 正确：默认导出的导入方式
import add from './math';

9. 实际应用场景

1. 组织业务逻辑

使用模块来组织业务逻辑，将相关的代码分组到不同的模块中。

// 用户模块：src/modules/user.ts
export interface User {
  id: number;
  name: string;
  email: string;
}

export function getUserById(id: number): User {
  // 实现
}

export function createUser(user: Omit<User, 'id'>): User {
  // 实现
}

// 产品模块：src/modules/product.ts
export interface Product {
  id: number;
  name: string;
  price: number;
}

export function getProductById(id: number): Product {
  // 实现
}

export function createProduct(product: Omit<Product, 'id'>): Product {
  // 实现
}

2. 组织工具函数

使用模块来组织工具函数，将相关的工具函数分组到不同的模块中。

// 字符串工具：src/utils/string.ts
export function capitalize(str: string): string {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

export function truncate(str: string, length: number): string {
  return str.length > length ? str.slice(0, length) + '...' : str;
}

// 数字工具：src/utils/number.ts
export function formatNumber(num: number): string {
  return num.toLocaleString();
}

export function clamp(num: number, min: number, max: number): number {
  return Math.min(Math.max(num, min), max);
}

3. 组织类型定义

使用模块来组织类型定义，将相关的类型定义分组到不同的模块中。

// 核心类型：src/types/core.ts
export interface User {
  id: number;
  name: string;
  email: string;
}

export interface Product {
  id: number;
  name: string;
  price: number;
}

// API 类型：src/types/api.ts
export interface ApiResponse<T> {
  success: boolean;
  data: T;
  message?: string;
}

export interface PaginationParams {
  page: number;
  pageSize: number;
}

4. 组织组件

在前端框架（如 React、Vue）中，使用模块来组织组件。

// 按钮组件：src/components/Button.tsx
import React from 'react';

interface ButtonProps {
  text: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary' | 'danger';
}

export const Button: React.FC<ButtonProps> = ({
  text,
  onClick,
  variant = 'primary'
}) => {
  return (
    <button 
      className={`button button-${variant}`}
      onClick={onClick}
    >
      {text}
    </button>
  );
};

// 输入框组件：src/components/Input.tsx
import React from 'react';

interface InputProps {
  value: string;
  onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
  placeholder?: string;
  type?: string;
}

export const Input: React.FC<InputProps> = ({
  value,
  onChange,
  placeholder = '',
  type = 'text'
}) => {
  return (
    <input
      type={type}
      value={value}
      onChange={onChange}
      placeholder={placeholder}
      className="input"
    />
  );
};

总结

TypeScript 中的模块是一种组织代码的方式，它可以将相关的代码分组到一个文件中，并通过 import 和 export 关键字来管理模块之间的依赖关系。本文介绍了 TypeScript 模块的以下内容：

• 模块的基本概念：什么是模块，为什么使用模块
• 模块的导出：基本导出，导出语句，重命名导出，默认导出
• 模块的导入：基本导入，重命名导入，导入默认导出
• 模块的路径：相对路径，绝对路径
• 模块的配置：tsconfig.json 配置，package.json 配置
• 模块与命名空间的区别：对比模块和命名空间的特性
• 模块的最佳实践：单一职责原则，清晰的命名，合理的导出，明确的依赖关系，使用 ES 模块，合理使用路径映射
• 常见错误：循环依赖，导入路径错误，导出和导入不匹配，默认导出和命名导出混淆
• 实际应用场景：组织业务逻辑，组织工具函数，组织类型定义，组织组件

通过合理使用模块，你可以在 TypeScript 中更好地组织代码，提高代码的可读性、可维护性和可重用性。