TypeScript系列06-模块系统与命名空间

1. ES 模块与 CommonJS 互操作性

1.1 模块解析策略

TypeScript 提供多种模块解析策略，每种策略针对不同的运行环境和开发场景优化：

// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "node16", // 或 "classic", "node", "nodeNext", "bundler"
    // 其他配置...
  }
}

• Classic: TypeScript 原始的解析策略，主要用于向后兼容
• Node: 模拟 Node.js 的模块解析逻辑（CommonJS）
• Node16/NodeNext: 支持 Node.js 16+ 中的 ECMAScript 模块，处理 dual packages
• Bundler: 针对 Webpack/Vite 等打包工具环境优化

解析策略的选择直接影响导入路径的解析方式和模块加载行为：

// 在不同解析策略下，这个导入语句的解析过程会有差异
import { Component } from './components';

1.2 类型导入与值导入

TypeScript 区分类型级别导入和值级别导入，这对优化构建输出和理解互操作性至关重要：

// 值导入 - 生成 JavaScript 代码
import { useState } from 'react';

// 类型导入 - 编译后会被擦除
import type { ReactNode } from 'react';

// 混合导入 - 只导入类型，不导入值
import { type Props, Component } from './component';

使用类型导入可以：

• 减少最终构建包体积
• 避免循环依赖问题
• 明确表达开发意图

1.3 esModuleInterop 配置详解

esModuleInterop 是连接 ES 模块与 CommonJS 模块的桥梁，它解决了二者在导入/导出机制上的不兼容问题：

// tsconfig.json
{
  "compilerOptions": {
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

启用后，可以使用更符合直觉的导入语法：

// 未启用 esModuleInterop 时的 CommonJS 模块导入
import * as React from 'react';
const Component = React.Component;

// 启用 esModuleInterop 后
import React, { Component } from 'react';

底层实现原理是通过生成辅助函数（如 __importDefault 和 __importStar）来包装 CommonJS 模块，使其符合 ES 模块规范：

// 编译输出（简化版）
import * as reactModule from 'react';
const React = __importStar(reactModule);

2. 命名空间（Namespace）

2.1 何时使用命名空间

命名空间虽然是 TypeScript 早期的组织代码方式，但在特定场景仍然有其价值：

namespace Validation {
  export interface StringValidator {
    isValid(s: string): boolean;
  }
  
  // 内部实现，不导出
  const patterns = {
    email: /^[^@]+@[^@]+\.[^@]+$/
  };
  
  export class EmailValidator implements StringValidator {
    isValid(s: string): boolean {
      return patterns.email.test(s);
    }
  }
}

// 使用
const validator = new Validation.EmailValidator();

适用场景：

• 组织大型内部库
• 扩展全局对象
• 封装特定领域的功能集
• 处理没有模块化的第三方代码

2.2 与模块的对比

命名空间与 ES 模块的关键差异：

最佳实践：

• 在新项目中优先使用 ES 模块
• 命名空间适用于特定场景的补充手段
• 考虑未来代码维护和团队协作的需求

2.3 多文件命名空间

命名空间可以跨文件组织，通过 reference 指令建立联系：

// validators/email.ts
/// <reference path="./validation.ts" />
namespace Validation {
  export class EmailValidator implements StringValidator {
    isValid(s: string): boolean {
      return s.indexOf('@') > 0;
    }
  }
}

// validators/validation.ts
namespace Validation {
  export interface StringValidator {
    isValid(s: string): boolean;
  }
}

编译选项：

# 多文件编译到单个输出
tsc --outFile dist/validation.js validators/validation.ts validators/email.ts

# 或使用引用编译
tsc --outFile dist/validation.js validators/email.ts

3. 声明合并机制

3.1 接口合并

TypeScript 的接口可以进行声明合并，这是其类型系统的强大特性：

// 基础定义
interface ApiResponse {
  status: number;
  data: unknown;
}

// 扩展定义（声明合并）
interface ApiResponse {
  headers: Record<string, string>;
  timestamp: number;
}

// 结果等同于
interface ApiResponse {
  status: number;
  data: unknown;
  headers: Record<string, string>;
  timestamp: number;
}

合并规则：

• 非函数成员必须唯一或类型相同
• 函数成员同名视为重载
• 后声明的接口优先级更高（重载顺序）

3.2 命名空间合并

命名空间可以与其他声明类型合并，创建强大的扩展模式：

// 类与命名空间合并
class Calculator {
  add(a: number, b: number): number {
    return a + b;
  }
}

// 扩展计算器功能
namespace Calculator {
  export function multiply(a: number, b: number): number {
    return a * b;
  }
  
  export const PI = 3.14159;
}

// 使用
const calc = new Calculator();
calc.add(1, 2);       // 3
Calculator.multiply(2, 3); // 6
Calculator.PI;        // 3.14159

常见合并模式：

• 类+命名空间：添加静态成员
• 函数+命名空间：添加属性和方法
• 枚举+命名空间：添加辅助函数

3.3 模块扩展模式

模块扩展（Module Augmentation）允许安全地扩展第三方库的类型定义：

// 原始类型定义（来自库）
// node_modules/some-library/index.d.ts
declare module 'some-library' {
  export interface Options {
    timeout: number;
    retries: number;
  }
}

// 项目中扩展类型
// src/types/some-library.d.ts
declare module 'some-library' {
  export interface Options {
    logging?: boolean; // 添加新选项
    logLevel?: 'debug' | 'info' | 'warn' | 'error';
  }
  
  // 添加新导出
  export function enableDebug(): void;
}

实际应用场景：

• 扩展 React 的 ComponentProps 类型
• 增强第三方库的类型安全性
• 适配内部需求而不修改源码

4. 动态导入类型处理

4.1 import() 类型安全

TypeScript 支持动态导入的类型推导，确保运行时安全：

// 基础动态导入
const loadModule = async () => {
  const module = await import('./dynamicModule');
  module.someFunction(); // 类型安全！
};

// 泛型约束的动态导入
interface ModuleWithHandler {
  handler: (data: unknown) => void;
}

async function loadHandler<T extends ModuleWithHandler>(path: string): Promise<T['handler']> {
  const module = await import(path) as T;
  return module.handler;
}

// 使用
const handler = await loadHandler<ModuleWithHandler>('./handlers/dataHandler');
handler(someData);

实现细节：

• import() 返回 Promise<typeof Module>
• 保留了原始模块的类型信息
• 支持条件和动态路径导入

4.2 按需加载模块的类型定义

构建按需加载架构时的类型处理策略：

// 模块接口定义
// types/modules.d.ts
declare module 'app/modules' {
  export interface ModuleDefinition {
    initialize(): Promise<void>;
    cleanup(): void;
  }
  
  export interface ModuleRegistry {
    [key: string]: () => Promise<{ default: ModuleDefinition }>;
  }
}

// 实现动态加载系统
// src/moduleLoader.ts
import type { ModuleDefinition, ModuleRegistry } from 'app/modules';

const moduleRegistry: ModuleRegistry = {
  'dashboard': () => import('./modules/dashboard'),
  'settings': () => import('./modules/settings'),
  'reports': () => import('./modules/reports')
};

export async function loadModule(name: keyof typeof moduleRegistry): Promise<ModuleDefinition> {
  const moduleFactory = moduleRegistry[name];
  if (!moduleFactory) {
    throw new Error(`Module "${name}" not found`);
  }
  
  const { default: module } = await moduleFactory();
  await module.initialize();
  return module;
}

进阶技术：

• 使用索引访问类型增强类型安全
• 通过映射类型创建模块类型库
• 结合条件类型实现灵活的模块加载接口

5. 实战案例：React项目的模块组织策略

5.1 基于功能的模块化架构

// 项目结构
// src/
// ├── features/
// │   ├── auth/
// │   │   ├── index.ts         // 公共API
// │   │   ├── types.ts         // 类型定义
// │   │   ├── authSlice.ts     // 状态逻辑
// │   │   └── components/      // 相关组件
// │   ├── users/
// │   └── products/
// ├── shared/
// │   ├── api/
// │   ├── utils/
// │   └── components/
// └── app/
//     ├── store.ts
//     └── App.tsx

特点：

• 每个功能模块高内聚、低耦合
• 明确的公共API边界
• 封装内部实现细节

5.2 接口设计与模块互操作

// features/auth/types.ts
export interface User {
  id: string;
  name: string;
  role: 'admin' | 'user';
}

export interface AuthState {
  user: User | null;
  isAuthenticated: boolean;
  isLoading: boolean;
}

// features/auth/index.ts
export type { User, AuthState } from './types';
export { login, logout, checkAuth } from './authSlice';
export { default as LoginForm } from './components/LoginForm';
export { default as ProtectedRoute } from './components/ProtectedRoute';

// 在其他模块中使用
import { User, login, LoginForm } from '@/features/auth';

5.3 类型安全的异步模块加载

// app/moduleLoader.tsx
import React, { lazy, Suspense } from 'react';
import type { RouteProps } from 'react-router-dom';

// 模块类型定义
interface ModuleExports {
  default: React.ComponentType;
  getModuleData?: () => Promise<unknown>;
}

// 路由配置类型
interface AppRoute extends RouteProps {
  moduleKey: string;
  roles?: string[];
}

// 模块注册表
const moduleRegistry: Record<string, () => Promise<ModuleExports>> = {
  'dashboard': () => import('../features/dashboard'),
  'settings': () => import('../features/settings'),
  'reports': () => import('../features/reports')
};

// 构建类型安全的路由配置
export function createRoutes(): AppRoute[] {
  return [
    {
      path: '/dashboard',
      moduleKey: 'dashboard',
      roles: ['user', 'admin']
    },
    {
      path: '/settings',
      moduleKey: 'settings',
      roles: ['admin']
    },
    {
      path: '/reports',
      moduleKey: 'reports',
      roles: ['user', 'admin']
    }
  ];
}

// 渲染懒加载组件
export function renderModule(moduleKey: keyof typeof moduleRegistry): React.ReactNode {
  const LazyComponent = lazy(async () => {
    const module = await moduleRegistry[moduleKey]();
    // 可以在此处预加载数据
    if (module.getModuleData) {
      await module.getModuleData();
    }
    return { default: module.default };
  });

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <LazyComponent />
    </Suspense>
  );
}

5.4 构建时优化与模块分析

// webpack.config.js (使用TypeScript)
import { Configuration } from 'webpack';
import path from 'path';

const config: Configuration = {
  // ...其他配置
  
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendors: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          chunks: 'all'
        },
        features: {
          test: /[\\/]src[\\/]features[\\/]/,
          name(module: any) {
            // 提取特性名称作为chunk名
            const featurePath = module.context.match(/[\\/]features[\\/](.*?)[\\/]/);
            return featurePath ? `feature-${featurePath[1]}` : 'features';
          },
          chunks: 'all',
          minSize: 0
        }
      }
    }
  },
  
  resolve: {
    extensions: ['.ts', '.tsx', '.js'],
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@features': path.resolve(__dirname, 'src/features')
    }
  }
};

export default config;

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  
  build: {
    rollupOptions: {
      output: {
        manualChunks: (id) => {
          // Create vendor chunks
          if (id.includes('node_modules')) {
            return 'vendors';
          }
          
          // Create feature-based chunks
          const featureMatch = id.match(/[\/\\]src[\/\\]features[\/\\](.*?)[\/\\]/);
          if (featureMatch && featureMatch[1]) {
            return `feature-${featureMatch[1]}`;
          }
          
          return undefined; // default chunk
        }
      }
    }
  },
  
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@features': path.resolve(__dirname, 'src/features')
    }
  }
});

通过这种架构设计，可以实现：

• 代码按功能模块拆分加载
• 类型安全的跨模块通信
• 优化构建产物和加载性能
• 支持大型团队协作开发

总结

模块系统和命名空间是TypeScript中构建可扩展架构的基础，掌握这些概念能够显著提升代码组织质量和团队协作效率。