在 TypeScript 中，类型模块化（Type Modularization）是指将类型定义按照功能、模块或作用域进行拆分和管理，以提高代码的可维护性和复用性。以下是几种常见的类型模块化方案及最佳实践：

---

一、全局类型 vs 模块化类型

1、全局类型

如果 .d.ts 类型声明文件中不包含 import/export 语句，那么这些类型将被视为全局类型。

全局类型的特点是：自动全局生效，无需导入，但是需要注意可能导致命名冲突。

一般适用于：全局变量、扩展 Window 接口、全局常量等场景。

// types/global.d.ts
interface User {
  id: string;
  name: string;
}

declare const APP_ENV: "dev" | "prod";

使用：

const user: User = { id: "1", name: "Alice" }; // 直接使用

2、模块化类型

模块化类型指的是使用 export 或 import 语句将类型定义导出或导入到其他模块中。

模块化类型的特点是：需要显式导入，作用域隔离，避免全局污染。

一般适用于：组件/功能专属类型，避免全局污染。

示例：

// types/modules/post.d.ts
export interface Post {
  title: string;
  content: string;
}

使用：

import { Post } from "../types/modules/post";
const post: Post = { title: "Hello", content: "World" };

二、类型模块化的实现方式

1、按功能拆分类型文件

将类型按功能模块分组：

src

types

user.d.ts# 用户相关类型

post.d.ts# 文章相关类型

api.d.ts# API 响应类型

2、使用 namespace 命名空间 旧版 不推荐

旧版方案，现代 TS 推荐用模块

// types/lib.d.ts
declare namespace MyLib {
  interface Config {
    apiUrl: string;
  }
  export function init(config: Config): void;
}
// 使用
MyLib.init({ apiUrl: "/api" });

3、动态生成类型（type-fest 等工具库）

利用工具库组合复杂类型：

import { Merge, PartialDeep } from "type-fest";

type User = { name: string; age: number };
type PartialUser = PartialDeep<User>; // { name?: string; age?: number }

三、类型导入优化

1、统一导出入口（index.d.ts）

集中导出类型，简化导入路径：

// types/index.d.ts
export * from "./user";
export * from "./post";

使用：

import { User, Post } from "../types"; // 索引模式，无需指定具体文件

2、类型与实现分离

将类型定义和逻辑代码分开：

src

components

Button

Button.tsx# 组件逻辑

Button.types.ts# 组件类型

优先使用export，仅在必要时扩展全局（如 declare global）。

使用typeRoots 限制类型扫描范围（见下文）。

更新日志

2025/8/24 08:17

查看所有更新日志

• e7112-1于 2025/8/24