koa3-demo/.qoder/quests/optimize-source-structure.md

Koa3-Demo src目录结构优化设计

1. 概述

当前koa3-demo项目采用MVC分层架构，但在代码组织上存在一些可以优化的地方。本设计旨在优化src目录结构，使代码职责更加明确，结构更加清晰，便于维护和扩展。

2. 当前架构分析

2.1 现有目录结构

src/
├── config/           # 配置文件
├── controllers/      # 控制器层
│   ├── Api/         # API控制器
│   └── Page/        # 页面控制器
├── db/              # 数据库相关
├── jobs/            # 定时任务
├── middlewares/     # Koa中间件
├── services/        # 服务层
├── utils/           # 工具类
├── views/           # 视图模板
├── global.js        # 全局应用实例
├── logger.js        # 日志配置
└── main.js          # 应用入口

2.2 现有架构问题

问题类型	具体问题	影响
职责混淆	utils目录包含多种类型工具，缺乏分类	查找困难，职责不清
层次不清	middlewares安装逻辑与业务逻辑混在一起	维护困难
配置分散	配置相关代码分散在多个文件	管理困难
缺乏核心层	没有明确的应用核心层	启动流程不清晰

3. 优化目标

• 职责明确: 每个目录和文件都有明确的单一职责
• 层次清晰: 遵循分层架构原则，依赖关系清晰
• 易于扩展: 新功能可以轻松添加到相应位置
• 便于维护: 代码组织逻辑清晰，便于理解和修改

4. 优化后的目录结构

4.1 新的目录组织

src/
├── app/                # 应用核心层
│   ├── bootstrap/      # 应用启动引导
│   │   ├── app.js      # 应用实例创建
│   │   ├── middleware.js # 中间件注册
│   │   └── routes.js   # 路由注册
│   ├── config/         # 应用配置
│   │   ├── index.js    # 主配置文件
│   │   ├── database.js # 数据库配置
│   │   ├── logger.js   # 日志配置
│   │   └── server.js   # 服务器配置
│   └── providers/      # 服务提供者
│       ├── DatabaseProvider.js
│       ├── LoggerProvider.js
│       └── JobProvider.js
├── core/               # 核心基础设施
│   ├── base/          # 基础类
│   │   ├── BaseController.js
│   │   ├── BaseService.js
│   │   └── BaseModel.js
│   ├── contracts/     # 接口契约
│   │   ├── ServiceContract.js
│   │   └── RepositoryContract.js
│   ├── exceptions/    # 异常处理
│   │   ├── BaseException.js
│   │   ├── ValidationException.js
│   │   └── NotFoundResponse.js
│   └── middleware/    # 核心中间件
│       ├── auth/
│       ├── validation/
│       ├── error/
│       └── response/
├── modules/           # 功能模块（按业务领域划分）
│   ├── auth/         # 认证模块
│   │   ├── controllers/
│   │   ├── services/
│   │   ├── models/
│   │   ├── middleware/
│   │   └── routes.js
│   ├── user/         # 用户模块
│   │   ├── controllers/
│   │   ├── services/
│   │   ├── models/
│   │   └── routes.js
│   ├── article/      # 文章模块
│   │   ├── controllers/
│   │   ├── services/
│   │   ├── models/
│   │   └── routes.js
│   └── shared/       # 共享模块
│       ├── controllers/
│       ├── services/
│       └── models/
├── infrastructure/   # 基础设施层
│   ├── database/     # 数据库基础设施
│   │   ├── migrations/
│   │   ├── seeds/
│   │   ├── connection.js
│   │   └── queryBuilder.js
│   ├── cache/        # 缓存基础设施
│   │   ├── MemoryCache.js
│   │   └── CacheManager.js
│   ├── jobs/         # 任务调度基础设施
│   │   ├── scheduler.js
│   │   ├── JobQueue.js
│   │   └── jobs/
│   ├── external/     # 外部服务集成
│   │   ├── email/
│   │   └── storage/
│   └── monitoring/   # 监控相关
│       ├── health.js
│       └── metrics.js
├── shared/           # 共享资源
│   ├── utils/        # 工具函数
│   │   ├── crypto/   # 加密相关
│   │   ├── date/     # 日期处理
│   │   ├── string/   # 字符串处理
│   │   └── validation/ # 验证工具
│   ├── constants/    # 常量定义
│   │   ├── errors.js
│   │   ├── status.js
│   │   └── permissions.js
│   ├── types/        # 类型定义
│   │   └── common.js
│   └── helpers/      # 辅助函数
│       ├── response.js
│       └── request.js
├── presentation/     # 表现层
│   ├── views/        # 视图模板
│   ├── assets/       # 前端资源（如果有）
│   └── routes/       # 路由定义
│       ├── api.js
│       ├── web.js
│       └── index.js
└── main.js          # 应用入口

4.2 架构层次图

graph TB
    subgraph "表现层 (Presentation)"
        A[Controllers] --> B[Routes]
        C[Views] --> A
    end
    
    subgraph "应用层 (Application)"
        D[Services] --> E[DTOs]
        F[Use Cases] --> D
    end
    
    subgraph "领域层 (Domain)"
        G[Models] --> H[Entities]
        I[Business Logic] --> G
    end
    
    subgraph "基础设施层 (Infrastructure)"
        J[Database] --> K[External APIs]
        L[Cache] --> M[Jobs]
        N[Monitoring] --> L
    end
    
    subgraph "核心层 (Core)"
        O[Base Classes] --> P[Contracts]
        Q[Exceptions] --> R[Middleware]
    end
    
    A --> D
    D --> G
    G --> J
    O --> A
    O --> D
    O --> G

5. 模块化设计

5.1 按业务领域划分模块

每个模块包含该业务领域的完整功能：

graph LR
    subgraph "Auth Module"
        A1[AuthController] --> A2[AuthService]
        A2 --> A3[UserModel]
        A4[AuthMiddleware] --> A1
        A5[auth.routes.js] --> A1
    end
    
    subgraph "User Module"
        U1[UserController] --> U2[UserService]
        U2 --> U3[UserModel]
        U4[user.routes.js] --> U1
    end
    
    subgraph "Article Module"
        AR1[ArticleController] --> AR2[ArticleService]
        AR2 --> AR3[ArticleModel]
        AR4[article.routes.js] --> AR1
    end

5.2 模块间依赖管理

依赖类型	规则	示例
向上依赖	可以依赖core和shared	modules/user依赖core/base
平级依赖	通过shared接口通信	user模块通过shared调用auth
向下依赖	禁止	core不能依赖modules

6. 核心组件重构

6.1 应用启动流程

sequenceDiagram
    participant Main as main.js
    participant Bootstrap as app/bootstrap
    participant Providers as app/providers
    participant Modules as modules/*
    participant Server as Server
    
    Main->>Bootstrap: 初始化应用
    Bootstrap->>Providers: 注册服务提供者
    Providers->>Providers: 数据库、日志、任务等
    Bootstrap->>Modules: 加载业务模块
    Modules->>Modules: 注册路由和中间件
    Bootstrap->>Server: 启动HTTP服务器
    Server->>Main: 返回应用实例

6.2 配置管理优化

// app/config/index.js
export default {
  server: {
    port: process.env.PORT || 3000,
    host: process.env.HOST || 'localhost'
  },
  database: {
    // 数据库配置
  },
  logger: {
    // 日志配置
  },
  cache: {
    // 缓存配置
  }
}

6.3 中间件组织优化

graph TB
    subgraph "Global Middleware"
        A[Error Handler] --> B[Response Time]
        B --> C[Security Headers]
        C --> D[CORS]
    end
    
    subgraph "Auth Middleware"
        E[JWT Verification] --> F[Permission Check]
        F --> G[Rate Limiting]
    end
    
    subgraph "Validation Middleware"
        H[Input Validation] --> I[Data Sanitization]
    end
    
    subgraph "Response Middleware"
        J[JSON Formatter] --> K[Compression]
        K --> L[Caching Headers]
    end
    
    A --> E
    E --> H
    H --> J

7. 迁移策略

7.1 迁移步骤

阶段	操作	文件移动	风险等级
第1阶段	建立新目录结构	创建空目录	低
第2阶段	迁移配置文件	config/ → app/config/	中
第3阶段	重构核心基础设施	创建core/	中
第4阶段	按模块迁移业务代码	controllers/services → modules/	高
第5阶段	优化工具类和帮助函数	utils/ → shared/	中
第6阶段	调整应用启动流程	修改main.js和global.js	高

7.2 向后兼容性

// 在迁移期间保持向后兼容
// legacy/index.js
export * from '../modules/auth/services/AuthService.js'
export * from '../modules/user/services/UserService.js'
// ... 其他导出

8. 测试策略

8.1 测试目录结构

tests/
├── unit/
│   ├── modules/
│   ├── core/
│   └── shared/
├── integration/
│   ├── api/
│   └── database/
├── e2e/
└── fixtures/

8.2 测试分层策略

pyramid TB
    subgraph "测试金字塔"
        A[E2E Tests<br/>端到端测试]
        B[Integration Tests<br/>集成测试]
        C[Unit Tests<br/>单元测试]
    end
    
    C --> B
    B --> A

9. 代码质量保证

9.1 ESLint规则配置

// .eslintrc.js
module.exports = {
  rules: {
    // 模块导入规则
    'import/no-relative-parent-imports': 'error',
    // 强制使用绝对路径
    'import/no-relative-imports': 'warn'
  }
}

9.2 代码组织规范

规范类型	规则	示例
文件命名	PascalCase for classes, camelCase for others	UserService.js, authHelper.js
目录命名	kebab-case	user-management, api-gateway
导入顺序	core → shared → modules → external	先导入基础类，再导入业务类