在 TypeScript 中，创建和组织库（library）的结构非常重要，它直接影响到库的可维护性、可用性以及用户的使用体验。下面详细介绍如何设计和组织 TypeScript 库的结构。
1. 基本结构
一个典型的 TypeScript 库通常包含以下基本元素：
- 源代码文件夹（src）：存放 TypeScript 源码文件。
- 编译输出文件夹（dist 或 lib）：存放编译后的 JavaScript 文件（如果需要发布给用户）。
- 类型声明文件夹（types 或 typings）：存放 TypeScript 声明文件（
.d.ts）。
2. 设计原则和最佳实践
2.1. 使用 ES 模块
推荐使用 ES 模块作为默认的模块格式，因为它提供了静态分析、树摇（去除未使用代码）和更清晰的语法。如果需要兼容 CommonJS（例如在 Node.js 中使用），可以通过工具进行转换或使用条件导出。
// Example: myModule.ts
export function foo() { /* function implementation */ }
export const bar = 42;
2.2. 利用命名空间和模块
- 命名空间（Namespace）：用于将相关的类型和函数组织在一起，但在现代 TypeScript 开发中，推荐使用 ES 模块来代替命名空间。
// Example: myNamespace.ts namespace MyNamespace { export function foo() { /* function implementation */ } export const bar = 42; } - 模块（Module）：用于将相关的代码组织成一个独立的单元，可以导出和导入模块中的内容。
// Example: myModule.ts export function foo() { /* function implementation */ } export const bar = 42;
2.3. 声明文件
对于每个 TypeScript 文件，TypeScript 编译器会自动生成对应的声明文件（.d.ts），如果需要自定义声明，可以创建单独的声明文件。
// Example: myModule.d.ts
export declare function foo(): void;
export declare const bar: number;
2.4. 模块化的组织方式
根据功能和使用频率，将功能相关的代码组织成模块，并尽可能减少模块之间的耦合。可以通过模块的导入和导出来管理模块之间的依赖关系。
2.5. 编译和构建
在 tsconfig.json 中配置编译选项，确保 TypeScript 编译器可以正确地将 TypeScript 代码转换为 JavaScript 代码，并生成声明文件。
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"outDir": "dist",
"declaration": true,
"declarationDir": "types"
},
"include": ["src/**/*"]
}
3. 示例应用
假设有一个名为 my-library 的 TypeScript 库，可以按以下结构组织代码：
my-library/
├── src/
│ ├── index.ts // 主入口文件
│ ├── utils.ts // 工具函数
│ └── types.ts // 类型声明
├── dist/ // 编译输出目录
├── types/ // 声明文件目录
│ ├── index.d.ts
│ ├── utils.d.ts
│ └── types.d.ts
└── tsconfig.json // TypeScript 配置文件
在 index.ts 中导出库的主要功能，例如：
// src/index.ts
export * from './utils';
export * from './types';
然后在 tsconfig.json 中配置编译选项，生成 JavaScript 文件和声明文件到 dist 和 types 目录。
4. 发布和文档化
发布 TypeScript 库时，可以使用 npm 进行发布，并确保包含编译后的 JavaScript 文件和相应的声明文件。另外，编写清晰的文档（如 README.md 文件）来说明库的用途、安装方法和使用示例，提高库的易用性和可维护性。
总结
设计和组织 TypeScript 库的结构是一个综合考虑功能模块化、依赖管理、编译配置和发布流程的过程。通过合理的结构设计，可以使得库更易于维护、扩展和使用，提高代码的可读性和可靠性。