chanjs 2.7.2 → 2.7.4

package/response/response.js

@@ -0,0 +1,258 @@
+import {
+  CODE,
+  DB_ERROR,
+  CODE_OK,
+  CODE_BUSINESS_FAIL,
+  CODE_SYSTEM_ERROR,
+  CODE_NOT_FOUND,
+  getCodeMsg,
+} from "../config/code.js";
+
+/**
+ * 响应工具函数
+ * 提供统一的响应格式和错误处理
+ *
+ * ============================================================
+ * 统一响应格式（三层 code 体系）
+ * ============================================================
+ * 所有响应都遵循以下结构：
+ * {
+ *   success: boolean,    // 业务是否成功（true/false）
+ *   code: number,        // 业务 code（0 成功 / 1xxx 业务 / 5xxx 系统 / 6xxx 数据库）
+ *   msg: string,         // 用户可见消息
+ *   data: any            // 业务数据
+ * }
+ *
+ * HTTP Status 与业务 code 解耦：
+ * - HTTP Status 由网关/Express 控制（200/400/401/403/404/500）
+ * - 业务 code 由业务层控制（0 / 1xxx / 5xxx / 6xxx）
+ * - 前端先看 HTTP Status，再看业务 code
+ *
+ * ============================================================
+ * 使用示例
+ * ============================================================
+ * // 成功
+ * success({ data: { list: [] } })
+ * // → { success: true, code: 0, msg: '操作成功', data: { list: [] } }
+ *
+ * // 业务失败（通用）
+ * fail({ msg: '栏目下存在文章' })
+ * // → { success: false, code: 1008, msg: '栏目下存在文章', data: {} }
+ *
+ * // 业务失败（指定 code）
+ * fail({ msg: '参数缺失', code: 1007 })
+ * // → { success: false, code: 1007, msg: '参数缺失', data: {} }
+ *
+ * // 错误（系统/数据库异常，err 必传）
+ * error({ err: dbError })
+ * // → { success: false, code: 6005, msg: '数据重复', data: {} }
+ */
+
+/**
+ * 错误消息映射（数据库错误码专用）
+ * 与 CODE 字典保持一致，独立出来便于按 code 取消息
+ * @private
+ */
+const ERROR_MESSAGES = CODE;
+
+/**
+ * 是否暴露错误详情（sql/stack）
+ * 显式环境变量控制，避免 development 模式自动暴露敏感信息
+ * - 默认 false：生产/开发都不暴露
+ * - 设 EXPOSE_ERR_DETAIL=true 后才返回 sql/stack/message 等详细信息
+ * @private
+ */
+const EXPOSE_ERR_DETAIL = process.env.EXPOSE_ERR_DETAIL === 'true';
+
+/**
+ * 根据错误对象推断业务 code
+ * @private
+ * @param {Error} error - 错误对象
+ * @returns {number} 业务 code
+ */
+const inferErrorCode = (error) => {
+  if (!error?.message) return CODE_SYSTEM_ERROR;
+
+  const msg = error.message.toLowerCase();
+  if (msg.includes("syntax") || msg.includes("sql")) {
+    return 6008;  // 数据库语法错误
+  }
+  if (msg.includes("connection closed") || msg.includes("connection lost")) {
+    return 6009;  // 数据库连接关闭
+  }
+  if (msg.includes("permission") || msg.includes("access denied")) {
+    return 1003;  // 权限不足
+  }
+  return CODE_SYSTEM_ERROR;
+};
+
+/**
+ * 解析数据库错误
+ * @param {Error} error - 数据库错误对象
+ * @returns {{code: number, msg: string, statusCode: number}} 包含 code、msg 和 HTTP statusCode
+ * @description
+ * 将数据库原生错误码映射为业务 code，并给出对应的 HTTP statusCode
+ * - 6xxx 数据库错误 → HTTP 500
+ * - 1xxx 业务错误 → HTTP 400
+ * - 其他 → HTTP 500
+ */
+export function parseDatabaseError(error) {
+  let errorCode;
+  if (error?.code && DB_ERROR[error.code]) {
+    errorCode = DB_ERROR[error.code];
+  } else {
+    errorCode = inferErrorCode(error);
+  }
+
+  // 根据 code 段位决定 HTTP statusCode
+  let statusCode;
+  if (errorCode >= 6000) {
+    statusCode = 500;  // 数据库错误 → 500
+  } else if (errorCode >= 5000) {
+    statusCode = 500;  // 系统错误 → 500
+  } else if (errorCode >= 1000) {
+    statusCode = 400;  // 业务错误 → 400
+  } else {
+    statusCode = 500;  // 兜底
+  }
+
+  return {
+    code: errorCode,
+    msg: ERROR_MESSAGES[errorCode] || error?.message || "服务器内部错误",
+    statusCode,
+  };
+}
+
+/**
+ * 生成错误响应（系统/数据库异常用）
+ * @param {Object} options - 响应选项
+ * @param {Error} [options.err] - 错误对象（必传，用于解析 code）
+ * @param {Object} [options.data={}] - 响应数据
+ * @param {number} [options.code=5001] - 错误 code（err 为空时使用）
+ * @returns {Object} 错误响应对象
+ * @description
+ * - 传 err：自动解析数据库错误码并映射为业务 code
+ * - 不传 err：使用传入的 code 或默认 5001
+ * 开发环境下（NODE_ENV=development）附带数据库错误详情
+ */
+export const error = ({ err, data = {}, code = CODE_SYSTEM_ERROR } = {}) => {
+  if (err) {
+    console.error("[DB Error]", err?.message || err);
+    const errorCode = err?.code && DB_ERROR[err.code]
+      ? DB_ERROR[err.code]
+      : inferErrorCode(err);
+    const msg = ERROR_MESSAGES[errorCode] || "操作失败";
+
+    return {
+      success: false,
+      msg,
+      code: errorCode,
+      data: EXPOSE_ERR_DETAIL ? {
+        sql: err?.sql,
+        sqlMessage: err?.sqlMessage,
+        message: err?.message,
+      } : {},
+    };
+  }
+
+  const msg = getCodeMsg(code, "操作失败");
+  return {
+    success: false,
+    msg,
+    code,
+    data,
+  };
+};
+
+/**
+ * 生成失败响应（业务失败用）
+ * @param {Object} options - 响应选项
+ * @param {string} [options.msg="操作失败"] - 错误消息
+ * @param {Object} [options.data={}] - 响应数据
+ * @param {number} [options.code=1008] - 业务 code（默认 1008 业务处理失败）
+ * @returns {Object} 失败响应对象
+ * @description
+ * 用于业务逻辑失败（如：栏目下存在文章、参数缺失等）
+ * 与 error() 区别：fail 用于业务可恢复错误，error 用于系统/数据库异常
+ *
+ * @example
+ * fail({ msg: '栏目下存在文章' })                       // → code: 1008
+ * fail({ msg: '参数缺失', code: 1007 })                // → code: 1007
+ * fail({ msg: '权限不足', code: 1003 })                // → code: 1003
+ */
+export const fail = ({ msg = "操作失败", data = {}, code = CODE_BUSINESS_FAIL } = {}) => {
+  return {
+    success: false,
+    msg,
+    code,
+    data,
+  };
+};
+
+/**
+ * 生成成功响应
+ * @param {Object} options - 响应选项
+ * @param {Object} [options.data={}] - 响应数据
+ * @param {string} [options.msg="操作成功"] - 成功消息
+ * @returns {Object} 成功响应对象
+ * @description
+ * code 固定为 0（不再用 200，避免与 HTTP 200 混淆）
+ */
+export const success = ({ data = {}, msg = "操作成功" } = {}) => ({
+  success: true,
+  msg,
+  code: CODE_OK,
+  data,
+});
+
+/**
+ * 生成 404 响应（接口不存在）
+ * @param {Object} req - Express 请求对象
+ * @returns {Object} 404 响应对象
+ * @description
+ * HTTP Status 404，业务 code 1004
+ */
+export function notFoundResponse(req) {
+  return {
+    success: false,
+    msg: "接口不存在",
+    code: CODE_NOT_FOUND,
+    data: { path: req.path, method: req.method },
+  };
+}
+
+/**
+ * 生成错误响应（Express 错误处理中间件用）
+ * @param {Error} err - 错误对象
+ * @param {Object} req - Express 请求对象
+ * @returns {Object} 错误响应对象
+ * @description
+ * 用于 Express 全局错误处理中间件
+ * 自动解析数据库错误并映射为业务 code
+ */
+export function errorResponse(err, req) {
+  const errorInfo = parseDatabaseError(err);
+
+  console.error(`[Error Handler] ${errorInfo.msg} - ${err?.message}`, {
+    code: errorInfo.code,
+    path: req?.path,
+    method: req?.method,
+    sql: err?.sql,
+    sqlMessage: err?.sqlMessage,
+    stack: err?.stack,
+  });
+
+  return {
+    success: false,
+    msg: errorInfo.msg,
+    code: errorInfo.code,
+    data: EXPOSE_ERR_DETAIL
+      ? {
+          message: err?.message,
+          sql: err?.sql,
+          sqlMessage: err?.sqlMessage,
+          stack: err?.stack,
+        }
+      : {},
+  };
+}

package/schedule/index.js

@@ -0,0 +1,6 @@
+/**
+ * 定时任务模块 - 支持 cron / every / delay
+ * 错误隔离 + 优雅停机
+ */
+export { default as Schedule } from "./schedule.js";
+export { schedule } from "./schedule.js";