TypeScript 模块系统深度解析
模块基础
模块是 TypeScript (以及现代 JavaScript) 中组织代码、实现复用和管理作用域的核心机制。自 ECMAScript 2015 (ES6) 起，JavaScript 引入了标准化的模块系统，TypeScript 在此基础上进行了扩展和支持。
- 作用域隔离：每个模块都拥有独立的作用域。模块内部定义的变量、函数、类等默认对外部不可见，必须通过
export关键字显式声明才能被外部引用。这有效避免了全局命名空间的污染。 - 导入与导出：模块间的通信通过
import和export关键字完成。export用于将模块内的声明暴露给外部，而import则用于引入其他模块导出的内容。这种显式的依赖管理使得代码结构清晰，可维护性高。 - 文件级别模块：在 TypeScript 中，任何包含顶级
import或export声明的文件都被自动识别为一个模块。这与 ES6 模块规范保持一致，并且也能与 CommonJS 等模块加载器良好兼容。 - 运行时加载器：在代码执行阶段，模块加载器负责解析模块间的依赖关系，查找并加载所需的模块。在 Node.js 环境中，CommonJS 是主流的加载器；在浏览器环境中，通常使用 Require.js、Webpack 等工具。
- 声明性依赖：TypeScript 的模块系统是声明性的。模块间的依赖关系通过
import和export语句在文件层面建立，而不是通过全局变量或函数调用来隐式关联。
导出声明与语句
导出声明
可以直接在变量、函数、类、接口或类型别名的声明前加上 export 关键字，将其导出。
// 导出单个函数
export function calculateSum(a: number, b: number): number {
return a + b;
}
// 导出类
export class UserProfile {
constructor(public name: string) {}
}
导出语句
export 语句允许批量导出多个声明，并且可以为导出的成员指定新的名称（重命名）。
// 定义需要导出的内容
function processData(data: any): void {
console.log("Processing:", data);
}
const MAX_ITEMS = 100;
// 使用 export 语句批量导出，并重命名
export {
processData as handleData,
MAX_ITEMS as maxAllowedItems
};
重新导出 (Re-exporting)
允许一个模块导入另一个模块的导出内容，并将其作为当前模块的导出。这常用于聚合或扩展模块功能。
// 假设有一个文件 './utils' 导出了 'formatDate' 函数
// export function formatDate(date: Date): string { ... }
// 在当前模块中重新导出 'formatDate'
export { formatDate } from './utils';
// 也可以重新导出并重命名
export { formatDate as formatCurrentDate } from './utils';
聚合重新导出 (Aggregating Re-exports)
使用 export * from 'module-name' 语法可以导入并重新导出指定模块的所有导出内容。
// 假设 './common' 模块导出了多个工具函数
// 将 './common' 中的所有导出全部重新导出
export * from './common';
导入模块内容
使用 import 关键字来引入其他模块的导出内容。
导入特定导出
使用花括号 {} 来按名称导入一个或多个特定的导出。
import { calculateSum, UserProfile } from './mathUtils';
const sumResult = calculateSum(10, 20);
const user = new UserProfile("Alice");
导入时可以对导出的名称进行重命名：
import { calculateSum as add } from './mathUtils';
const result = add(5, 5);
导入整个模块
将模块的所有导出作为一个对象导入。
import * as MathTools from './mathUtils';
const sum = MathTools.calculateSum(3, 7);
const newUser = new MathTools.UserProfile("Bob");
导入具有副作用的模块
某些模块可能不导出任何具体内容，而是执行一些全局操作（例如，加载 CSS、初始化配置）。导入这类模块只需使用 import 'module-path';。
// 导入 CSS 文件，可能触发样式加载
import './styles/main.css';
// 导入一个初始化模块
import './bootstrap';
默认导出 (Default Export)
默认导出为模块提供了一个主要的、唯一的导出项，简化了导入过程。
定义默认导出
使用 export default 关键字。
// utils.ts
export default class DataProcessor {
process(data: any) {
console.log("Processing data...", data);
}
}
// 也可以导出一个函数或值
// export default function greet(name: string) { ... }
// export default { name: "config" };
导入默认导出
在导入时，不需要使用花括号，直接指定一个变量名来接收默认导出。
// main.ts
import MyProcessor from './utils'; // MyProcessor 接收了 DataProcessor 类
const processor = new MyProcessor();
processor.process({ id: 1, value: "test" });
适用场景
- 当模块的主要目的是提供一个单一的核心功能（如一个类、一个函数或一个配置对象）时。
- 简化库的导入，用户可以直接 `import Library from 'library';`。
注意事项
- 一个模块只能有一个默认导出。
- 默认导出在导入时不需要花括号，这与命名导出有明显区别。
export = 和 import = require()
这是 TypeScript 提供的一种特定于 CommonJS 和 AMD 等旧模块系统的语法，用于兼容性处理。它允许将一个模块整体导出一个对象，或者将一个 CommonJS 风格的模块导入为一个变量。
示例
// calculator.ts - 使用 export = 导出整个模块
const add = (a: number, b: number) => a + b;
const subtract = (a: number, b: number) => a - b;
export = {
add,
subtract
};
// main.ts - 使用 import = require() 导入
import calc = require('./calculator');
console.log(calc.add(10, 5)); // 输出 15
console.log(calc.subtract(10, 5)); // 输出 5
区别与注意事项
- 兼容性：此语法主要为兼容旧的模块加载器（如 CommonJS、AMD）而设计，不适用于标准的 ES6 模块。
- 现代推荐：在现代 TypeScript 项目中，推荐使用标准的
export和import语法，它们能更好地与 ES6 模块以及 Node.js 的 CommonJS 环境协同工作。 - 与
export default的区别：export =导出的是一个模块对象，可以包含任意数量的成员；而export default只能导出一个单一的值。
模块代码生成目标
TypeScript 编译器（tsc）可以通过 --module 选项生成不同模块加载器兼容的代码，包括：
- ECMAScript Modules (ESM)：现代 JavaScript 标准，使用
import和export。 - CommonJS：Node.js 的标准模块系统，使用
require和module.exports。 - AMD (Asynchronous Module Definition)：常用于浏览器环境，支持异步加载。
- UMD (Universal Module Definition)：一种通用模式，尝试兼容 CommonJS, AMD 和全局变量。
- SystemJS：一种模块加载器，支持多种模块格式。
代码示例 (不同模块目标)
ECMAScript 模块 (ESM)
// myModule.ts
export const version = '1.0';
export function logMessage(msg: string) { console.log(msg); }
// main.ts
import { version, logMessage } from './myModule';
console.log(`Using module version: ${version}`);
logMessage('Module loaded.');
编译后 (--module esnext 或 es2015)，生成的 JavaScript 会使用 import 和 export 关键字。
CommonJS 模块
// myModule.js (CommonJS)
const version = '1.0';
function logMessage(msg) { console.log(msg); }
module.exports = { version, logMessage };
// main.js
const myModule = require('./myModule');
console.log(`Using module version: ${myModule.version}`);
myModule.logMessage('Module loaded.');
编译后 (--module commonjs)，TypeScript 会生成类似上述 CommonJS 格式的代码，使用 require 和 module.exports。
AMD 模块
// myModule.js (AMD)
define('myModule', [], function() {
const version = '1.0';
function logMessage(msg) { console.log(msg); }
return { version, logMessage };
});
// main.js
require(['myModule'], function(myModule) {
console.log(`Using module version: ${myModule.version}`);
myModule.logMessage('Module loaded.');
});
编译后 (--module amd)，会生成使用 define 和 require 的 AMD 格式代码。
UMD 模块
UMD 代码通常会包含一个自执行函数，内部根据全局环境中是否存在 define (AMD) 或 module.exports (CommonJS) 来决定如何暴露模块，否则作为全局变量挂载。
(function (root, factory) {
if (typeof define === 'function' && define.amd) {
define([], factory);
} else if (typeof exports === 'object') {
module.exports = factory();
} else {
root.MyLib = factory();
}
}(typeof self !== 'undefined' ? self : this, function () {
const version = '1.0';
function logMessage(msg) { console.log(msg); }
return { version, logMessage };
}));
编译后 (--module umd)，会生成 UMD 格式的代码。
模块结构组织最佳实践
- 扁平化导出，避免命名空间嵌套：模块本身已经提供了文件系统级别的组织。尽量将导出的内容直接放在模块的顶层，避免使用命名空间来进一步封装，这样可以简化用户导入时的写法。
- 优先使用
export default：如果一个模块的主要功能是一个类或一个函数，考虑使用export default。这使得导入更加简洁，如import MyClass from './MyClass'。 - 显式导出多个项：当需要导出多个独立功能时，直接使用命名导出（
export const ...,export function ...），并在导入时明确列出所需项。 - 合理利用文件结构：使用目录来组织相关的模块文件，形成清晰的层级结构，反映代码的组织逻辑。
- 聚合导出用于扩展：如果一个模块旨在扩展另一个模块的功能，可以使用
export * from '...'或export { ... } from '...'来聚合导出，而不是在模块内部重新实现。
