TypeScript学习-第10章：模块与命名空间

上一章咱们搞定了类型断言与缩小，终于能精准拿捏各种类型细节了。可一进入大型项目就傻眼：所有代码堆在一个文件里，像乱炖的大杂烩；变量函数互相污染，改一处牵一发而动全身；第三方库引入后没类型提示，写代码全靠猜......别慌！TypeScript的"代码组织神器"------模块（Module）与命名空间（Namespace）来了！前者负责现代项目的代码拆分与复用，后者兜底旧代码的全局作用域管理，二者联手让你的代码从"一团乱麻"变"井井有条"。今天就用接地气的方式，吃透这两个大型项目必备技能。

一、ES模块：现代TS的"代码拆分标配"

模块的核心思想的是"按功能拆分代码，独立管理，按需导入导出"，就像把家里的物品按"厨房、卧室、客厅"分类摆放，要用时精准取用，不用时互不干扰。TS完全兼容ES6模块规范，核心就是 export（导出）和 import（导入）这对"黄金搭档"。

1. 两种导出方式：默认导出 vs 命名导出

导出就像"打包快递"，默认导出是"专属包裹"（一个文件仅一个），命名导出是"分类包裹"（一个文件多个，需带名字），按需选择即可。

typescript 复制代码

// 模块文件：utils.ts（工具函数模块）
// 1. 命名导出（多个，带名字，用{}包裹）
export function formatDate(date: Date): string {
  return date.toLocaleDateString();
}

export const PI = 3.1415926;

// 2. 默认导出（一个文件仅一个，无需{}，可自定义名字导入）
export default function calculateSum(a: number, b: number): number {
  return a + b;
}

对应的导入方式也不同，注意默认导出与命名导出的混用规则：

typescript 复制代码

// 导入模块：index.ts
// 1. 导入默认导出（可自定义名字，无需{}）
import sum from "./utils"; // 自定义名字sum，对应默认导出的calculateSum

// 2. 导入命名导出（必须用{}，名字需与导出一致，可重命名）
import { formatDate, PI as CirclePI } from "./utils"; // PI重命名为CirclePI

// 3. 混合导入（默认导出在前，命名导出在后）
import sum, { formatDate } from "./utils";

// 4. 导入所有命名导出（用* as 别名打包）
import * as Utils from "./utils";
Utils.formatDate(new Date());
Utils.PI;
sum(1, 2);

避坑提醒：默认导出一个文件仅能有一个，若写多个默认导出会编译报错；命名导出导入时必须带{}，名字不匹配可通过 as 重命名，避免命名冲突。

2. 模块的核心优势：隔离作用域+类型联动

模块最关键的特性是"文件级作用域隔离"------模块内的变量、函数默认仅在模块内可见，必须通过 export 才能对外暴露，从根源上解决全局变量污染问题。同时，TS模块会自动联动类型，导入后能获得完整的类型提示，无需额外断言。

typescript 复制代码

// 模块文件：user.ts
export interface User {
  name: string;
  age: number;
}

export function getUserInfo(user: User): string {
  return `姓名：${user.name}，年龄：${user.age}`;
}

// 导入后自动获得类型提示
import { User, getUserInfo } from "./user";
const user: User = { name: "张三", age: 25 };
getUserInfo(user); // 完整类型提示，参数错误会报错

二、模块解析：TS如何"找到"你的模块？

导入模块时，TS会按特定规则查找模块文件，这个过程就是"模块解析"。就像找朋友家的路，要么按"相对位置"找（从当前文件出发），要么按"绝对位置"找（按统一门牌号），搞懂规则能避免"找不到模块"的玄学报错。

1. 两种解析路径：相对路径 vs 绝对路径

相对路径 ：以 ./（当前目录）或 ../（上级目录）开头，适用于项目内部模块，路径基于当前文件位置。是日常开发最常用的方式，直观且不易出错。
// 相对路径导入（当前文件同级目录的utils.ts） import { formatDate } from "./utils"; // 上级目录的user.ts import { User } from "../user";
绝对路径 ：不以 ./ 开头，基于项目根目录查找。需配置TS的 baseUrl 或 paths（在tsconfig.json中），适用于大型项目，避免多层 ../ 的繁琐路径。

`

// tsconfig.json 配置

{

"compilerOptions": {

"baseUrl": "./src", // 基础路径为src目录

"paths": {

"@/": [" "] // 别名配置，@代表src目录

}

}

}

// 绝对路径/别名导入

import { formatDate } from "utils"; // 基于baseUrl查找src/utils.ts

import { User } from "@/user"; // 基于别名@查找src/user.ts

2. TS模块解析的核心规则

TS默认按"Node模块解析规则"（模拟Node.js的查找逻辑）查找模块，流程简化如下：

查找与导入路径同名的 .ts、.tsx 文件（优先TS文件）；
若找不到，查找同名文件夹，读取文件夹内的 index.ts（默认入口文件）；
若配置了 baseUrl 或 paths，先按配置规则转换路径，再执行上述查找。

💡 小技巧：若导入第三方库（如lodash），TS会先查找库的类型文件（.d.ts），再查找JS文件，确保类型提示正常。

三、命名空间：旧代码的"全局作用域围栏"

命名空间（Namespace）是TS早期为解决全局作用域污染设计的方案，用 namespace 关键字将代码包裹，形成独立的作用域，就像给全局代码围了一圈"围栏"，防止变量函数互相干扰。但注意：现代TS项目优先用ES模块，命名空间仅用于兼容旧代码或全局脚本场景。

1. 命名空间的基础用法：包裹与导出

typescript 复制代码

// 命名空间：MathUtils（数学工具命名空间）
namespace MathUtils {
  // 命名空间内的成员默认仅内部可见
  const PI = 3.1415926;

  // 对外暴露成员需用export
  export function calculateArea(radius: number): number {
    return PI * radius * radius;
  }

  export function calculatePerimeter(radius: number): number {
    return 2 * PI * radius;
  }
}

// 使用命名空间成员（通过"命名空间.成员名"访问）
MathUtils.calculateArea(5); // 合法
MathUtils.PI; // 报错：PI是命名空间内私有成员，未导出

2. 命名空间与ES模块的区别（避坑关键）

很多人会混淆命名空间与模块，核心区别在于"作用域与使用场景"，一张表讲清：

对比维度	ES模块	命名空间
作用域	文件级作用域，天然隔离	全局作用域下的子作用域，需手动包裹
使用场景	现代TS/JS项目，代码拆分与复用	兼容旧代码、全局脚本，不推荐新项目
导入导出	用import/export，支持按需导入	用namespace包裹+内部export，通过命名空间访问
核心建议：新项目直接用ES模块，不要用命名空间；若维护旧项目遇到全局变量污染，可用命名空间兜底，逐步迁移到模块方案。

四、模块类型声明：给第三方库"加类型说明书"

导入第三方JS库（如jQuery、lodash）时，TS会报错"找不到模块的声明文件"，因为这些库没有自带TS类型信息。这时候就需要"类型声明文件"（后缀 .d.ts），相当于给无说明书的工具加了一份"类型说明书"，让TS能识别库的类型，提供提示。

1. 第三方库的类型声明：@types包

大部分主流第三方库的类型声明都已收录在 @types 仓库中，只需安装对应的 @types/库名 包，就能获得完整类型提示，无需手动编写。

bash 复制代码

# 安装jQuery的类型声明包
npm install @types/jquery --save-dev

# 安装后直接导入使用，自动获得类型提示
import $ from "jquery";
$("#app").css("color", "red"); // 完整类型提示，参数错误报错

2. 自定义类型声明：.d.ts文件的用法

若第三方库没有对应的@types包，或需要扩展已有类型，可手动编写 .d.ts 文件，用 declare 关键字声明类型。

typescript 复制代码

// 自定义类型声明文件：custom.d.ts
// 1. 声明全局变量
declare const VERSION: string;

// 2. 声明模块类型（给无类型的JS模块加类型）
declare module "custom-js-lib" {
  export function doSomething(arg: string): void;
  export interface CustomOptions {
    timeout: number;
    callback: () => void;
  }
}

// 3. 扩展已有类型（如扩展jQuery）
declare interface JQuery {
  // 给jQuery添加自定义方法的类型
  myPlugin(options: CustomOptions): JQuery;
}

// 使用自定义声明
import { doSomething } from "custom-js-lib";
doSomething("hello");
$("#app").myPlugin({ timeout: 1000, callback: () => {} });

💡 注意：.d.ts 文件仅用于类型声明，不包含具体实现代码，TS编译时会自动识别该文件中的类型。

五、实战：模块化拆分TS项目

学完知识点，咱们用一个简单案例演示如何拆分TS项目为多个模块，实现模块化开发，感受代码组织的魅力。

项目结构（按功能拆分）

模块拆分与导入导出实现

typescript 复制代码

// 1. 工具模块：utils/date.ts
export function formatDate(date: Date, format: string = "yyyy-MM-dd"): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, "0");
  const day = String(date.getDate()).padStart(2, "0");
  return format.replace("yyyy", year.toString()).replace("MM", month).replace("dd", day);
}

// 2. 工具模块：utils/math.ts
export default function calculateSum(a: number, b: number): number {
  return a + b;
}

// 3. 用户类型声明：user/type.d.ts
export interface User {
  id: number;
  name: string;
  age: number;
  registerTime: string;
}

// 4. 用户模块：user/index.ts
import { formatDate } from "../utils/date";
import { User } from "./type";

export function createUser(name: string, age: number): User {
  return {
    id: Math.random(),
    name,
    age,
    registerTime: formatDate(new Date())
  };
}

// 5. 入口文件：index.ts
import sum from "./utils/math";
import { createUser } from "./user";

const total = sum(10, 20);
const user = createUser("张三", 25);
console.log("总和：", total);
console.log("用户信息：", user);

核心优势：按功能拆分后，代码职责清晰，可单独维护、测试，导入时按需取用，避免全局污染，同时借助TS类型联动，确保模块间调用的类型安全。

六、避坑指南与深度总结

模块与命名空间别混用：新项目坚决用ES模块，命名空间仅兜底旧代码，混用会导致代码混乱、类型推断异常。
路径配置要规范 ：大型项目建议配置 baseUrl 和别名（如@），避免多层 ../ 路径，同时确保tsconfig.json配置与项目结构一致。
类型声明文件的放置 ：自定义 .d.ts 文件建议放在项目根目录或src目录下，TS会自动识别，无需手动导入。
默认导出慎用：默认导出虽灵活，但重构时易出错（名字可自定义），多人协作项目建议优先用命名导出，类型更明确。

最后总结：模块与命名空间的核心是"代码组织与作用域隔离"------ES模块是现代TS项目的首选，解决代码拆分、复用与类型联动；命名空间兜底旧代码的全局污染问题；.d.ts文件则保障第三方库的类型安全。掌握这套组合拳，无论多大规模的TS项目，都能保持代码清晰、可维护，彻底告别"代码乱炖"的尴尬。