优雅的 TypeScript 项目结构

这是一个基于 ImageMagick 的图片优化插件项目，展示了优雅的 TypeScript 项目目录结构。

📁 项目目录结构

optimizebyimagemagick/
├── 📁 src/                          # 源代码目录
│   ├── 📁 types/                    # 类型定义
│   │   └── index.ts                 # 所有类型定义
│   ├── 📁 config/                   # 配置管理
│   │   └── index.ts                 # 配置类和默认配置
│   ├── 📁 utils/                    # 工具函数
│   │   └── index.ts                 # 文件、图片、时间工具类
│   ├── 📁 logger/                   # 日志管理
│   │   └── index.ts                 # 日志类和工厂
│   ├── 📁 analyzer/                 # 图片分析器
│   │   └── index.ts                 # 图片分析逻辑
│   ├── 📁 optimizer/                # 图片优化器
│   │   └── index.ts                 # 图片优化逻辑
│   └── index.ts                     # 主入口文件
├── 📁 dist/                         # 编译输出目录
├── 📁 tests/                        # 测试文件
│   ├── 📁 unit/                     # 单元测试
│   ├── 📁 integration/              # 集成测试
│   └── 📁 fixtures/                 # 测试数据
├── 📁 docs/                         # 文档
│   ├── API.md                       # API 文档
│   └── CONTRIBUTING.md              # 贡献指南
├── 📁 examples/                     # 使用示例
├── 📁 scripts/                      # 构建脚本
├── 📁 .github/                      # GitHub 配置
│   └── workflows/                   # CI/CD 配置
├── package.json                     # 项目配置
├── tsconfig.json                    # TypeScript 配置
├── .eslintrc.js                     # ESLint 配置
├── .prettierrc                      # Prettier 配置
├── jest.config.js                   # Jest 测试配置
├── .gitignore                       # Git 忽略文件
├── README.md                        # 项目说明
└── LICENSE                          # 许可证

🏗️ 架构设计原则

1. 模块化设计

• 单一职责: 每个模块只负责一个特定功能
• 高内聚低耦合: 模块内部紧密相关，模块间松散依赖
• 接口分离: 通过接口定义模块间的契约

2. 目录组织

• 按功能分组: 相关功能放在同一目录下
• 清晰的层次: 从通用到具体，从底层到高层
• 易于扩展: 新功能可以轻松添加新模块

3. 类型安全

• 完整的类型定义: 所有接口和数据结构都有类型定义
• 类型导出: 通过 types/index.ts 统一导出所有类型
• 类型检查: 严格的 TypeScript 配置

📦 核心模块

1. 类型定义 (src/types/)

// 定义所有接口和类型
export interface ImageInfo { ... }
export interface OptimizationConfig { ... }
export interface ImageOptimizer { ... }

2. 配置管理 (src/config/)

// 管理应用配置
export class ConfigManager {
  getConfig(): OptimizationConfig
  updateConfig(updates: Partial<OptimizationConfig>): void
  validateConfig(config: OptimizationConfig): string[]
}

3. 工具函数 (src/utils/)

// 提供通用工具函数
export class FileUtils { ... }
export class ImageUtils { ... }
export class TimeUtils { ... }

4. 日志管理 (src/logger/)

// 统一的日志处理
export class Logger {
  debug(message: string): void
  info(message: string): void
  warn(message: string): void
  error(message: string): void
}

5. 业务逻辑 (src/analyzer/, src/optimizer/)

// 核心业务逻辑
export class ImageAnalyzerImpl implements ImageAnalyzer { ... }
export class ImageOptimizerImpl implements ImageOptimizer { ... }

🔧 开发工具配置

TypeScript 配置 (tsconfig.json)

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "declaration": true,
    "sourceMap": true,
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

代码质量工具

• ESLint: 代码规范检查
• Prettier: 代码格式化
• Jest: 单元测试
• TypeScript: 类型检查

📋 最佳实践

1. 文件命名

• 使用 kebab-case 命名目录
• 使用 PascalCase 命名类
• 使用 camelCase 命名函数和变量

2. 导入导出

• 使用 index.ts 统一导出模块
• 避免循环依赖
• 使用相对路径导入

3. 错误处理

• 统一的错误处理机制
• 详细的错误信息
• 优雅的错误恢复

4. 测试策略

• 单元测试覆盖核心逻辑
• 集成测试验证模块协作
• 端到端测试验证完整流程

🚀 快速开始

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建项目
npm run build

# 运行测试
npm test

# 代码检查
npm run lint

📈 项目优势

1. 可维护性: 清晰的模块结构和类型定义
2. 可扩展性: 易于添加新功能和模块
3. 可测试性: 模块化设计便于单元测试
4. 可读性: 一致的代码风格和文档
5. 类型安全: 完整的 TypeScript 类型系统

这种项目结构适用于中大型 TypeScript 项目，提供了良好的可维护性和扩展性。