koa3-demo/.qoder/quests/clean-src-directory.md

src 目录整理设计

概述

本设计旨在优化 koa3-demo 项目的 src 目录结构，在保持现有 MVC 架构不变的前提下，通过最小化的代码改动来提升代码组织的清晰度和可维护性。

当前目录结构分析

现状问题

• 目录层级较为扁平，业务模块分散
• controllers 按类型（Api/Page）分组，但缺乏按业务领域组织
• services 和 models 分离在不同的顶级目录
• 缺乏统一的模块组织规范

优势保持

• MVC 架构清晰，分层明确
• 中间件系统完善
• 路由自动发现机制完整
• 数据库操作层设计合理

整理方案

目标架构

采用领域驱动的模块化架构，在保持 MVC 分层的同时，按业务领域组织代码：

graph TB
    subgraph "src 目录结构"
        A[src/] --> B[app/]
        A --> C[modules/]
        A --> D[shared/]
        A --> E[presentation/]
        
        B --> B1[config/]
        B --> B2[providers/]
        B --> B3[bootstrap/]
        
        C --> C1[auth/]
        C --> C2[article/]
        C --> C3[user/]
        C --> C4[site-config/]
        
        D --> D1[utils/]
        D --> D2[constants/]
        D --> D3[helpers/]
        
        E --> E1[middlewares/]
        E --> E2[routes/]
        E --> E3[views/]
        
        subgraph "模块内部结构"
            C1 --> C1A[controllers/]
            C1 --> C1B[services/]
            C1 --> C1C[models/]
            C1 --> C1D[validators/]
        end
    end

详细目录规划

1. app/ - 应用核心

app/
├── config/          # 配置管理
│   ├── index.js     # 当前 src/config/index.js
│   └── database.js  # 数据库配置（从 db/ 提取）
├── providers/       # 服务提供者
│   ├── DatabaseProvider.js   # 数据库连接管理
│   └── index.js     # 提供者注册
└── bootstrap/       # 应用引导
    ├── app.js       # 应用实例（当前 global.js）
    ├── logger.js    # 日志配置
    └── index.js     # 引导入口

2. modules/ - 业务模块

modules/
├── auth/            # 认证模块
│   ├── controllers/
│   │   ├── AuthController.js      # API 控制器
│   │   └── AuthPageController.js  # 页面控制器
│   ├── services/
│   │   └── AuthService.js         # 从 userService.js 提取认证相关
│   ├── models/
│   │   └── UserModel.js           # 用户模型
│   └── validators/
│       └── AuthValidator.js       # 认证验证规则
├── user/            # 用户管理模块
│   ├── controllers/
│   │   └── ProfileController.js   # 用户资料控制器
│   ├── services/
│   │   └── UserService.js         # 用户业务服务
│   └── models/
│       └── UserModel.js           # 用户模型（共享）
├── article/         # 文章管理模块
│   ├── controllers/
│   │   └── ArticleController.js
│   ├── services/
│   │   └── ArticleService.js
│   └── models/
│       └── ArticleModel.js
├── bookmark/        # 书签管理模块
│   ├── services/
│   │   └── BookmarkService.js
│   └── models/
│       └── BookmarkModel.js
├── site-config/     # 站点配置模块
│   ├── services/
│   │   └── SiteConfigService.js
│   └── models/
│       └── SiteConfigModel.js
└── common/          # 通用模块
    ├── controllers/
    │   ├── ApiController.js
    │   ├── StatusController.js
    │   └── UploadController.js
    └── services/
        └── JobService.js

3. shared/ - 共享资源

shared/
├── utils/           # 工具函数
│   ├── error/
│   ├── router/
│   ├── bcrypt.js
│   ├── helper.js
│   └── scheduler.js
├── constants/       # 常量定义
│   ├── errors.js
│   └── status.js
└── base/            # 基础类
    ├── BaseController.js
    ├── BaseService.js
    └── BaseModel.js

4. presentation/ - 表现层

presentation/
├── middlewares/     # 中间件（当前 middlewares/）
├── routes/          # 路由管理
│   ├── api.js       # API 路由
│   ├── web.js       # 页面路由
│   └── index.js     # 路由注册
└── views/           # 视图模板（当前 views/）

5. infrastructure/ - 基础设施

infrastructure/
├── database/        # 数据库相关
│   ├── migrations/  # 迁移文件
│   ├── seeds/       # 种子数据
│   ├── docs/        # 数据库文档
│   └── index.js     # 数据库连接
└── jobs/            # 定时任务
    ├── exampleJob.js
    └── index.js

迁移策略

阶段一：创建新目录结构

1. 创建 app/, modules/, shared/, presentation/, infrastructure/ 目录
2. 建立各模块的子目录结构

阶段二：文件迁移与重组

1. 配置文件迁移

   • config/ → app/config/
   • 从 db/index.js 提取数据库配置到 app/config/database.js

2. 核心文件重组

   • global.js → app/bootstrap/app.js
   • logger.js → app/bootstrap/logger.js
   • 创建 app/bootstrap/index.js 统一引导

3. 业务模块化

   • 按业务领域创建模块目录
   • 将相关的 controllers, services, models 组织到对应模块

4. 基础设施迁移

   • db/ → infrastructure/database/
   • jobs/ → infrastructure/jobs/
   • middlewares/ → presentation/middlewares/
   • views/ → presentation/views/

阶段三：更新引用路径

1. 更新 main.js 中的导入路径
2. 更新中间件注册路径
3. 更新服务间的依赖引用
4. 更新路由自动发现配置

实现细节

模块内 MVC 组织

每个业务模块内部采用标准的 MVC 分层：

graph LR
    subgraph "auth 模块"
        AC[AuthController] --> AS[AuthService]
        AS --> UM[UserModel]
        APC[AuthPageController] --> AS
    end
    
    subgraph "共享层"
        BC[BaseController]
        BS[BaseService] 
        BM[BaseModel]
    end
    
    AC -.-> BC
    AS -.-> BS
    UM -.-> BM

路径映射表

当前路径	新路径	说明
src/config/	src/app/config/	配置管理
src/global.js	src/app/bootstrap/app.js	应用实例
src/logger.js	src/app/bootstrap/logger.js	日志配置
src/controllers/Api/AuthController.js	src/modules/auth/controllers/AuthController.js	认证API控制器
src/controllers/Page/AuthPageController.js	src/modules/auth/controllers/AuthPageController.js	认证页面控制器
src/services/userService.js	src/modules/auth/services/AuthService.js + src/modules/user/services/UserService.js	拆分认证和用户服务
src/db/models/UserModel.js	src/modules/auth/models/UserModel.js	用户模型
src/middlewares/	src/presentation/middlewares/	中间件
src/views/	src/presentation/views/	视图模板
src/db/migrations/	src/infrastructure/database/migrations/	数据库迁移
src/jobs/	src/infrastructure/jobs/	定时任务

导入路径更新

main.js 更新示例

// 原始导入
import { app } from "./global"
import { logger } from "./logger.js"
import "./jobs/index.js"
import LoadMiddlewares from "./middlewares/install.js"

// 更新后导入
import { app } from "./app/bootstrap/app.js"
import { logger } from "./app/bootstrap/logger.js" 
import "./infrastructure/jobs/index.js"
import LoadMiddlewares from "./presentation/middlewares/install.js"

自动路由发现适配

更新路由扫描配置以适配新的模块结构：

// 扫描路径配置
const scanPaths = [
    'src/modules/*/controllers/**/*.js',
    'src/modules/common/controllers/**/*.js'
];

文件操作清单

需要移动的文件

• src/config/ → src/app/config/
• src/global.js → src/app/bootstrap/app.js
• src/logger.js → src/app/bootstrap/logger.js
• src/db/ → src/infrastructure/database/
• src/jobs/ → src/infrastructure/jobs/
• src/middlewares/ → src/presentation/middlewares/
• src/views/ → src/presentation/views/
• src/utils/ → src/shared/utils/

需要按模块重组的文件

• 认证相关：AuthController.js, AuthPageController.js, userService.js(部分), UserModel.js
• 用户管理：ProfileController.js, userService.js(部分)
• 文章管理：ArticleController.js, ArticleService.js, ArticleModel.js
• 书签管理：BookmarkService.js, BookmarkModel.js
• 站点配置：SiteConfigService.js, SiteConfigModel.js
• 通用功能：ApiController.js, StatusController.js, UploadController.js, JobController.js

需要更新导入的文件

• src/main.js
• src/presentation/middlewares/install.js
• 各个控制器文件中的服务导入
• 各个服务文件中的模型导入

预期效果

代码组织改善

1. 业务内聚性：相关的 controller、service、model 集中在同一模块
2. 职责清晰：每个模块负责特定的业务领域
3. 依赖明确：模块间依赖关系更加清晰可见

开发体验提升

1. 文件查找：按业务功能快速定位相关文件
2. 代码维护：修改某个功能时，相关文件集中在一个目录
3. 团队协作：不同开发者可以专注于不同的业务模块

架构扩展性

1. 新增模块：按照统一规范快速创建新的业务模块
2. 功能拆分：大模块可以进一步拆分成子模块
3. 微服务准备：为将来可能的微服务拆分做好准备

风险评估与注意事项

低风险操作

• 目录创建和文件移动
• 路径引用更新
• 配置文件调整

需要谨慎的操作

• 路由自动发现逻辑调整
• 中间件注册顺序维护
• 数据库连接管理迁移

测试验证点

1. 应用启动正常
2. 路由注册成功
3. 数据库连接正常
4. 中间件功能完整
5. 各业务模块功能正常

本方案通过最小化改动实现目录结构优化，保持原有架构优势的同时提升代码组织质量，为项目的长期维护和扩展奠定良好基础。