create-pixle-koa-template 1.0.0

package/template/services/DownloadService.js

@@ -0,0 +1,54 @@
+/**
+ * 下载服务
+ */
+const {  error } = require("../utils/response.js");
+const send = require("koa-send");
+const path = require("path");
+
+
+class DownloadService {
+  /**
+   * 文件下载服务
+   * @param {Object} ctx - Koa上下文对象，包含请求和响应信息
+   * @param {string} url - 要下载的文件相对路径（如：storage/uploads/image/2025/12/16/file.png）
+   * @returns {Promise<void>} - 无返回值，直接通过ctx返回文件流或错误响应
+   */
+  async download(ctx, url) {
+      try {
+          // 将URL路径按"/"分割成数组，用于解析目录和文件名
+          let urlArr = url.split("/");
+          
+          // 获取数组最后一个元素作为文件名
+          const fileName = urlArr[urlArr.length - 1];
+          
+          // 获取除了最后一个元素外的所有部分，重新拼接成目录路径
+          const fileDir = urlArr.slice(0, urlArr.length - 1).join("/");
+          
+          // 构建完整的本地文件目录路径
+          // __dirname 表示当前文件所在目录
+          // 向上跳转一级（../）后拼接上文件目录
+          const dirPath = path.join(__dirname, `../${fileDir}`);
+          
+          // 调用 koa-send 中间件实现文件下载
+          let result = await send(ctx, fileName, {
+              root: dirPath, // 指定文件所在的根目录
+              setHeaders: (res) => {
+                  // 设置 Content-Disposition 响应头为 attachment，强制浏览器下载文件
+                  // encodeURIComponent 确保文件名中的特殊字符能正确处理
+                  res.setHeader(
+                      "Content-Disposition",
+                      `attachment; filename="${encodeURIComponent(fileName)}"`
+                  );
+              },
+          });
+          
+      } catch (err) {
+          // 捕获并处理下载过程中的错误
+          // 如果是文件不存在等404错误，返回404状态码
+          // 其他错误返回相应的错误状态码
+          error(ctx, "文件不存在", err.status || 404);
+      }
+  }
+}
+
+module.exports = new DownloadService();

package/template/services/EmailService.js

@@ -0,0 +1,245 @@
+/**
+ * 验证码发送工具
+ */
+
+const nodemailer = require("nodemailer");
+// 引入QQ邮箱配置
+const QQ_EMAIL_CONFIG = require("../config/email");
+
+// 创建传输器
+const transporter = nodemailer.createTransport(QQ_EMAIL_CONFIG);
+
+/**
+ * 生成4位验证码
+ * @returns 验证码
+ */
+const generateVerificationCode = () => {
+  let code = "";
+  for (let i = 0; i < 4; i++) {
+    code += Math.floor(Math.random() * 10); // 0-9
+  }
+  return code;
+};
+
+/**
+ * 获取邮箱验证码主题
+ * @param {*} type ：验证码类型: register:注册, resetPassword:重置密码
+ * @returns 验证码主题
+ */
+const getEmailSubject = (type = "register") => {
+  let subjectOptions = [];
+  switch (type) {
+    case "register":
+      subjectOptions = ["注册", "注册账号"];
+      break;
+    case "resetPassword":
+      subjectOptions = ["重置密码", "重置密码"];
+      break;
+    default:
+      subjectOptions = ["注册", "注册账号"];
+  }
+  return subjectOptions;
+};
+
+/**
+ * 发送验证码邮件
+ * @param {*} email 收件人邮箱
+ * @param {*} code  验证码
+ * @param {*} type ：验证码类型: register:注册, resetPassword:重置密码
+ * @returns
+ */
+const sendVerificationCode = async (email, code, type = "register") => {
+  try {
+    // 验证收件人邮箱格式
+    if (!isValidEmail(email)) {
+      throw new Error("收件人邮箱格式不正确，请输入正确的邮箱");
+    }
+
+    const subjectOptions = getEmailSubject(type);
+
+
+    const mailOptions = {
+      from: {
+        name: "验证码服务", // 发件人名称
+        address: QQ_EMAIL_CONFIG.auth.user,
+      },
+      to: email,
+      subject: `【重要】${subjectOptions[0]}验证码`,
+      text: `您的${subjectOptions[0]}验证码是：${code}，验证码5分钟内有效。`,
+      html: generateQQEmailTemplate(code,subjectOptions),
+    };
+
+    // 发送邮件
+    const info = await transporter.sendMail(mailOptions);
+
+    return {
+      success: true,
+      message: "验证码发送成功",
+      messageId: info.messageId,
+      to: email,
+    };
+  } catch (error) {
+    // console.error(" 发送验证码失败:", error.message);
+    // 提供友好的错误提示
+    let userMessage = "验证码发送失败";
+    if (error.code === "EAUTH") {
+      userMessage = "邮箱认证失败，请检查授权码是否正确";
+    } else if (error.code === "ECONNECTION") {
+      userMessage = "连接QQ邮箱服务器失败，请检查网络";
+    } else if (error.responseCode === 550) {
+      userMessage = "收件人邮箱地址不存在或无法接收邮件";
+    }
+
+    throw new Error(userMessage);
+  }
+};
+
+// 验证是否为邮箱
+const isValidEmail = (email) => {
+  const reg = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+  return reg.test(email);
+};
+
+// 生成QQ邮箱专用HTML模板
+const generateQQEmailTemplate = (code,subjectOptions) => {
+  return `
+      <!DOCTYPE html>
+      <html lang="zh-CN">
+      <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>${subjectOptions[0]}验证码</title>
+        <style>
+          body {
+            font-family: 'Microsoft YaHei', Arial, sans-serif;
+            line-height: 1.6;
+            color: #333;
+            margin: 0;
+            padding: 20px;
+            background-color: #f5f5f5;
+          }
+          .email-container {
+            max-width: 600px;
+            margin: 0 auto;
+            background-color: white;
+            border-radius: 8px;
+            overflow: hidden;
+            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+          }
+          .header {
+            background: linear-gradient(135deg, #12c2e9, #c471ed, #f64f59);
+            color: white;
+            padding: 30px 20px;
+            text-align: center;
+          }
+          .header h1 {
+            margin: 0;
+            font-size: 24px;
+          }
+          .content {
+            padding: 30px;
+          }
+          .code-container {
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            padding: 25px;
+            text-align: center;
+            border-radius: 8px;
+            margin: 30px 0;
+            box-shadow: 0 4px 15px rgba(102, 126, 234, 0.3);
+          }
+          .code {
+            font-size: 42px;
+            font-weight: bold;
+            letter-spacing: 8px;
+            text-shadow: 2px 2px 4px rgba(0,0,0,0.2);
+            font-family: 'Courier New', monospace;
+          }
+          .tips {
+            background-color: #f8f9fa;
+            border-left: 4px solid #12c2e9;
+            padding: 15px;
+            margin: 20px 0;
+            border-radius: 4px;
+          }
+          .footer {
+            text-align: center;
+            padding: 20px;
+            color: #666;
+            font-size: 12px;
+            border-top: 1px solid #eee;
+            background-color: #f9f9f9;
+          }
+          .warning {
+            color: #ff6b6b;
+            font-weight: bold;
+            background-color: #ffeaa7;
+            padding: 10px;
+            border-radius: 4px;
+            margin: 15px 0;
+          }
+          .qq-logo {
+            width: 60px;
+            height: 60px;
+            background: linear-gradient(135deg, #12c2e9, #c471ed);
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            margin: 0 auto 20px;
+            color: white;
+            font-size: 24px;
+            font-weight: bold;
+          }
+        </style>
+      </head>
+      <body>
+        <div class="email-container">
+          <div class="header">
+            <div class="qq-logo">Q</div>
+            <h1>邮箱验证码</h1>
+            <p>邮箱安全验证服务</p>
+          </div>
+          
+          <div class="content">
+            <p>尊敬的用户 ，您好！</p>
+            <p>您正在申请${subjectOptions[1]}，请使用以下验证码完成验证：</p>
+            
+            <div class="code-container">
+              <div class="code">${code}</div>
+            </div>
+            
+            <div class="warning">
+              ⚠️ 重要提示：请勿将验证码透露给任何人！
+            </div>
+            
+            <div class="tips">
+              <p><strong>使用说明：</strong></p>
+              <ul>
+                <li>此验证码有效期为 <strong>5分钟</strong></li>
+                <li>请在${subjectOptions[0]}页面输入此验证码完成验证</li>
+                <li>如非本人操作，请忽略此邮件</li>
+                <li>如有疑问，请联系客服</li>
+              </ul>
+            </div>
+            
+            <p>感谢您使用我们的服务！</p>
+            <p><em>系统自动发送，请勿回复本邮件。</em></p>
+          </div>
+          
+          <div class="footer">
+            <p>© ${new Date().getFullYear()} 邮箱验证服务</p>
+            <p>本邮件由系统自动发送，如有疑问请联系管理员</p>
+            <p>发送时间：${new Date().toLocaleString("zh-CN")}</p>
+          </div>
+        </div>
+      </body>
+      </html>
+    `;
+};
+
+module.exports = {
+  generateVerificationCode,
+  sendVerificationCode,
+  isValidEmail,
+};

package/template/services/JwtTokenService.js

@@ -0,0 +1,50 @@
+/**
+ * jwt token服务（生成、验证、解码）
+ */
+
+const jwt = require("jsonwebtoken");
+const config = require("../config");
+const { setToken} = require("./TokenRedisService.js");
+
+/**
+ * 生成token
+ * @param {*} payload: 用户信息
+ * @param {*} options : 配置项
+ * @returns token
+ */
+const generateToken = async (payload = { account: "", userId: "" }) => {
+  let token = jwt.sign(payload, config.jwt.secret, {
+    expiresIn: config.jwt.expiresIn,
+  });
+
+  //保存token到redis
+  await setToken(payload.userId,token);
+  return token;
+};
+
+/**
+ * 验证token
+ * @param {*} token
+ * @returns
+ */
+const verifyToken = (token) => {
+  try {
+    return jwt.verify(token, config.jwt.secret);
+  } catch (error) {
+    throw new Error("Token验证失败");
+  }
+};
+/**
+ * 解码token
+ * @param {*} token
+ * @returns
+ */
+const decodeToken = (token) => {
+  try {
+    return jwt.decode(token, config.jwt.secret);
+  } catch (error) {
+    throw new Error("Token解码失败");
+  }
+};
+
+module.exports = { generateToken, verifyToken, decodeToken };

package/template/services/PasswordService.js

@@ -0,0 +1,133 @@
+/**
+ * 密码服务
+ */
+
+const authDAO = require("../models/Auth.js");
+const { error } = require("../utils/response.js");
+const { deleteToken } = require("./TokenRedisService.js");
+const argon2 = require("argon2");
+const passwordValidator = require("../utils/passwordValidator.js");
+const {
+  isValidEmail,
+} = require("./EmailService.js");
+const CodeRedisService = require("./CodeRedisService.js");
+const codeRedisService = new CodeRedisService("resetPassword");
+
+
+class PasswordService {
+  /**
+   * 修改密码
+   * @param {*} ctx 上下文对象
+   * @param {*} oldPassword 旧密码
+   * @param {*} newPassword 新密码
+   * @returns {boolean|undefined} 是否修改成功
+   */
+  async changePassword(ctx, oldPassword, newPassword) {
+    // 从上下文状态中获取当前登录用户的ID
+    let { userId } = ctx.state.user;
+
+    // 根据用户ID从数据库中查找用户信息
+    let result = await authDAO.findById(userId);
+
+    // 检查用户是否存在
+    if (!result) return error(ctx, "用户不存在", 400);
+
+    // 提取用户ID和数据库中存储的哈希密码
+    const { id, password: hashedPassword } = result;
+
+    // 使用argon2验证旧密码的正确性
+    let isMatch = await argon2.verify(hashedPassword, oldPassword);
+
+    // 如果旧密码验证失败，返回错误响应
+    if (!isMatch) {
+      return error(ctx, "旧密码错误", 400);
+    }
+
+    //新密码强度验证
+    let validateResult = passwordValidator.validate(newPassword);
+    if (!validateResult.isValid) {
+      return error(ctx, validateResult.errors[0], 400);
+    }
+
+    // 使用argon2对新密码进行加密，配置参数：
+    // - type: 使用argon2id算法（推荐的平衡安全性和性能的算法）
+    // - memoryCost: 内存成本设为2^16（64MB）
+    // - timeCost: 时间成本设为3（迭代次数）
+    // - parallelism: 并行度设为1（线程数）
+    const newHashedPassword = await argon2.hash(newPassword, {
+      type: argon2.argon2id,
+      memoryCost: 2 ** 16,
+      timeCost: 3,
+      parallelism: 1,
+    });
+
+    // 更新数据库中的用户密码
+    await authDAO.update(id, {
+      password: newHashedPassword,
+    });
+
+    // 密码修改成功后，删除用户的token，确保旧密码的token失效
+    await deleteToken(userId);
+
+    // 返回成功标志
+    return true;
+  }
+
+  /**
+   * 重置密码
+   * @param {*} ctx 上下文对象
+   * @param {*} email 邮箱
+   * @param {*} code 验证码
+   * @param {*} password 新密码
+   * @returns {boolean|undefined} 是否重置成功
+   */
+  async resetPassword(ctx, email, code, password) {
+    //邮箱格式校验
+    if (!isValidEmail(email)) {
+      return error(ctx, "邮箱格式不正确", 400);
+    }
+
+    //新密码强度验证
+    let validateResult = passwordValidator.validate(password);
+    if (!validateResult.isValid) {
+      return error(ctx, validateResult.errors[0], 400);
+    }
+
+    // 从数据库中查找用户信息
+    let result = await authDAO.findOne({ email });
+    // 检查用户是否存在
+    if (!result) return error(ctx, "用户不存在", 400);
+
+    const storedCode = await codeRedisService.getVerifyCode(email);
+    if (!storedCode) {
+      return error(ctx, "验证码无效或已过期，请重新获取", 400);
+    }
+
+    if (storedCode !== code) {
+      return error(ctx, "验证码错误，请重新输入", 400);
+    }
+    // 验证成功后清理 - 防止重复使用
+    await codeRedisService.delVerifyCode(email);
+
+     // 使用argon2对新密码进行加密
+    const newHashedPassword = await argon2.hash(password, {
+      type: argon2.argon2id,
+      memoryCost: 2 ** 16,
+      timeCost: 3,
+      parallelism: 1,
+    });
+
+    // 更新数据库中的用户密码
+    await authDAO.update(result.id, {
+      password: newHashedPassword,
+    });
+
+    // 密码重置成功后，删除用户的token，确保旧密码的token失效
+    await deleteToken(result.id);
+    return true;
+  }
+
+
+}
+
+module.exports = new PasswordService();

package/template/services/TokenRedisService.js

@@ -0,0 +1,29 @@
+/**
+ * token存储redis服务
+ */
+const redis = require("../config/redis");
+const config = require("../config/index.js");
+/**
+ * 存储token到白名单
+ * @param {*} token: token
+ * @param {*} userId: 用户id
+ * @param {*} expire: 过期时间,默认7天
+ */
+const setToken = async (
+  userId,
+  token,
+  expire = config.jwt.expiresIn || 24 * 60 * 60 * 7
+) => {
+  return await redis.set(`whitelist:userid:${userId}`, token, "EX", expire);
+};
+
+// 从白名单获取token（传入对应userId返回token，不存在则为 null）
+const getToken = async (userId) => {
+  return await redis.get(`whitelist:userid:${userId}`);
+};
+// 从白名单中删除 token（登出时用）
+const deleteToken = async (userId) => {
+  return await redis.del(`whitelist:userid:${userId}`);
+};
+
+module.exports = { setToken, getToken, deleteToken };

package/template/services/UserService.js

@@ -0,0 +1,128 @@
+/**
+ * 用户服务
+ */
+
+const userDAO = require("../models/User.js");
+const { error } = require("../utils/response.js");
+const dayjs = require('dayjs');
+
+class UserService {
+  //用户详情
+  async getUserById(ctx, userId) {
+    // 通过用户ID从数据库查询用户信息
+    let result = await userDAO.findById(userId);
+    // 如果查询结果为空，返回用户不存在的错误信息
+    if (!result) {
+      return error(ctx, "用户不存在", 400);
+    } else {
+      // 使用对象解构过滤掉密码字段，确保密码不会返回给客户端
+      let { password, ...data } = result;
+
+      // 返回过滤后的用户数据（不包含密码）
+      return {
+        ...data,
+        created_at: dayjs(data.created_at).format('YYYY-MM-DD HH:mm:ss'),
+        updated_at: dayjs(data.updated_at).format('YYYY-MM-DD HH:mm:ss')
+      };
+    }
+  }
+
+
+  //更新用户
+  async updateUser(ctx, userId, params) {
+    // 调用数据访问层更新用户信息
+    let result = await userDAO.update(userId, params);
+
+    // 如果更新成功返回更新结果，否则返回用户不存在的错误信息
+    return result || error(ctx, "用户不存在", 400);
+  }
+
+  //删除用户
+  async deleteUser(ctx, userId) {
+    // 调用数据访问层删除用户
+    let result = await userDAO.delete(userId);
+
+    // 如果删除成功返回删除结果，否则返回用户不存在的错误信息
+    return result || error(ctx, "用户不存在", 400);
+  }
+
+  //获取用户列表
+  async getUserList(ctx) {
+    // 定义字段类型映射，all字段为布尔类型
+    const fieldTypes = { all: "boolean" };
+
+    // 参数类型转换
+    let {
+      all = false,        // 是否查询所有数据，默认为false（分页查询）
+      startTime,          // 开始时间
+      endTime,            // 结束时间
+      email,              // 邮箱（模糊查询）
+      page,               // 页码
+      pageSize,           // 每页大小
+    } = userDAO.convertQueryParams(ctx.request.query, fieldTypes);
+
+    // 查询条件
+    let conditions = {};
+
+    // 邮箱模糊查询条件
+    if (email) {
+      conditions["$like_email"] = email;
+    }
+
+    // 时间范围查询条件
+    if (startTime && endTime) {
+      // 时间区间查询
+      conditions["$between_created_at"] = [
+        startTime,
+        endTime,
+      ];
+    } else if (startTime && !endTime) {
+      // 大于等于开始时间
+      conditions["$gte_created_at"] = startTime;
+    } else if (endTime && !startTime) {
+      // 小于等于结束时间
+      conditions["$lte_created_at"] = endTime;
+    }
+
+    // 查询所有用户（不分页）
+    if (all) {
+      let result = await userDAO.findAll(conditions, {}, fieldTypes);
+
+      // 格式化时间字段
+      result = result.map((item) => {
+        // 使用对象解构过滤掉密码字段，确保密码不会返回给客户端
+        let { password, ...data } = item;
+        return {
+          ...data,
+          created_at: dayjs(item.created_at).format('YYYY-MM-DD HH:mm:ss'),
+          updated_at: dayjs(item.updated_at).format('YYYY-MM-DD HH:mm:ss')
+        };
+      });
+      return result;
+    }
+    // 分页查询用户
+    else {
+      let result = await userDAO.paginate(
+        page,
+        pageSize,
+        conditions,
+        {},
+        fieldTypes
+      );
+
+      // 格式化时间字段
+      result.list = result.list.map((item) => {
+        // 使用对象解构过滤掉密码字段，确保密码不会返回给客户端
+        let { password, ...data } = item;
+        return {
+          ...data,
+          created_at: dayjs(item.created_at).format('YYYY-MM-DD HH:mm:ss'),
+          updated_at: dayjs(item.updated_at).format('YYYY-MM-DD HH:mm:ss')
+        };
+      });
+      return result;
+    }
+  }
+}
+
+module.exports = new UserService();

package/template/utils/crypto.js

@@ -0,0 +1,9 @@
+const crypto = require('crypto');
+
+// 生成 64 字节的 Base64 编码密钥
+const generateJWTSecret = () => {
+    let secret=crypto.randomBytes(64).toString('base64');
+  return secret
+};
+
+module.exports = { generateJWTSecret };