模块扩充

模块扩充的基本概念

TypeScript的模块扩充允许开发者在不修改原始声明的情况下扩展已有模块。这种机制特别适合为第三方库添加类型定义或增强内置类型。模块扩充的核心思想是利用声明合并特性，通过declare module语法对现有模块进行类型层面的扩展。

// 原始模块声明
declare module 'original-module' {
  export interface Config {
    timeout: number;
  }
}

// 模块扩充
declare module 'original-module' {
  export interface Config {
    retries?: number;  // 新增可选属性
  }
  
  export function newMethod(): void;  // 新增方法
}

全局模块的扩充方式

对于全局作用域中的类型，可以直接通过声明合并进行扩充。常见场景包括扩展浏览器内置对象或Node.js全局变量。

// 扩充Window接口
interface Window {
  myCustomProp: string;
}

// 扩充Array原型
interface Array<T> {
  shuffle(): T[];
}

Array.prototype.shuffle = function() {
  // 实现代码
  return this.sort(() => Math.random() - 0.5);
};

第三方库的类型扩充

当使用没有完整类型定义的第三方库时，模块扩充能完美解决类型问题。以流行的lodash库为例：

// lodash模块扩充
declare module 'lodash' {
  interface LoDashStatic {
    multiplyByTwo(value: number): number;
    deepClone<T>(obj: T): T;
  }
}

// 实际实现需要单独提供
_.multiplyByTwo = (n) => n * 2;
_.deepClone = (obj) => JSON.parse(JSON.stringify(obj));

命名空间合并技巧

模块扩充可以与命名空间合并结合使用，创建更复杂的类型结构：

// 原始命名空间
namespace Utilities {
  export function log(message: string) {
    console.log(message);
  }
}

// 扩充命名空间
namespace Utilities {
  export function error(message: string) {
    console.error(message);
  }
  
  export namespace Math {
    export function square(x: number) {
      return x * x;
    }
  }
}

环境模块的特殊处理

对于没有默认导出的模块，扩充时需要特殊处理：

// 假设一个CSS模块声明
declare module '*.css' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

// 扩充CSS模块支持SCSS
declare module '*.scss' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

类型守卫的模块扩充

可以结合类型守卫增强模块的类型安全性：

declare module 'my-library' {
  interface User {
    id: string;
    name: string;
  }
  
  export function isUser(obj: any): obj is User;
}

// 使用示例
import { isUser } from 'my-library';

const data = JSON.parse(response);
if (isUser(data)) {
  console.log(data.name);  // 类型安全访问
}

泛型模块扩充模式

对于需要保持类型灵活性的场景，可以使用泛型进行模块扩充：

declare module 'generic-module' {
  export interface ResponseWrapper<T = any> {
    data: T;
    status: number;
    meta?: {
      timestamp: Date;
      version: string;
    };
  }
  
  export function wrapResponse<T>(data: T): ResponseWrapper<T>;
}

多模块联合扩充

当需要跨模块扩充类型时，可以采用联合声明方式：

// 跨模块类型引用
declare module 'module-a' {
  export interface SharedType {
    id: string;
  }
}

declare module 'module-b' {
  import { SharedType } from 'module-a';
  
  export function process(input: SharedType): void;
}

动态模块加载的类型扩充

针对动态导入场景的类型支持：

declare module 'dynamic-module' {
  export type ModuleLoader<T> = () => Promise<{ default: T }>;
  
  export function loadComponent<T>(
    loader: ModuleLoader<T>,
    fallback?: React.ReactNode
  ): React.ComponentType<T>;
}

模块扩充的最佳实践

1. 保持扩充声明与原始声明结构一致
2. 为每个扩充添加清晰的JSDoc注释
3. 将扩充集中放在项目根目录的types文件夹
4. 避免循环依赖的扩充声明
5. 优先使用接口扩展而非类型别名

/**
 * 扩展React的默认属性
 */
declare module 'react' {
  interface HTMLAttributes<T> {
    // 添加自定义数据属性
    'data-custom'?: string;
    // 支持微前端场景的扩展属性
    'data-module'?: string;
  }
}

常见问题解决方案

处理模块扩充中的命名冲突：

// 使用命名空间隔离冲突
declare module 'conflict-module' {
  namespace Extended {
    export interface Options {
      customOption: boolean;
    }
  }
  
  export function method(options: Extended.Options): void;
}

处理类型覆盖问题：

// 使用Omit工具类型避免属性覆盖
declare module 'overwrite-module' {
  interface Original {
    prop: string;
  }
  
  interface Extended extends Omit<Original, 'prop'> {
    prop: number;  // 安全覆盖
    newProp: boolean;
  }
}

高级模式：条件类型扩充

结合TypeScript的条件类型实现智能扩充：

declare module 'conditional-module' {
  export type SmartResult<T> = 
    T extends string ? { text: T } :
    T extends number ? { value: T } :
    { data: T };
    
  export function smartProcess<T>(input: T): SmartResult<T>;
}

性能优化考虑

大型项目中的模块扩充优化策略：

// 使用引用减少重复声明
/// <reference types="./extensions/date" />
/// <reference types="./extensions/array" />

// 按需加载的类型扩充
declare module 'large-library' {
  export type FeatureFlags = 
    | 'newDashboard'
    | 'experimentalAPI'
    | 'legacySupport';
  
  export function isFeatureEnabled(flag: FeatureFlags): boolean;
}

测试策略验证

确保模块扩充正确性的测试方法：

// 类型测试示例
import { expectType } from 'tsd';

declare module 'tested-module' {
  export function addedMethod(input: string): number;
}

expectType<number>(addedMethod('test'));

工具链集成

与构建工具的协同工作配置：

// webpack环境变量扩充
declare module 'process' {
  global {
    namespace NodeJS {
      interface ProcessEnv {
        readonly CUSTOM_ENV: 'development' | 'production' | 'test';
        readonly ANALYTICS_ID?: string;
      }
    }
  }
}

历史版本兼容

处理不同版本库的类型扩充差异：

// 版本感知的类型扩充
declare module 'versioned-library' {
  export interface ApiV1 {
    oldMethod(): void;
  }
  
  export interface ApiV2 {
    newMethod(): void;
  }
  
  export function getApi(version: 1): ApiV1;
  export function getApi(version: 2): ApiV2;
}