chanjs 2.7.3 → 2.7.5

package/response/response.js

@@ -1,258 +1,104 @@
-import {
-  CODE,
-  DB_ERROR,
-  CODE_OK,
-  CODE_BUSINESS_FAIL,
-  CODE_SYSTEM_ERROR,
-  CODE_NOT_FOUND,
-  getCodeMsg,
-} from "../config/code.js";
+import { CODE_OK, CODE_BUSINESS_FAIL, CODE_NOT_FOUND, CODE_SYSTEM_ERROR, getCodeMsg } from "./code.js";
+import { isAppError } from "../core/errors.js";
+import { htmlEncode } from "../utils/html.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: {} }
+ * 统一响应序列化工具（纯函数：无 IO、无日志、无环境判断、无 DB 感知）
+ * 仅做数据格式化，可复用于定时任务 / RPC / 接口返回，与全局错误处理器解耦
  */
+export const success = ({ data = {}, msg = getCodeMsg(CODE_OK) } = {}) => ({
+  success: true, code: CODE_OK, 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;  // 兜底
-  }
+export const fail = ({ msg = getCodeMsg(CODE_BUSINESS_FAIL), data = {}, code = CODE_BUSINESS_FAIL } = {}) => ({
+  success: false, code, msg, data,
+});
 
-  return {
-    code: errorCode,
-    msg: ERROR_MESSAGES[errorCode] || error?.message || "服务器内部错误",
-    statusCode,
-  };
-}
+/** 404 路由不存在专用返回体 */
+export const routeNotFound = req => ({
+  success: false,
+  code: CODE_NOT_FOUND,
+  msg: "请求的资源不存在",
+  data: { path: req.originalUrl || req.url, method: req.method },
+});
 
 /**
- * 生成错误响应（系统/数据库异常用）
- * @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）附带数据库错误详情
+ * 统一错误序列化格式化（纯函数）
+ * - 业务错误（AppError 体系）：提取 code / msg + 自定义扩展字段
+ * - 系统 / 未知错误：生产环境强制脱敏，仅 exposeDetail=true 时附带堆栈
  */
-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,
-      } : {},
-    };
+export function serializeError(err, exposeDetail = false) {
+  if (isAppError(err)) {
+    const result = { success: false, code: err.code, msg: err.message };
+    const extra = {};
+    for (const key of Object.getOwnPropertyNames(err)) {
+      const val = err[key];
+      if (val === undefined || val === null) continue;
+      if (typeof val === "function" || typeof val === "symbol") continue;
+      try { extra[key] = val && typeof val === "object" && !Array.isArray(val) ? JSON.stringify(val) : val; }
+      catch { extra[key] = "[unserializable]"; }
+    }
+    if (Object.keys(extra).length > 0) result.data = extra;
+    return result;
   }
 
-  const msg = getCodeMsg(code, "操作失败");
+  // 原生未知系统错误：生产环境强制脱敏，不泄露 SQL / 堆栈
   return {
     success: false,
-    msg,
-    code,
-    data,
+    code: CODE_SYSTEM_ERROR,
+    msg: err?.message || "系统内部错误",
+    ...(exposeDetail && err?.stack ? { data: { stack: err.stack } } : {}),
   };
-};
-
-/**
- * 生成失败响应（业务失败用）
- * @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,
-});
+// =================== HTML 错误页（纯函数，无模板引擎依赖） ===================
 
 /**
- * 生成 404 响应（接口不存在）
- * @param {Object} req - Express 请求对象
- * @returns {Object} 404 响应对象
- * @description
- * HTTP Status 404，业务 code 1004
+ * 框架内置兜底错误HTML页面
  */
-export function notFoundResponse(req) {
-  return {
-    success: false,
-    msg: "接口不存在",
-    code: CODE_NOT_FOUND,
-    data: { path: req.path, method: req.method },
-  };
+export function buildErrorHtml(status, errorMsg, code, req) {
+  const url = htmlEncode(req.originalUrl || req.url);
+  const method = htmlEncode(req.method);
+  const msg = htmlEncode(errorMsg || "服务器内部错误");
+  const codeText = htmlEncode(code ? String(code) : `HTTP_${status}`);
+
+  return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${status} 服务异常</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Hiragino Sans GB","Microsoft YaHei",sans-serif;background:#f5f7fa;color:#2c3e50;min-height:100vh;display:flex;align-items:center;justify-content:center;padding:20px}
+.box{max-width:620px;width:100%;background:#fff;border-radius:12px;box-shadow:0 2px 16px rgba(0,0,0,.06);padding:40px 32px;}
+.code{font-size:64px;font-weight:700;line-height:1;color:#1677ff;margin-bottom:8px;text-align:center}
+.title{font-size:18px;font-weight:600;margin-bottom:12px;color:rgba(0,0,0,0.88);text-align:center}
+.msg{font-size:14px;color:#262626;line-height:1.6;margin-bottom:20px;word-break:break-all;background: #fafafa;padding: 20px;border-radius: 8px;}
+.url{font-size:14px;color:#434343;margin-bottom:24px;word-break:break-all}
+</style>
+</head>
+<body>
+<div class="box">
+  <div class="code">${status}</div>
+  <div class="title">服务异常</div>
+  <div class="msg">${msg}</div>
+  <div class="url">请求地址：${method} ${url}</div>
+  <div class="url">错误码：${codeText}</div>
+</div>
+</body>
+</html>`;
 }
 
 /**
- * 生成错误响应（Express 错误处理中间件用）
- * @param {Error} err - 错误对象
- * @param {Object} req - Express 请求对象
- * @returns {Object} 错误响应对象
- * @description
- * 用于 Express 全局错误处理中间件
- * 自动解析数据库错误并映射为业务 code
+ * 统一错误响应出口（HTML / JSON 自动分流）
+ * - API 请求（XHR、Accept 优先 json）→ 一律返回 JSON
+ * - 浏览器页面请求（Accept 优先 html）→ 渲染内置 HTML 错误页
  */
-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,
-        }
-      : {},
-  };
+export function respondError(res, req, { httpStatus = 500, code = 500, msg = "服务器内部错误", data = null } = {}) {
+  const wantsJson = req && (req.xhr || req.accepts?.(["json", "html"]) === "json");
+  if (!wantsJson && req?.accepts?.("html")) {
+    return res.status(httpStatus).type("html").send(buildErrorHtml(httpStatus, msg, code, req));
+  }
+  return res.status(httpStatus).json({ success: false, code, msg, data });
 }

package/security/checker.js

@@ -1,83 +1,35 @@
-import { keywordRegexCache } from "./keywords.js";
+import { KEYWORD_RULES, keywordRegexCache, SORTED_CATEGORIES } from "./keywords.js";
 
 /**
- * 安全检查工具
- * 提供关键词检测和路径忽略检查功能
+ * 恶意关键词检测：单次遍历预排序的分类列表，利用捕获组直接定位命中关键词
+ * @param {string} fullText 待检测文本
+ * @returns {{category: string; keyword: string}|null}
  */
-
-/**
- * 检查文本中是否包含恶意关键词
- * @param {string} fullText - 要检查的完整文本
- * @returns {Object|null} 检测结果，包含 category 和 keyword，未检测到返回 null
- * @description
- * 性能优化（P2 #19）：
- * 1. 先用每类合并的大正则做预检（单次 test 判断该类是否命中）
- * 2. 预检命中后再遍历该类的具体关键词定位命中项
- * 3. 正常请求：8 次大正则 test，比原版 80+ 次小正则 test 快 10 倍
- * 4. 恶意请求：大正则预检 + 该类关键词遍历，开销略增但可接受
- *
- * 按优先级检查：sqlInjection / xss / commandInjection 优先
- * @example
- * const result = checkKeywords('SELECT * FROM users WHERE 1=1');
- * console.log(result); // { category: 'sqlInjection', keyword: 'union select' }
- */
-export function checkKeywords(fullText) {
-  if (!fullText?.trim()) return null;
-
-  const priorityCategories = ['sqlInjection', 'xss', 'commandInjection'];
-  const otherCategories = Object.keys(keywordRegexCache).filter(c => !priorityCategories.includes(c));
-
-  // 优先类别
-  for (const category of priorityCategories) {
-    const cache = keywordRegexCache[category];
-    if (!cache?.mergedRegex) continue;
-
-    // 预检：大正则一次 test
-    if (!cache.mergedRegex.test(fullText)) continue;
-
-    // 命中：遍历定位具体关键词
-    for (const { keyword, regex } of cache.patterns) {
-      if (regex.test(fullText)) {
-        return { category, keyword };
-      }
-    }
+export const checkKeywords = fullText => {
+  const text = fullText?.trim();
+  if (!text) return null;
+
+  for (const cat of SORTED_CATEGORIES) {
+    const match = keywordRegexCache[cat].merged.exec(text);
+    if (!match) continue;
+    // capture[0]是整体匹配，capture[1..]是每个关键词的捕获组
+    const idx = match.findIndex((g, i) => i > 0 && g);
+    return { category: cat, keyword: KEYWORD_RULES[cat][idx - 1] };
   }
-
-  // 其他类别
-  for (const category of otherCategories) {
-    const cache = keywordRegexCache[category];
-    if (!cache?.mergedRegex) continue;
-
-    if (!cache.mergedRegex.test(fullText)) continue;
-
-    for (const { keyword, regex } of cache.patterns) {
-      if (regex.test(fullText)) {
-        return { category, keyword };
-      }
-    }
-  }
-
   return null;
-}
+};
 
 /**
- * 检查路径是否在忽略列表中
- * @param {string} path - 要检查的路径
- * @param {Array<string>} ignorePaths - 忽略路径数组
- * @returns {boolean} 是否应该忽略该路径
- * @description
- * 检查给定路径是否匹配忽略列表中的任意路径
- * 支持精确匹配和前缀匹配
- * @example
- * isIgnored('/api/health', ['/api/health', '/metrics']); // true
- * isIgnored('/api/users', ['/api/health']); // false
+ * 路径忽略校验：大小写不敏感、自动去除末尾斜杠，支持精确/前缀匹配
+ * @param {string} path 当前请求路径
+ * @param {string[]} ignorePaths 忽略路径列表
+ * @returns {boolean}
  */
-export function isIgnored(path, ignorePaths) {
-  if (!path || !ignorePaths?.length) return false;
-
-  const normalizedPath = path.trim().toLowerCase().replace(/\/$/, '');
-  return ignorePaths.some(p => {
-    const normalizedP = p.trim().toLowerCase().replace(/\/$/, '');
-    return normalizedPath === normalizedP || normalizedPath.startsWith(`${normalizedP}/`);
+export const isIgnored = (path, ignorePaths) => {
+  if (!path || !Array.isArray(ignorePaths) || !ignorePaths.length) return false;
+  const target = path.trim().toLowerCase().replace(/\/$/, "");
+  return ignorePaths.some(raw => {
+    const rule = raw.trim().toLowerCase().replace(/\/$/, "");
+    return target === rule || target.startsWith(`${rule}/`);
   });
-}
+};

package/security/index.js

@@ -1,14 +1,9 @@
 /**
- * 安全模块 - 关键词检查/XSS过滤/签名加密/JWT/限流
- * - checker + keywords: 敏感词检测（大正则预检优化）
- * - xss-filter: XSS 过滤（WeakSet 防循环引用）
- * - sign: AES-256-GCM 签名加密（timingSafeEqual 防时序攻击）
- * - jwt: JWT 令牌生成/验证
- * - rate-limit: IP 维度限流（服务端存储）
+ * security 模块聚合导出
  */
 export { checkKeywords, isIgnored } from "./checker.js";
-export { keywordRegexCache, KEYWORD_RULES } from "./keywords.js";
+export { keywordRegexCache } from "./keywords.js";
 export { filterXSS } from "./xss-filter.js";
-export { signData, verifySign, aesEncrypt, aesDecrypt } from "./sign.js";
-export { verifyToken, generateToken, setToken, getToken, revokeToken, isTokenRevoked } from "./jwt.js";
+export { setToken, getToken } from "./jwt.js";
+export { aesEncrypt, aesDecrypt } from "./sign.js";
 export { createRateLimitMiddleware } from "./rate-limit.js";