chanjs 2.8.9 → 2.8.11

package/core/Repository.js

@@ -7,7 +7,8 @@ import {
   CODE_PARAM_MISSING,
 } from "../response/code.js";
 
-const SORT_FIELD_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+// 合法标识符：列名或「表别名.列名」（join 查询需显式前缀消歧，如 p.price）
+const SORT_FIELD_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/;
 const OPERATORS = { $like:'like', $gt:'>', $gte:'>=', $lt:'<', $lte:'<=', $ne:'<>' };
 
 /**
@@ -69,6 +70,52 @@ function applyQuery(dbQuery, query) {
   return dbQuery;
 }
 
+/**
+ * URL 平铺查询参数 → applyQuery 条件对象（通用搜索基建）
+ *
+ * @param {object} query - 平铺查询参数（如 req.query），值为字符串/数字
+ * @param {Object<string, Function>} fieldMap - 筛选字段白名单映射表：
+ *   { urlParam: (value) => 条件片段 | null }
+ *   - 仅声明的参数会进入查询，未声明的一律忽略（防任意列注入）
+ *   - 转换函数负责类型收敛与 like 转义（utils.escapeLike），返回 null/undefined 表示无效值，忽略
+ * @returns {object} 条件对象，可直接交给 applyQuery 拼接 knex where
+ *
+ * @example
+ * const FILTERS = {
+ *   keyword: v => ({ title: { $like: `%${escapeLike(v)}%` } }),
+ *   price_min: v => Number.isFinite(Number(v)) ? { price: { $gte: Number(v) } } : null,
+ * };
+ * mapUrlFilters({ keyword: "液压", price_min: "100" }, FILTERS);
+ * // → { title: { $like: "%液压%" }, price: { $gte: 100 } }
+ */
+function mapUrlFilters(query, fieldMap) {
+  const filter = {};
+  for (const [key, map] of Object.entries(fieldMap || {})) {
+    const raw = query?.[key];
+    if (raw === undefined || raw === null || String(raw).trim() === "") continue;
+    let piece;
+    try {
+      piece = map(String(raw).trim());
+    } catch {
+      continue; // 转换函数异常视为无效参数，静默忽略（面向用户输入，前台容错）
+    }
+    if (!piece || typeof piece !== "object") continue;
+    for (const [field, cond] of Object.entries(piece)) {
+      const prev = filter[field];
+      // 同字段多操作符深合并（如 price 的 $gte 与 $lte 共存成区间）
+      if (
+        prev && typeof prev === "object" && !Array.isArray(prev) &&
+        cond && typeof cond === "object" && !Array.isArray(cond)
+      ) {
+        filter[field] = { ...prev, ...cond };
+      } else {
+        filter[field] = cond;
+      }
+    }
+  }
+  return filter;
+}
+
 /**
  * 应用字段白名单 + 排序白名单到 query
  * @param {import('knex').Knex.QueryBuilder} q
@@ -270,9 +317,8 @@ class Repository extends BaseComponent {
 
   /**
    * 更新内部原语（私有方法）：子类无法覆写。
-   * 历史教训：此前 updateById 直接调 this.update({query,data})，
-   * 业务 Service 普遍以扁平 body 形状覆写 update(body)，多态派发回子类后
-   * {query,data} 被解构成 id=undefined → 更新静默失效（无 SQL、仍返回旧数据）。
+   * 业务 Service 普遍以扁平 body 形状覆写 update(body)，若框架内部走多态的 this.update，
+   * {query,data} 会被子类签名解构致 id=undefined、更新静默失效。
    * 框架内部路径必须走本私有方法，杜绝该类命名冲突。
    */
   async #updateRaw(query, data) {
@@ -490,4 +536,7 @@ class Repository extends BaseComponent {
   }
 }
 
+// 查询条件组装原语（业务 service 可直接组合使用，不必继承 Repository）
+export { applyQuery, mapUrlFilters };
+
 export default Repository;

package/core/bootstrap/error-handler.js

@@ -68,9 +68,8 @@ export function registerErrorHandler(chan) {
     const userId = req.user?.id ?? "-";
 
     // 日志分级：业务错误 4xx → warn，系统错误 5xx → error（唯一打印点，杜绝重复刷屏）
-    // ⚠️ pino 的日志方法依赖 this，不能解引用后裸调（logFn = logger.warn; logFn(...) 会在
-    // pino/lib/tools.js 抛 TypeError: Cannot read properties of undefined (reading 'Symbol(pino.msgPrefix)')，
-    // 把真实的业务错误整个掩盖成 500），必须用箭头函数包一层保住 this
+    // pino 的日志方法依赖 this，不能解引用后裸调（会抛 TypeError 把真实业务错误掩盖成 500），
+    // 必须用箭头函数包一层保住 this
     const logFn = httpStatus < 500 ? (msg) => logger.warn(msg) : (msg) => logger.error(msg);
     logFn(JSON.stringify({
       type: err.name || "UnknownError",

package/core/loader.js

@@ -63,8 +63,8 @@ export async function loadController(moduleName) {
     // 原型方法批量bind，幂等标记避免重复绑定
     // 遍历整条原型链（含父类继承的方法）：子类方法定义在自身原型、父类模板方法定义在父类原型，
     // 只 bind 直接原型会导致继承方法 this 丢失（Express 非点调用时 this=undefined）。
-    // ⚠️ 必须用 getOwnPropertyDescriptor 取 value：BaseComponent 的 app/config/db 是 getter-only，
-    //    其中 db 返回 knex 实例（typeof 为 function），直接 inst[key] 会触发 getter 且赋值只读属性抛错。
+    // 必须用 getOwnPropertyDescriptor 取 value：BaseComponent 的 app/config/db 是 getter-only，
+    // 其中 db 返回 knex 实例（typeof 为 function），直接 inst[key] 会触发 getter 且赋值只读属性抛错。
     let proto = Object.getPrototypeOf(inst);
     while (proto && proto !== Object.prototype) {
       Object.getOwnPropertyNames(proto).forEach(key => {

package/index.js

@@ -22,6 +22,9 @@ export { BaseComponent } from "./core/BaseComponent.js";
 export { default as Controller } from "./core/Controller.js";
 export { default as Repository } from "./core/Repository.js";
 export { Service } from "./core/Service.js";
+// 查询条件组装原语（通用搜索基建：URL 平铺参数 → knex 安全 where）
+export { applyQuery, mapUrlFilters } from "./core/Repository.js";
+export { escapeLike } from "./utils/escape.js";
 
 // ===================== 基础设施（事件总线 / 定时任务 / i18n）=====================
 export { EventBus, event } from "./core/EventBus.js";

package/middleware/validate.js

@@ -76,7 +76,7 @@ export function validateAll(schemas) {
       setValidated(req, source, result.data);
       aggregated[source] = result.data;
     }
-    // 聚合多来源校验结果，避免用单一来源覆盖已校验数据（修复原末行用 req.body 覆盖问题）
+    // 聚合多来源校验结果，避免用单一来源覆盖已校验数据
     req.validated = aggregated;
     next();
   };

package/middleware/waf.js

@@ -19,9 +19,8 @@ const WAF_KNOWN_KEYS = new Set(["enabled", "rateLimit", "ignorePaths", "bodyXssP
 
 const TRUSTED_IPS = new Set(["127.0.0.1", "::1"]);
 
-// URL/query 关键词检测保留的分类——只保留真正危险、几乎不会在正常 URL 中出现的攻击特征。
-// 去掉 wholeWord / extensions / directories / sensitiveIdentifiers / commandInjection，
-// 这些在正常 URL（?debug=1、/internal/、/.well-known/、wget/scp/dd 等）极易误伤正常请求。
+// URL/query 关键词检测只保留真正危险、几乎不会在正常 URL 中出现的攻击特征，
+// 避免 ?debug=1、/internal/、/.well-known/、wget/scp/dd 等正常请求被误伤。
 const URL_SCAN_CATEGORIES = ["sqlInjection", "xss", "pathTraversal", "encoding"];
 
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "chanjs",
-  "version": "2.8.9",
+  "version": "2.8.11",
   "description": "chanjs基于 Node.js + Express 5 的标准 HMVC 框架（NHMVC），纯 JavaScript（ESM）开发。",
   "main": "index.js",
   "module": "index.js",

package/utils/escape.js

@@ -0,0 +1,8 @@
+/**
+ * LIKE 关键词转义（% _ \），防止用户输入的通配符干扰模糊查询语义。
+ * 仅用于用户输入侧（如 mapUrlFilters 的字段映射函数内部）；
+ * 内部代码构造的查询条件为可信输入，无需转义。
+ */
+export function escapeLike(str = "") {
+  return String(str).replace(/[%_\\]/g, "\\$&");
+}

package/utils/index.js

@@ -44,4 +44,5 @@ export { tree, treeById } from "./tree.js";
 export { filterFields } from "./filter.js";
 
 // 分页工具
-export { pages } from "./pages.js";
+export { pages, parsePage, parsePageSize, pageHtml } from "./pages.js";
+export { escapeLike } from "./escape.js";

package/utils/logger.js

@@ -24,8 +24,7 @@ const root = pino(
  * 附加参数序列化：error/warn 的第二参（Error/对象）拼进消息本身。
  *
  * 背景：pino-pretty 的 messageFormat 字符串模板只渲染 msg 字段，
- * 「logger.error(msg, err)」的 err 会被整体丢弃（连堆栈都不输出），
- * 曾导致 Gather.js 加载失败只剩「导入失败 xxx.js:」空冒号、无法定位根因。
+ * 「logger.error(msg, err)」的 err 会被整体丢弃（连堆栈都不输出）。
  * 在封装层统一序列化，保证文档承诺的「第二参数自动解析堆栈」真实生效。
  * @param {unknown[]} args error/warn 的除消息外全部参数
  * @returns {string} 可读文本（Error 优先 stack，对象 JSON，其余 String）

package/utils/pages.js

@@ -4,6 +4,73 @@
  * 样式由项目 CSS（如 .blince-pagination）统一维护，不依赖 Tailwind 等第三方框架
  */
 
+/**
+ * 解析页码：非数字/0/负数统一回落 1，防 NaN 或负数穿透进 SQL LIMIT/OFFSET
+ * （?page=abc 这类脏值若直接 parseInt 后进查询，NaN 会让 knex LIMIT 报错）
+ * @param {*} value 页码来源（req.query / req.params 原始值）
+ * @returns {number} 至少为 1 的整数页码
+ */
+export function parsePage(value) {
+  return Math.max(1, parseInt(value, 10) || 1);
+}
+
+/**
+ * 解析每页条数：非数字回落 fallback，并钳制 [1, max] 区间防大值拖垮 DB
+ * @param {*} value pageSize 来源（req.query / req.params 原始值）
+ * @param {number} [fallback=10] 非法/缺省时的默认条数
+ * @param {number} [max=100] 上限（来自公开 query 的值必须有上限）
+ * @returns {number} 钳制后的整数条数
+ */
+export function parsePageSize(value, fallback = 10, max = 100) {
+  return Math.min(Math.max(parseInt(value, 10) || fallback, 1), max);
+}
+
+/**
+ * 渲染 query 式分页 HTML（?current=N，保留筛选参数）
+ * 与 pages() 的分工：pages() 面向 /list-2.html 路径式分页（SEO 静态 URL，带省略号）；
+ * 本函数面向带筛选条件的列表页——URLSearchParams 自动编码参数，天然防注入
+ * @param {Object} opts
+ * @param {string} opts.baseUrl 基础路径（如 /blog.html）
+ * @param {Object} [opts.query] 当前 URL query 对象，翻页时原样保留（剔除 current）
+ * @param {number} opts.total 总记录数
+ * @param {number} [opts.pageSize=10] 每页条数
+ * @param {number} [opts.current=1] 当前页码
+ * @param {string} [opts.unit="篇"] 统计文案量词（篇/家/条…）
+ * @param {number} [opts.window=2] 当前页前后各显示页数（窗口共 2*window+1 页）
+ * @returns {string} 总页数 ≤1 时返回空串
+ */
+export function pageHtml({ baseUrl, query, total, pageSize = 10, current = 1, unit = "篇", window = 2 }) {
+  total = parseInt(total) || 0;
+  current = parsePage(current);
+  pageSize = parsePageSize(pageSize);
+  const totalPage = Math.max(1, Math.ceil(total / pageSize));
+  if (totalPage <= 1) return "";
+
+  const base = new URLSearchParams();
+  Object.entries(query || {}).forEach(([k, v]) => {
+    if (k === "current" || v === undefined || v === null || v === "") return;
+    base.set(k, v);
+  });
+  const link = (n) => {
+    const p = new URLSearchParams(base);
+    if (n > 1) p.set("current", n);
+    const s = p.toString();
+    return `${baseUrl}${s ? "?" + s : ""}`;
+  };
+  const pageLink = (n) =>
+    n === current ? `<span class="current">${n}</span>` : `<a href="${link(n)}">${n}</a>`;
+
+  let html = "";
+  if (current > 1) html += `<a href="${link(current - 1)}">上一页</a>`;
+  let start = Math.max(1, current - window);
+  let end = Math.min(totalPage, start + window * 2);
+  start = Math.max(1, end - window * 2);
+  for (let i = start; i <= end; i++) html += pageLink(i);
+  if (current < totalPage) html += `<a href="${link(current + 1)}">下一页</a>`;
+  html += `<span class="disabled">共 ${total} ${unit} / ${totalPage} 页</span>`;
+  return html;
+}
+
 /**
  * 渲染分页HTML
  * @param {number} current 当前页码