# 模块系统

URL: https://caijiao.org/koa/base/modules
Source: docs/koa/base/modules.md
Description: 了解 Koa 应用的模块化结构，包括如何组织中间件、路由、控制器与服务，从而构建可维护的项目架构。

在使用 Koa 开发中大型应用时，良好的模块系统对于项目的可维护性与可扩展性至关重要。虽然 [Koa](/koa/) 不强制项目结构，但我们可以借助模块划分思想，将项目拆解为多个功能单元进行组织。

## 模块化目标

- 解耦业务逻辑与路由、中间件
- 提高代码复用性和可读性
- 易于测试与维护

## 常见模块划分方式

一个典型的 Koa 项目模块结构如下：

```

project/
├── app.js                  # 应用主入口
├── routes/                 # 路由模块
│   ├── user.js
│   └── article.js
├── controllers/            # 控制器：处理具体请求逻辑
│   ├── userController.js
│   └── articleController.js
├── services/               # 服务层：处理数据库或外部 API
│   └── userService.js
├── middlewares/            # 自定义中间件
│   └── auth.js
├── models/                 # 数据模型（如使用 Sequelize/Mongoose）
└── config/                 # 配置文件（如数据库、JWT 密钥等）

````

## 示例：控制器与路由的拆分

### 控制器 `controllers/userController.js`

```js
exports.getProfile = async (ctx) => {
  ctx.body = { user: 'Tom', age: 28 };
};
````

### 路由模块 `routes/user.js`

```js
const Router = require('koa-router');
const userController = require('../controllers/userController');

const router = new Router({ prefix: '/user' });

router.get('/profile', userController.getProfile);

module.exports = router;
```

### 主应用入口 `app.js`

```js
const Koa = require('koa');
const userRoutes = require('./routes/user');

const app = new Koa();

app.use(userRoutes.routes());

app.listen(3000);
```

## 中间件模块化

可将权限验证、参数校验、日志等中间件抽离至 `middlewares/` 目录，并在入口或路由中使用：

```js
const auth = require('./middlewares/auth');
router.get('/secure', auth, controller.action);
```

## 项目组织建议

- 每个功能模块（如用户、文章）可封装为独立文件夹
- 控制器只处理请求逻辑，不直接访问数据库
- 服务层负责业务处理和数据交互

## 总结

Koa 虽然本身极简，但通过模块系统的组织，可以让开发者根据项目规模灵活搭建清晰的工程结构，有效提升项目的可维护性和扩展能力。