create-pixle-koa-template 1.0.0

package/template//344/275/277/347/224/250/346/225/231/347/250/213.md

@@ -0,0 +1,881 @@
+# Koa.js 项目基础框架使用教程
+
+## 1. 项目概述
+
+本项目是一个基于 Koa.js 框架构建的后端服务基础框架，提供了完整的 MVC 架构设计、用户认证、文件上传、数据访问层等核心功能。框架采用了模块化设计，各组件职责清晰，便于扩展和维护。
+
+### 主要特性：
+- 完整的用户认证系统（登录、注册、密码重置）
+- 基于 JWT 的安全认证机制
+- RESTful API 路由设计
+- 统一的错误处理和响应格式
+- 强大的数据访问层（支持复杂查询、分页等）
+- Redis 集成（用于验证码、Token 存储）
+- 文件上传下载功能
+- 详细的请求日志记录
+
+## 2. 环境要求
+
+- Node.js 18.x 或更高版本
+- MySQL 数据库
+- Redis 服务
+- npm 或 yarn 包管理器
+
+## 3. 安装与配置
+
+### 3.1 安装依赖
+
+```bash
+npm install
+```
+
+### 3.2 环境配置
+
+在项目根目录修改 `.env` 文件，配置以下环境变量：
+
+```
+# 服务器配置
+PORT=3001 # 端口
+NODE_ENV=development
+
+# JWT配置
+JWT_SECRET=your_jwt_secret_key_here # 密钥
+
+
+# 邮箱配置
+EMAIL_HOST=smtp.example.com   # 邮箱SMTP服务器地址
+EMAIL_PORT=465           # SSL加密端口（推荐）
+EMAIL_USER=your_email@example.com   # 发件人邮箱地址
+EMAIL_PASS=your_email_authorization_code    # 邮箱授权码（非登录密码）
+EMAIL_FROM=your_email@example.com   # 显示的发件人地址
+
+
+# 验证码配置
+VERIFICATION_CODE_EXPIRE=300 # 验证码过期时间 5分钟
+VERIFICATION_SEND_LIMIT_EXPIRE=60  # 重复发送限制时间60秒
+MAX_ATTEMPTS_PER_DAY=10 # 每日最多发送10次
+```
+
+### 3.3 数据库配置
+
+修改 `config/db.js` 文件中的数据库连接信息：
+
+```javascript
+const pool = mysql.createPool({
+  host: "localhost",     // 数据库服务器地址
+  port: 3306,            // 数据库端口
+  user: "root",          // 数据库用户名
+  password: "abc123abc", // 数据库密码
+  database: "demo",      // 数据库名称
+  // 连接池配置
+  waitForConnections: true,
+  connectionLimit: 10,
+  queueLimit: 0,
+});
+```
+
+### 3.4 Redis 配置
+
+修改 `config/redis.js` 文件中的 Redis 连接信息：
+
+```javascript
+const redis = new Redis({
+    host: "localhost", // Redis服务器地址
+    port: 6379,        // Redis端口
+    password: '',      // Redis密码
+    db: 0,             // 数据库索引
+});
+```
+
+### 3.5 启动项目
+
+```bash
+npm start
+```
+
+服务器默认在 `http://localhost:3001` 启动。
+
+## 4. 项目结构
+
+```
+├── app.js                 # 应用入口文件
+├── config/                # 配置文件目录
+│   ├── db.js             # 数据库配置
+│   ├── email.js          # 邮箱配置
+│   ├── index.js          # 主配置文件
+│   └── redis.js          # Redis配置
+├── controllers/           # 控制器目录
+│   ├── AuthController.js # 认证控制器
+│   ├── DownloadController.js # 下载控制器
+│   ├── UploadController.js   # 上传控制器
+│   └── UserController.js     # 用户控制器
+├── middleware/            # 中间件目录
+│   ├── auth.js          # 认证中间件
+│   ├── errorHandler.js  # 错误处理中间件
+│   ├── logger.js        # 日志中间件
+│   ├── notFound.js      # 404处理中间件
+│   └── upload.js        # 上传中间件
+├── models/                # 数据模型目录
+│   ├── Auth.js          # 认证模型
+│   ├── BaseDAO.js       # 基础数据访问对象
+│   └── User.js          # 用户模型
+├── routes/                # 路由目录
+│   ├── auth.js          # 认证路由
+│   ├── download.js      # 下载路由
+│   ├── index.js         # 路由管理器
+│   ├── upload.js        # 上传路由
+│   └── user.js          # 用户路由
+├── services/              # 服务层目录
+│   ├── AuthService.js   # 认证服务
+│   ├── CodeRedisService.js # 验证码Redis服务
+│   ├── DownloadService.js  # 下载服务
+│   ├── EmailService.js     # 邮件服务
+│   ├── JwtTokenService.js  # JWT Token服务
+│   ├── PasswordService.js  # 密码服务
+│   ├── TokenRedisService.js # Token Redis服务
+│   └── UserService.js       # 用户服务
+├── storage/               # 存储目录
+│   └── uploads/           # 上传文件目录
+├── utils/                 # 工具类目录
+│   ├── crypto.js         # 加密工具
+│   ├── passwordValidator.js # 密码验证工具
+│   ├── prototype/        # 原型扩展目录
+│   └── response.js       # 响应工具
+└── public/                # 静态资源目录
+```
+
+## 5. 核心功能模块
+
+### 5.1 路由系统
+
+#### 路由注册机制
+
+项目使用自动路由注册机制，只需在 `routes` 目录下创建路由文件，系统会自动加载并注册这些路由。
+
+#### 创建新路由
+
+在 `routes` 目录下创建新的路由文件，例如 `product.js`：
+
+```javascript
+const productController = require('../controllers/ProductController');
+const Router = require('@koa/router');
+const router = new Router({
+    prefix: '/product'
+});
+
+// 获取产品列表
+router.get('/', productController.list);
+// 获取单个产品
+router.get('/:id', productController.detail);
+// 创建产品
+router.post('/', productController.create);
+// 更新产品
+router.put('/:id', productController.update);
+// 删除产品
+router.delete('/:id', productController.delete);
+
+module.exports = router;
+```
+
+### 5.2 中间件系统
+
+#### 核心中间件
+
+1. **错误处理中间件**：统一捕获并处理应用中的错误
+2. **日志中间件**：记录请求信息、响应时间、状态码等
+3. **认证中间件**：基于 JWT 的认证，支持路由白名单
+4. **404 中间件**：处理不存在的路由请求
+
+#### 自定义中间件
+
+在 `middleware` 目录下创建自定义中间件文件，例如 `validation.js`：
+
+```javascript
+/**
+ * 请求参数验证中间件
+ */
+const validateParams = (schema) => {
+  return async (ctx, next) => {
+    try {
+      // 这里可以使用如 Joi、Yup 等验证库
+      // 验证通过则继续
+      await next();
+    } catch (error) {
+      ctx.status = 400;
+      ctx.body = {
+        code: 400,
+        message: error.message || '参数验证失败'
+      };
+    }
+  };
+};
+
+module.exports = validateParams;
+```
+
+### 5.3 验证码系统
+
+验证码系统用于用户注册、密码重置等场景，确保操作的安全性和防止恶意攻击。本系统通过邮箱发送验证码，并使用Redis进行验证码存储和频率限制管理。
+
+#### 验证码使用场景
+
+- **用户注册**：新用户注册时需要验证邮箱的真实性
+- **密码重置**：用户忘记密码时通过邮箱验证码进行身份验证
+
+#### 验证码类型
+
+- `register`：用于用户注册场景
+- `resetPassword`：用于密码重置场景
+
+#### 如何使用验证码系统
+
+##### 1. 发送验证码
+
+**步骤说明**：
+
+1. 调用发送验证码接口 `/api/auth/verify-code`
+2. 系统会自动执行以下操作：
+   - 验证邮箱格式是否正确
+   - 检查邮箱是否已注册（注册场景）
+   - 验证发送频率限制（60秒内只能发送一次）
+   - 验证每日发送次数限制（每邮箱每日最多10次）
+   - 生成4位数字验证码
+   - 发送验证码邮件
+   - 存储验证码到Redis（有效期5分钟）
+
+**使用示例**：
+
+```javascript
+// 前端调用示例
+const response = await fetch('/api/auth/verify-code', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    email: 'user@example.com',
+    type: 'register'  // 或 'resetPassword'
+  })
+});
+const result = await response.json();
+// {"code": 200, "message": "验证码发送成功", "data": true}
+```
+
+##### 2. 验证验证码
+
+**步骤说明**：
+
+1. 在用户注册或重置密码接口中传递验证码
+2. 系统会自动执行以下操作：
+   - 从Redis获取存储的验证码
+   - 验证验证码是否有效且未过期
+   - 验证用户输入的验证码是否匹配
+   - 验证成功后自动清除验证码（防止重复使用）
+
+**使用示例**：
+
+```javascript
+// 注册时验证验证码
+const registerResponse = await fetch('/api/auth/register', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    account: 'newuser',
+    password: 'StrongPass123',
+    email: 'user@example.com',
+    code: '1234'  // 用户收到的验证码
+  })
+});
+```
+
+#### 验证码系统的安全特性
+
+1. **有效期限制**：验证码默认有效期为5分钟，通过环境变量 `VERIFICATION_CODE_EXPIRE` 配置
+2. **发送频率限制**：60秒内每个邮箱只能发送一次验证码，通过环境变量 `VERIFICATION_SEND_LIMIT_EXPIRE` 配置
+3. **每日次数限制**：每个邮箱每日最多发送10次验证码，通过环境变量 `MAX_ATTEMPTS_PER_DAY` 配置
+4. **邮箱格式验证**：系统自动验证邮箱格式的合法性
+5. **验证码一次性使用**：验证成功后自动删除验证码，防止重复使用
+6. **安全的Redis存储**：验证码以特定格式存储在Redis中，使用合理的键名前缀
+
+#### 常见错误处理
+
+使用验证码系统时，可能遇到的常见错误：
+
+- 邮箱格式不正确
+- 邮箱已被注册（注册场景）
+- 60秒内已发送验证码
+- 今日发送验证码已达上限
+- 验证码无效或已过期
+- 验证码错误
+
+系统会返回相应的错误信息，前端可以根据返回的错误信息给用户友好的提示。
+### 5.4 数据访问层
+
+#### BaseDAO 类
+
+项目提供了强大的 `BaseDAO` 类，封装了常见的数据库操作：
+
+- 增删改查
+- 分页查询
+- 条件查询
+- 高级搜索
+
+#### 创建新的 DAO
+
+```javascript
+const BaseDAO = require('./BaseDAO');
+
+class ProductDAO extends BaseDAO {
+  constructor() {
+    super('products'); // 表名
+  }
+  
+  // 可以添加自定义方法
+  async findByCategory(categoryId) {
+    return await this.findAll({ category_id: categoryId });
+  }
+}
+
+module.exports = new ProductDAO();
+```
+
+#### 使用 DAO 示例
+
+```javascript
+const productDAO = require('../models/ProductDAO');
+
+// 查询所有产品
+const products = await productDAO.findAll();
+
+// 条件查询
+const activeProducts = await productDAO.findAll({ status: 'active' });
+
+// 分页查询
+const pagination = await productDAO.paginate(page, pageSize, conditions);
+
+// 插入数据
+const newProduct = await productDAO.create(productData);
+
+// 更新数据
+await productDAO.update(productId, updateData);
+
+// 删除数据
+await productDAO.delete(productId);
+```
+
+#### BaseDAO 条件查询详细用法
+
+BaseDAO 提供了丰富的条件查询功能，支持以下查询方式：
+
+##### 1. 普通等值查询
+
+```javascript
+// 查询名称等于 '张三' 的用户
+const user = await userDAO.findOne({ name: '张三' });
+
+// 查询状态为 'active' 的产品
+const activeProducts = await productDAO.findAll({ status: 'active' });
+```
+
+##### 2. 模糊查询（$like_）
+
+```javascript
+// 查询用户名包含 '张' 的用户
+const users = await userDAO.findAll({ $like_name: '张' });
+
+// 查询产品描述包含 '新品' 的产品
+const newProducts = await productDAO.findAll({ $like_description: '新品' });
+```
+
+##### 3. 大于等于查询（$gte_）
+
+```javascript
+// 查询价格大于等于 100 的产品
+const expensiveProducts = await productDAO.findAll({ $gte_price: 100 });
+
+// 查询创建时间大于等于 2024-01-01 的订单
+const orders = await orderDAO.findAll({ $gte_created_at: '2024-01-01' });
+```
+
+##### 4. 小于等于查询（$lte_）
+
+```javascript
+// 查询价格小于等于 500 的产品
+const affordableProducts = await productDAO.findAll({ $lte_price: 500 });
+
+// 查询创建时间小于等于 2024-12-31 的订单
+const orders = await orderDAO.findAll({ $lte_created_at: '2024-12-31' });
+```
+
+##### 5. 范围查询（$between_）
+
+```javascript
+// 查询价格在 100-500 之间的产品
+const products = await productDAO.findAll({ $between_price: [100, 500] });
+
+// 查询创建时间在 2024-01-01 到 2024-12-31 之间的订单
+const orders = await orderDAO.findAll({ 
+  $between_created_at: ['2024-01-01', '2024-12-31'] 
+});
+```
+
+##### 6. IN 查询（$in_）
+
+```javascript
+// 查询状态为 'active' 或 'pending' 的产品
+const products = await productDAO.findAll({ 
+  $in_status: ['active', 'pending'] 
+});
+
+// 查询指定 ID 的用户列表
+const users = await userDAO.findAll({ 
+  $in_id: [1, 2, 3, 4, 5] 
+});
+```
+
+##### 7. 组合条件查询
+
+```javascript
+// 组合多种条件查询
+const products = await productDAO.findAll({
+  category_id: 1,
+  $gte_price: 100,
+  $lte_price: 500,
+  $in_status: ['active', 'pending']
+});
+```
+
+##### 8. 条件查询配合排序和分页
+
+```javascript
+// 条件查询并排序
+const products = await productDAO.findAll(
+  { category_id: 1 },
+  { orderBy: 'price', orderDirection: 'desc' }
+);
+
+// 条件查询并分页
+const products = await productDAO.findAll(
+  { status: 'active' },
+  { limit: 10, offset: 20 }
+);
+
+// 完整的分页查询（推荐使用 paginate 方法）
+const result = await productDAO.paginate(
+  1,  // 页码
+  10, // 每页数量
+  { category_id: 1 }, // 查询条件
+  { orderBy: 'created_at', orderDirection: 'desc' } // 排序选项
+);
+// result 结构: { list: [...], pagination: { page, pageSize, total, totalPages, hasNext, hasPrev } }
+```
+
+##### 9. 高级搜索方法
+
+BaseDAO 还提供了 `advancedSearch` 方法，支持更复杂的搜索场景：
+
+```javascript
+const searchConfig = {
+  keyword: '张三', // 搜索关键词
+  keywordFields: ['name', 'email', 'phone'], // 搜索的字段
+  conditions: { status: 'active' }, // 基础条件
+  dateRangeField: 'created_at', // 时间范围字段
+  startDate: '2024-01-01', // 开始时间
+  endDate: '2024-12-31', // 结束时间
+  options: { orderBy: 'created_at', orderDirection: 'desc' } // 排序选项
+};
+
+const users = await userDAO.advancedSearch(searchConfig);
+```
+
+### 5.5 控制器层
+
+控制器负责处理 HTTP 请求，调用服务层进行业务逻辑处理，并返回响应。
+
+#### 创建控制器
+
+```javascript
+const ProductService = require('../services/ProductService');
+const { success, error } = require('../utils/response');
+
+class ProductController {
+  // 获取产品列表
+  async list(ctx) {
+    const { page = 1, pageSize = 10 } = ctx.query;
+    const result = await ProductService.getProducts(page, pageSize);
+    success(ctx, result, '获取产品列表成功');
+  }
+  
+  // 获取单个产品
+  async detail(ctx) {
+    const { id } = ctx.params;
+    const product = await ProductService.getProductById(id);
+    if (product) {
+      success(ctx, product, '获取产品详情成功');
+    } else {
+      error(ctx, '产品不存在', 404);
+    }
+  }
+  
+  // 创建产品
+  async create(ctx) {
+    const result = await ProductService.createProduct(ctx.request.body);
+    success(ctx, result, '创建产品成功');
+  }
+}
+
+module.exports = new ProductController();
+```
+
+### 5.6 服务层
+
+服务层封装业务逻辑，协调多个 DAO 的操作。
+
+#### 创建服务
+
+```javascript
+const productDAO = require('../models/ProductDAO');
+const { error } = require('../utils/response');
+
+class ProductService {
+  // 获取产品列表（带分页）
+  async getProducts(page, pageSize) {
+    return await productDAO.paginate(page, pageSize);
+  }
+  
+  // 根据ID获取产品
+  async getProductById(id) {
+    return await productDAO.findById(id);
+  }
+  
+  // 创建产品
+  async createProduct(productData) {
+    // 数据验证
+    if (!productData.name) {
+      throw new Error('产品名称不能为空');
+    }
+    
+    // 业务逻辑处理
+    // ...
+    
+    // 调用DAO进行数据操作
+    return await productDAO.create(productData);
+  }
+}
+
+module.exports = new ProductService();
+```
+
+### 5.7 认证系统
+
+#### JWT 认证流程
+
+1. 用户登录获取 JWT Token
+2. 客户端在请求头中携带 Token
+3. 服务端验证 Token 的有效性
+4. 验证通过则允许访问受保护的资源
+
+#### 配置白名单
+
+在 `config/index.js` 中配置不需要认证的路由：
+
+```javascript
+jwt: {
+  secret: process.env.JWT_SECRET,
+  expiresIn: 24 * 60 * 60 * 7, // 7天
+  pathWhiteList: [
+    /^\/static\/.*/,        // 静态资源
+    '/api/auth/login',       // 登录接口
+    '/api/auth/register',    // 注册接口
+    '/api/auth/verify-code', // 发送验证码接口
+    // 其他不需要认证的路由
+  ],
+},
+```
+
+## 6. 使用示例
+
+### 6.1 发送验证码
+
+**请求**：
+```
+POST /api/auth/verify-code
+Content-Type: application/json
+
+{
+  "email": "test@example.com",
+  "type": "register"  // 可选值: register(注册), resetPassword(重置密码)
+}
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "message": "验证码发送成功",
+  "data": true
+}
+```
+
+**验证码限制说明**：
+- 验证码有效期为5分钟
+- 每个邮箱60秒内只能发送一次验证码
+- 每个邮箱每日最多发送10次验证码
+
+### 6.2 用户注册
+
+**请求**：
+```
+POST /api/auth/register
+Content-Type: application/json
+
+{
+  "account": "testuser",
+  "password": "Test123456",
+  "email": "test@example.com",
+  "code": "123456"
+}
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "message": "注册成功",
+  "data": { "id": 1 }
+}
+```
+
+### 6.3 用户登录
+
+**请求**：
+```
+POST /api/auth/login
+Content-Type: application/json
+
+{
+  "account": "testuser",
+  "password": "Test123456"
+}
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "message": "登录成功",
+  "data": {
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "userId": 1
+  }
+}
+```
+
+### 6.4 用户退出登录
+
+**请求**：
+```
+POST /api/auth/logout
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "message": "退出登录成功"
+}
+```
+
+### 6.5 用户详情
+
+**请求**：
+```
+GET /api/user/current
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "id": 1,
+    "account": "testuser",
+    "email": "test@example.com",
+    "created_at": "2023-07-01 00:00:00",
+    "updated_at": "2023-07-01 00:00:00"
+  }
+}
+```
+
+### 6.6 文件上传
+
+#### 单文件上传
+
+**请求**：
+```
+POST /api/upload/single
+Content-Type: multipart/form-data
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+[form-data with file]
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "message": "上传成功",
+  "data": {
+    "url": "/storage/uploads/image/2025/12/16/file123.jpg",
+    "filename": "file123.jpg",
+    "size": 2546
+  }
+}
+```
+
+#### 多文件上传
+
+**请求**：
+```
+POST /api/upload/multiple
+Content-Type: multipart/form-data
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+[form-data with multiple files]
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "message": "上传成功",
+  "data": [
+    {
+      "url": "/storage/uploads/image/2025/12/16/file1.jpg",
+      "filename": "file1.jpg",
+      "size": 2061
+    },
+    {
+      "url": "/storage/uploads/image//2025/12/16/file2.jpg",
+      "filename": "file2.jpg",
+      "size": 7256
+    }
+  ]
+}
+```
+
+### 6.7 接口列表
+
+#### 认证相关接口
+
+| 接口路径 | 方法 | 描述 | 请求参数 | 成功响应 (200 OK) |
+|---------|------|------|---------|-------------------|
+| `/api/auth/login` | `POST` | 用户登录 | `{"account": "用户名", "password": "密码"}` | `{"code": 200, "message": "登录成功", "data": {"token": "JWT令牌", "user": {"id": 1, "account": "用户名", "email": "邮箱", "created_at": "2023-07-01 00:00:00", "updated_at": "2023-07-01 00:00:00"}}}` |
+| `/api/auth/register` | `POST` | 用户注册 | `{"account": "用户名", "password": "密码", "email": "邮箱", "code": "验证码"}` | `{"code": 200, "message": "注册成功", "data": {"id": 1, "account": "用户名", "email": "邮箱", "created_at": "2023-07-01 00:00:00", "updated_at": "2023-07-01 00:00:00"}}` |
+| `/api/auth/verify-code` | `POST` | 发送验证码 | `{"email": "邮箱", "type": "验证码类型（register/resetPassword）"}` | `{"code": 200, "message": "验证码发送成功", "data": true}` |
+| `/api/auth/logout` | `POST` | 用户退出登录 | 无（需要JWT认证） | `{"code": 200, "message": "退出登录成功"}` |
+| `/api/auth/change-password` | `POST` | 修改密码 | `{"oldPassword": "旧密码", "newPassword": "新密码"}` | `{"code": 200, "message": "密码修改成功"}` |
+| `/api/auth/reset-password` | `POST` | 重置密码 | `{"email": "邮箱", "code": "验证码", "newPassword": "新密码"}` | `{"code": 200, "message": "密码重置成功"}` |
+
+#### 用户相关接口
+
+| 接口路径 | 方法 | 描述 | 请求参数 | 成功响应 (200 OK) |
+|---------|------|------|---------|-------------------|
+| `/api/user/current` | `GET` | 获取当前用户信息 | 无（需要JWT认证） | `{"code": 200, "message": "获取成功", "data": {"id": 1, "account": "用户名", "email": "邮箱", "created_at": "2023-07-01 00:00:00", "updated_at": "2023-07-01 00:00:00"}}` |
+| `/api/user/list` | `GET` | 获取用户列表 | 查询参数：`email`（邮箱）, `startTime`（开始时间）, `endTime`（结束时间）, `page`（页码）, `pageSize`（每页数量）, `all`（是否获取全部列表，默认为false） | 当all=true时：`{"code": 200, "message": "success", "data": [{"id": 15, "account": "admin", "updated_at": "2025-12-15 16:28:58", "email": "xxx@qq.com", "created_at": "2025-12-15 15:38:12"}]}`<br>当all=false时：`{"code": 200, "message": "success", "data": {"list": [{"id": 15, "account": "admin", "updated_at": "2025-12-15 16:28:58", "email": "xxx@qq.com", "created_at": "2025-12-15 15:38:12"}], "pagination": {"page": 2, "pageSize": 1, "total": 4, "totalPages": 4, "hasNext": true, "hasPrev": true}}}` |
+| `/api/user` | `POST` | 创建新用户 | `{"account": "用户名", "password": "密码", "email": "邮箱"}` | `{"code": 200, "message": "创建成功", "data": {"id": 1, "account": "用户名", "email": "邮箱", "created_at": "2023-07-01 00:00:00", "updated_at": "2023-07-01 00:00:00"}}` |
+| `/api/user/:id` | `PUT` | 更新用户信息 | `{"account": "用户名", "email": "邮箱"}` | `{"code": 200, "message": "success", "data": true}` |
+| `/api/user/:id` | `DELETE` | 删除用户 | 无（路径参数id） | `{"code": 200, "message": "删除成功"}` |
+| `/api/user/:id` | `GET` | 获取指定用户信息 | 无（路径参数id） | `{"code": 200, "message": "获取成功", "data": {"id": 1, "account": "用户名", "email": "邮箱", "created_at": "2023-07-01 00:00:00", "updated_at": "2023-07-01 00:00:00"}}` |
+
+#### 文件上传相关接口
+
+| 接口路径 | 方法 | 描述 | 请求参数 | 成功响应 (200 OK) |
+|---------|------|------|---------|-------------------|
+| `/api/upload/single` | `POST` | 单文件上传 | FormData: `file`（文件字段） | `{"code": 200, "message": "上传成功", "data": {"url": "/storage/uploads/image/2025/12/16/file.jpg", "filename": "file.jpg", "size":2650}}` |
+| `/api/upload/multiple` | `POST` | 多文件上传 | FormData: `files`（多文件字段） | `{"code": 200, "message": "上传成功", "data": [{"url": "...", "filename": "...", "size": "..."}]}` |
+
+#### 文件下载相关接口
+
+| 接口路径 | 方法 | 描述 | 请求参数 | 成功响应 (200 OK) |
+|---------|------|------|---------|-------------------|
+| `/api/download` | `GET` | 文件下载 | 查询参数：`url`（文件相对路径） | 文件流响应（Content-Type: 对应的文件MIME类型） |
+
+## 7. 最佳实践
+
+### 7.1 代码组织
+
+- 遵循 MVC 架构，将代码分层组织
+- 控制器只负责请求处理和响应返回
+- 业务逻辑放在服务层
+- 数据访问操作通过 DAO 进行
+
+### 7.2 错误处理
+
+- 使用统一的错误处理中间件
+- 业务逻辑错误通过抛出异常处理
+- 返回统一格式的错误响应
+- 记录关键错误日志
+
+### 7.3 安全性
+
+- 敏感数据加密存储（如密码使用 argon2 加密）
+- 接口访问使用 JWT 认证
+- 输入参数严格验证
+- 防止 SQL 注入（使用参数化查询）
+
+### 7.4 性能优化
+
+- 使用数据库连接池
+- 合理使用 Redis 缓存
+- 分页查询避免一次性加载大量数据
+- 使用异步操作提高并发性能
+
+## 8. 常见问题
+
+### 8.1 如何添加新的 API 接口？
+
+1. 在 `controllers` 目录下创建对应的控制器
+2. 在 `services` 目录下创建对应的服务
+3. 在 `models` 目录下创建对应的 DAO
+4. 在 `routes` 目录下创建对应的路由文件
+
+### 8.2 如何扩展中间件？
+
+在 `middleware` 目录下创建新的中间件文件，并在 `app.js` 中注册使用。
+
+### 8.3 如何处理文件上传？
+
+使用已有的 `UploadController` 和 `upload.js` 中间件，或根据需要扩展。
+
+### 8.4 如何进行数据库事务？
+
+在 DAO 层可以通过获取连接并手动控制事务：
+
+```javascript
+async transactionExample() {
+  const connection = await this.pool.getConnection();
+  try {
+    await connection.beginTransaction();
+    // 执行多个操作
+    await connection.execute(sql1, params1);
+    await connection.execute(sql2, params2);
+    await connection.commit();
+    return true;
+  } catch (error) {
+    await connection.rollback();
+    throw error;
+  } finally {
+    connection.release();
+  }
+}
+```
+
+## 9. 总结
+
+本框架提供了一个完整的 Koa.js 后端服务开发基础，包含了用户认证、数据访问、文件上传等常用功能。通过模块化设计和清晰的分层架构，使得项目易于维护和扩展。开发者可以基于此框架快速构建自己的后端服务，专注于业务逻辑的实现。