create-pixle-koa-template 1.0.0

package/bin/create-app.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+async function createProject() {
+  try {
+    // 获取项目名称
+    const projectName = process.argv[2];
+    
+    if (!projectName) {
+      console.log('\x1b[36m%s\x1b[0m', '✨ Create Pixle Koa Template ✨');
+      console.log('\x1b[90m%s\x1b[0m', 'Usage: npm create pixle-koa-template <project-name>\n');
+      console.log('\x1b[31m%s\x1b[0m', 'Please provide a project name.');
+      console.log('Example: npm create pixle-koa-template my-project');
+      process.exit(1);
+    }
+
+    // 验证项目名称
+    if (!/^[a-z0-9-]+$/.test(projectName)) {
+      console.log('\x1b[31m%s\x1b[0m', 
+        'Project name can only contain lowercase letters, numbers, and hyphens');
+      process.exit(1);
+    }
+
+    const targetPath = path.join(process.cwd(), projectName);
+
+    // 检查目录是否存在
+    if (fs.existsSync(targetPath)) {
+      console.log('\x1b[31m%s\x1b[0m', `Directory "${projectName}" already exists!`);
+      process.exit(1);
+    }
+
+    console.log('\x1b[34m%s\x1b[0m', `📦 Creating project: ${projectName}`);
+
+    // 创建项目目录
+    fs.mkdirSync(targetPath, { recursive: true });
+
+    // 复制模板文件
+    const templatePath = path.join(__dirname, '../template');
+    copyDirSync(templatePath, targetPath, projectName);
+
+    console.log('\x1b[32m%s\x1b[0m', `✅ Project created successfully!`);
+    console.log('\x1b[36m%s\x1b[0m', '\n📋 Next steps:');
+    console.log(`  cd ${projectName}`);
+    console.log('  npm install');
+    console.log('  npm run dev\n');
+
+  } catch (error) {
+    console.error('\x1b[31m%s\x1b[0m', `\n❌ Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// 递归复制目录
+function copyDirSync(src, dest, projectName) {
+  fs.mkdirSync(dest, { recursive: true });
+  
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath, projectName);
+    } else {
+      // 读取文件内容并替换变量
+      let content = fs.readFileSync(srcPath, 'utf8');
+      content = content.replace(/{{project-name}}/g, projectName);
+      fs.writeFileSync(destPath, content, 'utf8');
+    }
+  }
+}
+
+createProject();

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "create-pixle-koa-template",
+  "version": "1.0.0",
+  "description": "Koa template",
+  "bin": {
+    "create-pixle-koa-template": "./bin/create-app.js"
+  },
+  "files": [
+    "bin/",
+    "template/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": ["koa", "template", "pixle" ],
+  "license": "MIT"
+}

package/template/.env

@@ -0,0 +1,20 @@
+# 服务器配置
+PORT=3001 # 端口
+NODE_ENV=development
+
+# JWT配置
+JWT_SECRET=your_jwt_secret_key_here # 密钥
+
+
+# 邮箱配置
+EMAIL_HOST=smtp.qq.com   # QQ邮箱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次

package/template/app.js

@@ -0,0 +1,49 @@
+require("dotenv").config(); // 在最顶部引入并配置
+require("./utils/prototype").loadAndExecutePrototypes(); // 加载并执行所有原型扩展
+require("./config/db.js");//加载数据库配置
+require("./config/redis.js");// 加载Redis配置
+const Koa = require("koa");
+const app = new Koa();
+const errorHandlerMiddleware = require("./middleware/errorHandler.js");
+const loggerMiddleware = require("./middleware/logger.js");
+const authMiddleware = require("./middleware/auth.js");
+const notFoundMiddleware = require("./middleware/notFound.js");
+const bodyParser = require("koa-bodyparser");
+const static = require("koa-static");
+const path = require("path");
+const mount = require("koa-mount");
+const { registerRoutes } = require("./routes");
+const config = require("./config");
+
+
+//错误处理
+app.use(errorHandlerMiddleware);
+// 日志中间件
+app.use(loggerMiddleware);
+app.on("error", (err, ctx) => {
+  console.error("server error", err);
+});
+
+//添加静态资源，前缀/static，静态资源目录为public
+app.use(mount("/static", static(path.join(__dirname, "public"))));
+// 使用 bodyParser 中间件
+app.use(bodyParser());
+
+// JWT 认证中间件（必须放在路由注册之前，确保所有API请求都经过认证）
+app.use(authMiddleware);
+
+// 注册路由
+registerRoutes(app, config.routes.prefix);
+//404中间件
+app.use(notFoundMiddleware);
+
+// 端口号
+const PORT = process.env.PORT || 3000;
+// 启动服务器
+async function startServer() {
+  app.listen(PORT, () => {
+    console.log(`🚀 服务器已启动: http://localhost:${PORT}`);
+  });
+}
+
+startServer();

package/template/config/db.js

@@ -0,0 +1,29 @@
+const mysql = require("mysql2/promise");
+const pool = mysql.createPool({
+  host: "localhost",//数据库服务器地址，默认localhost
+  port: 3306,// 默认端口
+  user: "root",//用户名，默认root
+  password: "1234qwer",//密码
+  database: "demo",//数据库名称
+ // 连接池配置
+ waitForConnections: true,// 没有连接时等待
+ connectionLimit: 10, // 连接池最大连接数
+ queueLimit: 0,    // 等待队列无限制（0表示不限制）
+});
+
+// 测试数据库连接
+async function testConnection() {
+  try {
+    const connection = await pool.getConnection();
+    console.log("数据库连接成功");
+    connection.release();// 释放连接回池
+  } catch (e) {
+    console.log(e, "数据库连接失败");
+  }
+}
+
+//执行连接测试
+testConnection()
+
+module.exports =  pool
+  

package/template/config/email.js

@@ -0,0 +1,30 @@
+// QQ邮箱专用配置
+const QQ_EMAIL_CONFIG = {
+    // QQ邮箱固定配置
+    host: process.env.EMAIL_HOST,
+    port: process.env.EMAIL_PORT,
+    secure: true, // 使用SSL
+    
+    // 认证信息（从环境变量获取）
+    auth: {
+      user: process.env.EMAIL_USER,
+      pass: process.env.EMAIL_PASS
+    },
+    
+    // 连接配置
+    connectionTimeout: 10000, // 10秒连接超时
+    greetingTimeout: 10000,   // 10秒问候超时
+    socketTimeout: 60000,     // 60秒socket超时
+    
+    // TLS配置
+    tls: {
+      rejectUnauthorized: false // 允许自签名证书
+    },
+    
+    // 调试模式
+    debug: process.env.NODE_ENV === 'development',
+    logger: process.env.NODE_ENV === 'development'
+  };
+
+
+  module.exports = QQ_EMAIL_CONFIG;

package/template/config/index.js

@@ -0,0 +1,36 @@
+const path = require("path");
+
+let config = {
+  // 应用配置
+  app: {},
+  //路由配置
+  routes: {
+    prefix: "/api", //路由前缀
+  },
+  // JWT 配置
+  jwt: {
+    secret: process.env.JWT_SECRET, // 64 字节的 Base64 编码密钥，引用utils/crypto.js工具生成
+    expiresIn: 24 * 60 * 60 * 7, // Token 有效期7天
+    //不需要鉴权路由白名单
+    pathWhiteList: [
+      /^\/static\/.*/, //静态资源
+      '/api/auth/login', //登录接口
+      '/api/auth/register', //注册接口
+      '/api/auth/verify-code',//发送验证码
+      '/api/auth/reset-password',//重置密码接口
+    ],
+  },
+  //上传文件配置
+  upload: {
+    // 上传文件目录
+    uploadDir:  {
+      image: path.join(__dirname, "../storage/uploads/image"), //图片上传目录路径
+      file: path.join(__dirname, "../storage/uploads/file"), //文件上传目录路径
+    },
+    // 上传文件大小限制（字节）
+    maxSize: 1024 * 1024 * 20, // 20MB
+    maxCount: 9, //多文件上传，一次最多9个文件
+  },
+};
+
+module.exports = config;

package/template/config/redis.js

@@ -0,0 +1,19 @@
+const Redis = require("ioredis");
+const redis = new Redis({
+    host: "localhost",
+    port: 6379,
+    password: '',
+    db: 0,
+});
+
+// 错误处理
+redis.on('error', (err) => {
+    console.error('Redis error:', err);
+});
+
+// 连接成功
+redis.on('ready', () => {
+  console.log('Redis链接成功');
+})
+
+module.exports = redis;

package/template/controllers/AuthController.js

@@ -0,0 +1,71 @@
+const AuthService = require("../services/AuthService.js");
+const PasswordService = require("../services/PasswordService.js");
+const { success, error } = require("../utils/response.js");
+
+class AuthController {
+  //登录
+  async login(ctx) {
+    let { account, password } = ctx.request.body;
+    let res = await AuthService.login(ctx, account, password);
+    res && success(ctx, res, "登录成功");
+  }
+
+  //退出登录
+  async logout(ctx) {
+    let res = await AuthService.logout(ctx);
+    res && success(ctx, true, "退出登录成功");
+  }
+
+  //注册
+  async register(ctx) {
+    let res = await AuthService.register(ctx, ctx.request.body);
+    res && success(ctx, res, "注册成功");
+  }
+
+  //发送验证码
+  async sendVerificationCode(ctx) {
+    let { email,type } = ctx.request.body;
+    let res = await AuthService.sendVerificationCode(ctx, email,type);
+    res && success(ctx, true, "验证码发送成功");
+  }
+  //修改密码
+  async changePassword(ctx) {
+    let { oldPassword, newPassword } = ctx.request.body;
+    // 验证旧密码是否为空
+    if (!oldPassword) {
+      return error(ctx, "旧密码不能为空", 400);
+    }
+    // 验证新密码是否为空
+    if (!newPassword) {
+      return error(ctx, "新密码不能为空", 400);
+    }
+    if (oldPassword === newPassword) {
+      return error(ctx, "新密码不能与旧密码相同", 400);
+    }
+    let res = await PasswordService.changePassword(
+      ctx,
+      oldPassword,
+      newPassword
+    );
+    res && success(ctx, true, "密码修改成功");
+  }
+
+  //重置密码
+  async resetPassword(ctx) {
+    let { email, code, password } = ctx.request.body;
+    if (!email) {
+      return error(ctx, "邮箱不能为空", 400);
+    }
+    if (!code) {
+      return error(ctx, "验证码不能为空", 400);
+    }
+    if (!password) {
+      return error(ctx, "新密码不能为空", 400);
+    }
+
+    let res = await PasswordService.resetPassword(ctx, email, code, password);
+    res && success(ctx, true, "密码重置成功");
+  }
+}
+
+module.exports = new AuthController();

package/template/controllers/DownloadController.js

@@ -0,0 +1,18 @@
+const { error } = require("../utils/response.js");
+const DownloadService = require("../services/DownloadService.js");
+
+// 下载控制器
+class DownloadController {
+  async download(ctx) {
+    let { url } = ctx.query;
+    if (!url) {
+      return error(ctx, "url不能为空", 400);
+    }
+    let urlArr = url.split("/");
+    if (urlArr.length < 2) {
+      return error(ctx, "url格式错误", 400);
+    }
+    await DownloadService.download(ctx, url);
+  }
+}
+module.exports = new DownloadController();

package/template/controllers/UploadController.js

@@ -0,0 +1,60 @@
+const { success } = require("../utils/response.js");
+// 上传控制器
+class UploadController {
+
+  /**
+   * 单文件上传控制器
+   * @param {Object} ctx - Koa上下文对象，包含请求和响应信息
+   * @returns {Promise<void>} - 无返回值，直接通过ctx返回响应
+   */
+  async single(ctx) {
+      // 从上下文对象中获取上传的单个文件
+      // ctx.file 是由文件上传中间件(如 koa-multer)处理后生成的文件对象
+      const file = ctx.file;
+      
+      // 上传成功，返回处理后的文件信息
+      success(
+          ctx,
+          {
+              filename: file.filename, // 原始文件名
+              // 构建可访问的文件URL路径
+              // 1. 将文件路径按"\\storage\\"分割，获取存储目录后的部分
+              // 2. 将Windows风格的反斜杠(\\)替换为URL标准的正斜杠(/)
+              // 3. 拼接上"/storage/"前缀，形成完整的可访问URL
+              // 示例: /storage/uploads/image/2025/12/16/image_1765852398032_hcjukkjyamu.png
+              url: `/storage/${file.path.split("\\storage\\")[1].replaceAll("\\", "/")}`,
+              size: file.size, // 文件大小，单位为字节(B)
+          },
+          "上传成功" // 响应成功提示信息
+      );
+  }
+
+
+
+  /**
+   * 多文件上传控制器
+   * @param {Object} ctx - Koa上下文对象，包含请求和响应信息
+   * @returns {Promise<void>} - 无返回值，直接通过ctx返回响应
+   */
+  async multiple(ctx) {
+      // 从上下文对象中获取上传的文件列表
+      // ctx.files 是由文件上传中间件(如 koa-multer)处理后生成的文件数组
+      const files = ctx.files;
+      
+      // 处理每个上传的文件，构建返回给客户端的文件信息列表
+      let list = files.map((item) => ({
+          filename: item.filename, // 原始文件名
+          // 构建可访问的文件URL路径
+          // 1. 将文件路径按"\\storage\\"分割，获取存储目录后的部分
+          // 2. 将Windows风格的反斜杠(\\)替换为URL标准的正斜杠(/)
+          // 3. 拼接上"/storage/"前缀，形成完整的可访问URL
+          url: `/storage/${item.path.split("\\storage\\")[1].replaceAll("\\", "/")}`,
+          size: item.size, // 文件大小，单位为字节(B)
+      }));
+      
+      // 上传成功，返回处理后的文件信息列表和成功提示
+      success(ctx, list, "上传成功");
+  }
+}
+
+module.exports = new UploadController();

package/template/controllers/UserController.js

@@ -0,0 +1,90 @@
+const UserService = require("../services/UserService.js");
+const AuthService = require("../services/AuthService.js");
+const { success, error } = require("../utils/response.js");
+
+class UserController {
+  //获取当前用户详情
+  async getCurrentUser(ctx) {
+    // 从JWT令牌解密后的payload中获取用户ID，默认挂载到ctx.state.user
+    let { userId } = ctx.state.user;
+
+    // 检查用户ID是否存在（即用户是否已登录）
+    if (userId) {
+      // 调用用户服务层获取用户详细信息
+      let result = await UserService.getUserById(ctx, userId);
+      // 如果查询成功，返回用户信息
+      result && success(ctx, result);
+    } else {
+      error(ctx, "请登录", 400);
+    }
+  }
+
+  //获取单个用户
+  async getUserById(ctx) {
+    let userId = ctx.params.id;
+
+    // 验证用户ID是否为空
+    if (!userId) {
+      return error(ctx, "用户ID不能为空", 400);
+    }
+
+    // 调用用户服务层获取用户详细信息
+    let result = await UserService.getUserById(ctx, userId);
+    result && success(ctx, result);
+  }
+
+  //添加用户
+  async createUser(ctx) {
+    // 调用认证服务层注册用户，第三个参数false表示不是验证码注册类型来添加用户
+    let result = await AuthService.register(ctx, ctx.request.body, false);
+    
+    // 如果创建成功，返回创建结果
+    result && success(ctx, result);
+  }
+
+  //更新用户
+  async updateUser(ctx) {
+    const { id } = ctx.params;
+    const params = ctx.request.body;
+
+    // 验证用户ID是否为空
+    if (!id) {
+      return error(ctx, "用户ID不能为空", 400);
+    }
+
+    // 验证更新参数是否有效：必须是对象、不能是数组、不能为空对象
+    if (!(params
+      && typeof params === 'object'
+      && !Array.isArray(params)
+      && Object.keys(params).length > 0)) {
+      return error(ctx, "参数不能为空", 400);
+    }
+
+    // 调用用户服务层更新用户信息
+    const result = await UserService.updateUser(ctx, id, params);
+    result && success(ctx, result);
+  }
+
+  //删除用户
+  async deleteUser(ctx) {
+    const { id } = ctx.params;
+    // 验证用户ID是否为空
+    if (!id) {
+      return error(ctx, "用户ID不能为空", 400);
+    }
+     // 调用用户服务层删除用户
+    const result = await UserService.deleteUser(ctx, id);
+    result && success(ctx, result);
+  }
+
+  //获取用户列表
+  async getUserList(ctx) {
+    // 调用用户服务层获取用户列表
+    let result = await UserService.getUserList(ctx);
+    
+    // 如果查询成功，返回用户列表数据
+    result && success(ctx, result);
+  } 
+}
+
+module.exports = new UserController();

package/template/middleware/auth.js

@@ -0,0 +1,91 @@
+const koajwt = require("koa-jwt");
+const config = require("../config");
+const { getToken } = require("../services/TokenRedisService.js");
+
+/**
+ * JWT 认证中间件（token校验）
+ * 只对已匹配的路由进行认证，未匹配的路由返回404
+ */
+const authMiddleware = async (ctx, next) => {
+  // 使用从routes/index.js自动收集的路由信息
+  const registeredRoutes = ctx.app.context.registeredRoutes || [];
+  let pathExists = false;
+  
+  // 检查请求路径是否匹配任何已注册的路由
+  for (const route of registeredRoutes) {
+    try {
+      // 获取路由路径，用于后续分析
+      const routePath = route.path;
+      
+      // 对于静态路由，直接比较路径
+      if (routePath === ctx.path) {
+        pathExists = true;
+        break;
+      }
+      
+      // 对于动态路由（包含:param格式的参数），我们需要特殊处理
+      if (routePath.includes(':')) {
+        // 分割路径部分进行比较
+        const requestParts = ctx.path.split('/').filter(v=>!!v);
+        const routeParts = routePath.split('/').filter(v=>!!v);
+        
+        // 如果路径部分数量相同，可能是一个动态路由匹配
+        if (requestParts.length === routeParts.length) {
+          let isMatch = true;
+          
+          // 逐个比较路径部分，跳过参数部分
+          for (let i = 0; i < routeParts.length; i++) {
+            // 如果路由部分不是参数格式（不以:开头），则必须完全匹配
+            if (!routeParts[i].startsWith(':') && routeParts[i] !== requestParts[i]) {
+              isMatch = false;
+              break;
+            }
+          }
+          
+          if (isMatch) {
+            pathExists = true;
+            break;
+          }
+        }
+      }
+    } catch (e) {
+      // 忽略可能的错误
+    }
+  }
+  
+  // 如果路径不存在，直接继续，最终返回404
+  if (!pathExists) {
+    await next();
+    return;
+  }
+  
+  // 使用koajwt进行认证
+  const jwtAuth = koajwt({
+    secret: config.jwt.secret,
+    //是否撤销，返回true token失效
+    isRevoked: async (ctx, payload, token) => {
+      try {
+        if (!payload?.userId) {
+          return true; //格式错误，视为已撤销
+        }
+        // 根据用户id从白名单中获取token
+        const storedToken = await getToken(payload.userId);
+        //存在白名单中而且和 redis 中token一致，则视为有效
+        if (storedToken && storedToken === token) {
+          return false;
+        }
+        return true;
+      } catch (error) {
+        return true; // 出错时保守处理，视为已撤销
+      }
+    },
+  }).unless({
+    //白名单
+    path: config.jwt.pathWhiteList,
+  });
+  
+  // 执行JWT认证
+  return jwtAuth(ctx, next);
+};
+
+module.exports = authMiddleware;

package/template/middleware/errorHandler.js

@@ -0,0 +1,17 @@
+/**
+ * 错误处理中间件
+ */
+const errorHandlerMiddleware = async (ctx, next) => {
+  try {
+    await next();
+  } catch (err) {
+    ctx.status = err?.status ?? 500;
+    ctx.body = {
+      code: ctx.status,
+      message: ctx.status == 500 ? "服务器内部错误" : err?.message ?? "error",
+    };
+    ctx.app.emit("error", err, ctx);
+  }
+};
+
+module.exports = errorHandlerMiddleware;

package/template/middleware/logger.js

@@ -0,0 +1,41 @@
+/**
+ * 日志中间件
+ * 记录请求和响应的信息，包括URL、方法、状态码、响应时间等
+ */
+
+// 颜色配置
+const colors = {
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+};
+
+//根据状态码获取颜色
+const getStatusColor = (status) => {
+  if (status >= 500) return colors.red; // 服务器错误 - 红色
+  if (status >= 400) return colors.yellow; // 客户端错误 - 黄色
+  if (status >= 300) return colors.cyan; // 重定向 - 青色
+  if (status >= 200) return colors.green; // 成功 - 绿色
+  return colors.white; // 其他 - 白色
+};
+
+//日志中间件
+const loggerMiddleware = async (ctx, next) => {
+  const start = Date.now();
+  const { method, url, ip } = ctx;
+
+  await next();
+  const responseTime = Date.now() - start;
+  const status = ctx.status;
+  const timestamp = new Date().format("yyyy-MM-dd HH:mm:ss");
+  // 根据状态码设置日志颜色
+  let logColor = getStatusColor(status);
+  // 打印日志
+  console.log(
+    `${logColor}[${timestamp}] ${method} ${url} - ${status} - ${responseTime}ms - ${ip}`
+  );
+};
+
+module.exports = loggerMiddleware;