chanjs 2.7.11 → 2.7.13

package/README.md

@@ -1,84 +1,102 @@
 # ChanJS
 
-基于 Node.js + Express 5 的标准 HMVC 框架（NHMVC），纯 JavaScript（ESM）开发。模块自治 + 跨模块双通道协作，约定优于配置，开箱即用。
+基于 Node.js + Express 5 构建的**标准 HMVC（NHMVC）后端框架**，原生 ESM 纯 JavaScript 开发。
+以**模块自治 + 双通道跨模块协作**为核心，约定优于配置，开箱即用，拒绝冗余复杂。
+
+## 设计哲学
+
+> 
+> **大道至简。**
+> 优秀的开发工具，应当化繁为简。ChanJS 摒弃过度设计与沉重抽象，回归纯粹 JavaScript，用最少的心智负担交付稳定高效的业务能力。
+
+## 核心亮点
+
+- 🛡️ **安全可控**：内置多层防护能力，降低业务安全开发成本
+- ⚡ **高性能**：高性能日志、按需组件加载、慢查询监控
+- 🪶 **轻量精简**：无多余抽象、低侵入、上手门槛低
+- ✅ **务实好用**：聚焦后端业务高频场景，配套完整基础设施
 
 ## 特性
 
 ### 核心架构
-- Express 5+ 原生
-- Node.js 22.18+
-- ES Modules（import / export）
-- 标准 HMVC 架构（模块自治 + 跨模块双通道协作）
-- 约定优于配置
+
+- 原生基于 Express 5+
+- 最低运行环境 Node.js 22.18+
+- 全量 ES Modules（import / export）
+- **标准 HMVC 架构：模块自治 + 双通道跨模块协作**
+- 约定优于配置，减少样板配置代码
 
 ### 基础设施
-- **日志**：[pino](https://github.com/pinojs/pino) 高性能结构化日志
-- **请求日志**：pino-http，自动生成 requestId 贯穿全链路
-- **国际化**：[i18next](https://www.i18next.com/) 多语言支持
-- **事件总线**：EventBus，基于 Node 内置 EventEmitter
-- **定时任务**：Task，基于 [node-cron](https://github.com/node-cron/node-cron)
-- **数据库**：[Knex](https://knexjs.org/) 查询构建器，慢查询监控
-- **组件容器**：按需动态加载 controller/service，成功永久缓存、缺失不缓存
-- **优雅停机**：统一信号处理，资源按序释放
-
-### 安全能力
-- WAF 防火墙
-- XSS 防护
-- 关键词过滤
-- 请求限流
-- 路由白名单
-- Cookie 安全
-
-### 中间件生态
-- CORS
-- 请求解析（body / cookie）
-- 静态资源
-- favicon
-- 请求头注入
-- Art-template 模板引擎
-
-### 开发体验
-- 多环境配置（.env.dev / .env.prd）
-- 统一响应（success / fail）
+
+- **高性能日志**：Pino 结构化日志输出
+- **全链路请求追踪**：pino‑http，自动注入唯一 `requestId`
+- **国际化多语言**：i18next，内存高速语言查找
+- **全局事件总线**：轻量封装 Node.js EventEmitter，解耦业务事件
+- **定时任务调度**：node‑cron，自带异常捕获、停机安全回收
+- **数据库层**：Knex 查询构建器，内置慢查询监控告警
+- **按需组件容器**：Controller/Service 动态懒加载，成功实例永久缓存；缺失模块不缓存，修改文件即时生效
+- **优雅停机**：统一信号监听，资源有序释放，超时强制退出
+
+### 内置安全能力
+
+- WAF 基础防火墙
+- XSS 请求防护
+- 敏感关键词过滤
+- 接口请求限流
+- 路由访问白名单
+- Cookie 安全加固
+
+### 开箱即用中间件生态
+
+- CORS 跨域处理
+- Body / Cookie 请求解析
+- 静态资源托管
+- favicon 快捷支持
+- 自定义响应头注入
+- Art‑template 模板引擎渲染
+
+### 优秀开发体验
+
+- 多环境配置隔离（`.env.dev` / `.env.prd`）
+- 标准化统一返回体（success / fail）
 - Zod 参数校验中间件
-- 全局异常处理
-- 工具函数库
+- 全局异常捕获兜底
+- 内置通用工具函数库
 
 ## 目录结构
 
 ```
 |- app/
-|   |- common/            # 公共路由
-|   |- helper/            # 辅助函数
-|   |- middleware/        # 应用中间件
-|   |- modules/           # 业务模块
-|   |   |- <module>/
+|   |- common/            # 公共业务路由
+|   |- helper/            # 全局辅助工具函数
+|   |- middleware/        # 应用级中间件
+|   |- modules/           # 业务模块根目录
+|   |   |- <module>/      # 单个业务模块
 |   |       |- controller/
 |   |       |- service/
 |   |       |- middleware/
 |   |       |- router.js
-|   |- router.js
-|- config/                # 框架常量与环境加载
-|- data/                  # 运行数据
-|- doc/                   # 文档
-|- lang/                  # i18n 资源（zh-CN/en-US/...）
-|- public/                # 静态资源
-|- view/                  # 模板视图
-|- app.js                 # 业务入口
-|- .env.dev / .env.prd    # 环境变量
-|- pm2.json               # 进程管理
+|   |- router.js          # 根路由聚合
+|- config/                # 框架配置、环境变量加载
+|- data/                  # 运行时持久化数据目录
+|- doc/                   # 项目文档
+|- lang/                  # i18n 语言资源(zh‑CN/en‑US/...)
+|- public/                # 前端静态资源
+|- view/                  # 视图模板文件
+|- app.js                 # 项目业务入口
+|- .env.dev / .env.prd    # 环境配置文件
+|- pm2.json               # PM2 进程部署配置
 ```
 
 ## 快速开始
 
-```javascript
+```
 import Chan from "chanjs";
 
 const chan = new Chan();
 
-// 注册启动前置钩子
+// 注册启动前置钩子（事件、定时任务等初始化）
 chan.beforeStart(() => {
-  // 此处可注册事件监听、定时任务等
 });
 
 await chan.start();        // 加载配置、i18n、数据库、中间件、路由
@@ -87,65 +105,65 @@ chan.run((port) => {       // 启动 HTTP 服务
 });
 ```
 
-## 核心能力
+## 核心能力详解
 
-### 1. 日志系统（pino）
+### 1. 日志系统（Pino）
 
-dev 环境彩色输出，prod 环境输出 JSON（pm2 捕获 stdout）。API 完全兼容旧用法。
+开发环境彩色控制台输出；生产环境输出 JSON 结构化日志，适配 PM2 采集。API 向下完全兼容。
 
-```javascript
+```
 import logger, { createLogger } from "chanjs";
 
-// 全局日志
+// 全局日志实例
 logger.info("启动完成");
-logger.error("查询失败", err);   // 自动分离 Error 对象
+logger.error("查询失败", err);   // 自动识别 Error 对象
 
-// 带模块标签的子日志
+// 创建带业务标签的子日志
 const dbLog = createLogger("DB");
 dbLog.warn("慢查询");
 ```
 
-请求日志由 pino-http 自动处理，每个请求生成唯一 `requestId`，业务中通过 `req.log` 输出带 requestId 的日志：
+请求日志由 `pino‑http` 自动接管，每个请求分配唯一 `requestId`，Controller 内可直接携带链路日志：
 
-```javascript
+```
 // 在 Controller 中
 async getUser(req, res) {
-  req.log.info("查询用户详情");  // 自动携带 requestId
-  // ...
+  req.log.info("查询用户详情");  // 日志自动附带 requestId
 }
 ```
 
 ### 2. 事件总线（EventBus）
 
-基于 Node 内置 EventEmitter 的轻量封装，全局单例。
+基于 Node.js 原生 EventEmitter 封装的全局单例事件中心，用于业务解耦。
 
-```javascript
+```
 import { event, EventBus } from "chanjs";
 
-// 全局实例
+// 使用全局事件实例
 const off = event.on("user.login", (uid) => {
   logger.info(`用户 ${uid} 登录`);
 });
 event.emit("user.login", 1001);
-off();  // 取消监听
+off();  // 解绑监听
 
-// 独立实例（隔离场景）
+// 创建独立隔离的事件实例
 const localBus = new EventBus();
 ```
 
-> 详见 [doc/07-事件系统EventBus.md](./doc/07-事件系统EventBus.md)
+> 
+> 详细文档：[doc/07‑事件系统EventBus.md](./doc/07%E2%80%91%E4%BA%8B%E4%BB%B6%E7%B3%BB%E7%BB%9FEventBus.md)
 
 ### 3. 定时任务（Task）
 
-基于 node-cron 封装，支持 cron 表达式校验、异常自动捕获、优雅停机。
+基于 node‑cron 封装，内置 cron 表达式校验、任务异常捕获、优雅停机回收。
 
-```javascript
+```
 import Chan from "chanjs";
 
 const chan = new Chan();
 
 chan.beforeStart(() => {
-  // 注册定时任务（启动时自动开始）
+  // 注册定时任务，框架启动后自动运行
   chan.task.add("clear-log", "0 3 * * *", async () => {
     await chan.db.raw("DELETE FROM logs WHERE created_at < NOW() - INTERVAL 7 DAY");
   });
@@ -157,7 +175,7 @@ chan.run();
 
 ### 4. 国际化（i18next）
 
-启动时扫描 `lang/` 目录加载全部语言资源到内存，运行时 O(1) 查找。
+服务启动时一次性扫描加载 `lang/` 全部语言资源至内存，运行时 O(1) 快速读取翻译文本。
 
 ```
 lang/
@@ -167,7 +185,7 @@ lang/
     common.json    # { "user.welcome": "Welcome, {{name}}" }
 ```
 
-```javascript
+```
 import { initLang } from "chanjs";
 
 const i18n = await initLang("zh-CN");
@@ -176,86 +194,107 @@ i18n.t("user.welcome", { name: "张三" });  // → "欢迎，张三"
 
 ### 5. 数据库（Knex + 慢查询监控）
 
-多连接管理，自动慢查询与错误监控。
+支持多数据库连接管理，自动开启慢查询与 SQL 异常监控。
 
-```javascript
-// 框架启动时根据 config.db 自动注册连接
-// 业务中通过 this.db 或 getApp().db 访问默认连接
+```
+// 框架启动自动读取 config.db 注册数据库连接
+// 业务代码内可通过 this.db / getApp().db 获取默认连接
 
-// 运行时调整慢查询阈值
-chan.dbManager.setSlowThreshold(500);  // 500ms
+// 运行时动态调整慢查询告警阈值（毫秒）
+chan.dbManager.setSlowThreshold(500);
 ```
 
-### 6. 组件容器（跨模块按需获取）
+### 6. 组件容器 · 双通道跨模块调用
 
-Controller / Service 都继承 `Container`，自带 `this.get()`，按「模块名 + 文件名」动态加载组件。
-成功永久缓存；缺失不缓存（文件新增后立即感知）。
+Controller / Service 继承容器基类，内置 `this.get()` 方法，通过「模块名 + 组件名」动态加载跨模块业务组件。
 
-```javascript
-// 同模块获取 Service（Service 容器默认 type=service）
+> 
+> 加载成功后实例永久缓存；组件文件缺失不缓存，新增文件无需重启即可识别。
+
+```
+// 同模块调用 Service
 const cat = await this.get("book", "BookCategory");
 
-// 跨模块获取其他模块的 Service（Controller 容器默认 type=controller，取 service 需传第三参）
+// 跨模块调用 Service（推荐，HMVC 双通道‑服务通道）
 const book = await this.get("book", "Book", "service");
 const special = await this.get("cms", "Special", "service");
 ```
 
-- 存在返回实例并永久缓存；缺失返回 `null`，下次实时感知。
-- 自带非法名称 / 路径越界安全校验。
-- 异步方法，需 `await`。
-- 跨模块协作优先用 `get`，避免手写 `../../` 相对路径 import。
+- 返回实例或 null，异步调用必须 await
+- 内置名称校验、路径越界安全防护
+- 跨模块业务复用优先使用容器调用，摒弃超长相对路径 import
 
-### HMVC 定位（标准实现）
+#### HMVC 标准实现说明
 
-教科书把「Controller 嵌套调用 Controller + 运行时子请求」当作 HMVC 的标准，其实是把**实现手段**当成了标准，是片面的。
-HMVC 的本质是**分层 + 模块自治 + 跨模块复用**。Chanjs 抓住本质，支持**双通道跨模块协作**：
+传统教程常将「控制器嵌套发起子 HTTP 请求」当作 HMVC 的标准，该方式混淆了**实现手段**和架构本质。
 
-- `await this.get("模块", "Controller")` —— 获取其他模块的 Controller（默认本容器类型）
-- `await this.get("模块", "Service", "service")` —— 获取其他模块的 Service（推荐路径）
+> 
+> HMVC 的核心 = 分层解耦 + 模块自治 + 跨模块业务复用。
 
-因此 Chanjs 是更贴合 HMVC 本质的**标准 HMVC 实现**，教科书把手段当标准才是过时的变体。
+ChanJS 提供双通道协作模式，回归 HMVC 本质：
+
+1. 控制器通道：`await this.get("模块", "Controller")`
+2. 服务通道（推荐）：`await this.get("模块", "Service", "service")`
 
 ### 7. 优雅停机
 
-统一处理 SIGTERM / SIGINT / SIGQUIT，按序释放资源：
+统一监听 `SIGTERM / SIGINT / SIGQUIT` 退出信号，按顺序逐级释放资源：
 
 ```
 HTTP 服务 → 定时任务 → 缓存存储 → 数据库连接 → 事件总线
 ```
 
-单个资源关闭失败不阻断其他资源，超时强制退出。
+单个资源关闭失败不会阻断其余回收流程，超时后进程强制退出。
+
+## 环境变量配置
 
-## 环境变量
+| 变量 | 说明 | 默认值 |
+| --- | --- | --- |
+| `NODE_ENV` | 运行环境标识(dev/prd) | dev |
+| `PORT` | HTTP 监听端口 | 3000 |
+| `LOCALE` | 默认语言 | zh‑CN |
+| `LOG_LEVEL` | 日志输出级别 | dev:debug / prd:info |
+| `TRUSTED_PROXIES` | 信任反向代理网段 | loopback |
+| `SHUTDOWN_TIMEOUT` | 优雅停机超时时间(ms) | 5000 |
+| `REDIS_ENABLED` | 是否开启 Redis | false |
 
-| 变量 | 说明 | 默认 |
-|------|------|------|
-| `NODE_ENV` | 环境（dev/prd） | dev |
-| `PORT` | HTTP 端口 | 3000 |
-| `LOCALE` | 默认语言 | zh-CN |
-| `LOG_LEVEL` | 日志级别 | dev:debug / prd:info |
-| `TRUSTED_PROXIES` | 信任代理 | loopback |
-| `SHUTDOWN_TIMEOUT` | 停机超时(ms) | 5000 |
-| `REDIS_ENABLED` | 启用 Redis | false |
+## 项目依赖清单
 
-## 依赖
+### 运行依赖
 
-### 运行时依赖
 - express ^5.2.1
 - knex ^3.2.10
 - pino ^9.5.0
-- pino-http ^10.3.0
+- pino‑http ^10.3.0
 - i18next ^24.2.0
-- node-cron ^3.0.3
-- art-template ^4.13.4
+- node‑cron ^3.0.3
+- art‑template ^4.13.4
 - mysql2 ^3.22.3
 - ioredis ^5.4.6
 
 ### 开发依赖
-- pino-pretty ^11.3.0
+
+- pino‑pretty ^11.3.0
 
 ### 可选 Peer 依赖
-- zod ^4.4.3（参数校验）
 
-## License
+- zod ^4.4.3（接口参数校验）
+
+## Hono 高性能版本
+
+[chanjs‑hono](https://www.npmjs.com/package/chanjs%E2%80%91hono) 为 ChanJS 衍生高性能分支，基于 Hono，API 保持一致，性能更强。
+
+```
+npm install chanjs-hono
+```
+
+## 文档 & 生态资源
+
+- ChanJS官网文档：[ChanJS](https://chancms.top/)
+- ChanJS-Hono官网文档：[ChanJS-Hono](https://chancms.top/)
+- ChanJS-cli官方脚手架：[ChanJS-cli](https://chancms.top/)
+- ChanCMS官方开源 CMS：[ChanCMS](https://chancms.top/)
+
+## 开源协议
 
 ISC

package/core/Repository.js

@@ -10,6 +10,14 @@ import {
 const SORT_FIELD_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 const OPERATORS = { $like:'like', $gt:'>', $gte:'>=', $lt:'<', $lte:'<=', $ne:'<>' };
 
+/**
+ * 分页/分页相关保留字，不可能是合法的 WHERE 过滤列。
+ * 某些 controller 会把整个 req.query（含 pageSize/current/page）透传给 Repository.query，
+ * 若不加拦截会被 applyQuery 当成过滤字段拼进 SQL（如 `where pageSize = '20'`），
+ * 既报错又泄露分页语义。统一在此剥离，避免每个接口各自兜底。
+ */
+const PAGINATION_KEYS = new Set(['current', 'page', 'pageNum', 'pageSize', 'limit', 'offset']);
+
 /** 查询条件是否存在至少一个合法字段 */
 const hasValidQueryField = query =>
   Object.keys(query).some(f => SORT_FIELD_REGEX.test(f));
@@ -34,6 +42,7 @@ const guardInvalidQuery = query => {
  */
 function applyQuery(dbQuery, query) {
   for (const [field, val] of Object.entries(query)) {
+    if (PAGINATION_KEYS.has(field)) continue; // 分页参数不是过滤列，直接跳过
     if (!SORT_FIELD_REGEX.test(field)) {
       logger.warn(`[Repository] 非法查询字段：${field}`);
       continue;
@@ -88,6 +97,8 @@ function applySelectAndSort(q, fields, sort) {
 /**
  * 数据访问基类，封装通用CRUD操作
  * 继承 BaseComponent 获得 app/config/db 快捷访问，不绑定组件加载职责
+ * 防御设计：所有入口统一经 _guard 校验「数据库可用性 + 查询条件合法性」，
+ * 再进入 SQL 构造层，避免各方法重复书写 `_checkDB + guardInvalidQuery` 样板。
  */
 class Repository extends BaseComponent {
   constructor(table=null, dbName=null, opts={}) {
@@ -116,6 +127,19 @@ class Repository extends BaseComponent {
     if (!this.db) throw new Error("Database connection not available");
   }
 
+  /**
+   * 统一防御守卫：数据库可用性 + 查询条件合法性（fail-closed）。
+   * 查询/统计/存在性等方法的入口统一先过此守卫，替代各方法开头的 `_checkDB()+guardInvalidQuery()` 重复样板。
+   * 空 query（如 {}）合法放行；仅 db 不可用时直接抛异常，保证后端配置错误尽早暴露。
+   * @param {object} [opts={}]
+   * @param {object} [opts.query={}] 查询条件；为空对象或缺省时仅校验数据库连接
+   * @returns {null | {success:false,code:number,msg:string,data:object}} 校验通过返回 null，否则返回错误体（调用方应 return 该值）
+   */
+  _guard({ query = {} } = {}) {
+    this._checkDB();
+    return guardInvalidQuery(query);
+  }
+
   /** 统一构建查询实例（子类可重写以扩展过滤逻辑） */
   _buildBaseQuery({ query = {}, sort = {}, fields = [] } = {}) {
     this._checkDB();
@@ -139,16 +163,16 @@ class Repository extends BaseComponent {
 
   /** 查询全部，默认上限1000条 */
   async all({ query={}, sort={}, fields=[], limit=1000 }={}) {
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    const err = this._guard({ query });
+    if (err) return err;
     const list = await this._buildBaseQuery({query,sort,fields}).limit(limit);
     return { success:true, code:CODE_OK, msg:"查询成功", data: list };
   }
 
   /** 分页偏移查询 */
   async find({ query={}, sort={}, fields=[], limit, offset }={}) {
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    const err = this._guard({ query });
+    if (err) return err;
     let q = this._buildBaseQuery({query,sort,fields});
     typeof offset === 'number' && (q = q.offset(offset));
     typeof limit === 'number' && (q = q.limit(limit));
@@ -157,8 +181,8 @@ class Repository extends BaseComponent {
 
   /** 查询单条记录 */
   async findOne({ query={}, fields=[] }={}) {
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    const err = this._guard({ query });
+    if (err) return err;
     const row = await this._buildBaseQuery({query,fields}).first();
     if (!row) return { success:false, code:CODE_NOT_FOUND, msg:"记录不存在", data:null };
     return { success:true, code:CODE_OK, msg:"查询成功", data: row };
@@ -226,11 +250,10 @@ class Repository extends BaseComponent {
     return { success:true, code:CODE_OK, msg:"更新成功", data:{ affectedRows:rows } };
   }
 
-  /** 根据ID更新，返回更新后完整数据 */
+  /** 根据ID更新，返回更新后完整数据（复用 update 走统一 applyQuery 校验） */
   async updateById(id, data={}) {
-    this._checkDB();
     if (!id || !Object.keys(data).length) return { success:false, code:CODE_PARAM_INVALID, msg:"参数无效", data:{} };
-    await this.db(this.tableName).where({id}).update(this.#formatDate(data));
+    await this.update({ query: { id }, data });
     return this.findById(id);
   }
 
@@ -269,9 +292,8 @@ class Repository extends BaseComponent {
    * @returns {Promise<{success:boolean,code:number,msg:string,data:object}>}
    */
   async _doPaginate({ current=1, pageSize=10, query={}, sort={}, field=[] }={}) {
-    this._checkDB();
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    const err = this._guard({ query });
+    if (err) return err;
     // 页码边界保护：current<=0 会生成负 offset 让 MySQL 直接语法报错
     const currentPage = Math.max(1, Math.floor(Number(current) || 1));
     const size = Math.min(Math.max(pageSize, 1), this.limit);
@@ -301,20 +323,68 @@ class Repository extends BaseComponent {
     return this._doPaginate(params);
   }
 
+  /**
+   * 基于游标的深分页查询（keyset pagination），替代 offset 深分页。
+   *
+   * 适用场景：大表（数万行+）且需翻到很后面的分页。
+   * offset 深分页痛点：`LIMIT 100000, 20` 需先扫描并丢弃前 10 万行，越深越慢；
+   * keyset 直接用 `WHERE id > 上一页最后一条的 id ORDER BY id LIMIT 20` 精准定位，与页码无关，常数级耗时。
+   *
+   * 返回体不依赖 offset/totalPages，浏览器端用「加载更多」或「下一页」+ nextCursor 驱动。
+   *
+   * @param {object} [params]
+   * @param {object} [params.query={}] 过滤条件（同 query()）
+   * @param {number} [params.pageSize=20] 每页条数（受 this.limit 上限约束）
+   * @param {string} [params.cursorField='id'] 游标字段，须为稳定唯一且可排序的列（默认主键 id；也支持 created_at 等，但注意并列值会导致漏数据）
+   * @param {string|number|null} [params.cursorValue=null] 上一页最后一条的 cursorField 值；null 表示首页
+   * @param {'asc'|'desc'} [params.direction='desc'] 排序方向（取新纪录通常 desc）
+   * @param {string[]} [params.fields=[]] 白名单字段
+   * @returns {Promise<{success:boolean,code:number,msg:string,data:{list:Array,nextCursor:number|string|null,hasMore:boolean,cursorField:string}}>}
+   *
+   * @example
+   * // 首页（取最新 20 条）
+   * const p1 = await repo.cursorPage({ query:{cid:5}, pageSize:20, direction:'desc' });
+   * const nextCursor = p1.data.nextCursor;
+   * // 下一页（携带上一页末尾游标，常数级耗时，即使翻到第 1 万页也一样快）
+   * const p2 = await repo.cursorPage({ query:{cid:5}, pageSize:20, direction:'desc', cursorValue:nextCursor });
+   */
+  async cursorPage({ query={}, pageSize=20, cursorField='id', cursorValue=null, direction='desc', fields=[] }={}) {
+    const err = this._guard({ query });
+    if (err) return err;
+    // 游标字段与方向必须白名单校验，防 SQL 注入（排序字段会被直接拼进 ORDER BY）
+    if (!SORT_FIELD_REGEX.test(cursorField)) {
+      logger.warn(`[Repository] 非法游标字段：${cursorField}`);
+      return { success:false, code:CODE_PARAM_INVALID, msg:"非法排序字段", data:null };
+    }
+    const dir = String(direction).toLowerCase() === 'asc' ? 'asc' : 'desc';
+    const size = Math.min(Math.max(Number(pageSize) || 1, 1), this.limit);
+
+    let q = this._buildBaseQuery({ query, sort: { [cursorField]: dir }, fields });
+    // 游标定位：大于/小于上一页末尾的游标值，天然避免重复与跳跃
+    if (cursorValue !== null && cursorValue !== undefined && cursorValue !== "") {
+      q = dir === 'asc' ? q.where(cursorField, '>', cursorValue) : q.where(cursorField, '<', cursorValue);
+    }
+    const list = await q.limit(size);
+
+    const last = list.length ? list[list.length - 1] : null;
+    const nextCursor = last ? last[cursorField] : null;
+    // 恰好取满 size 条时无法确定是否还有更多（边界处需多取一条判断更严谨，这里退化为 hasMore=满页）
+    const hasMore = list.length === size;
+    return { success:true, code:CODE_OK, msg:"查询成功", data:{ list, nextCursor, hasMore, cursorField } };
+  }
+
   /** 统计符合条件记录行数 */
   async count(query={}) {
-    this._checkDB();
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    const err = this._guard({ query });
+    if (err) return err;
     const res = await applyQuery(this.db(this.tableName), query).count("* as total").first();
     return { success:true, code:CODE_OK, msg:"统计成功", data:{ count: Number(res?.total ?? 0) } };
   }
 
   /** 判断查询条件下记录是否存在 */
   async exists(query={}) {
-    this._checkDB();
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    const err = this._guard({ query });
+    if (err) return err;
     const row = await applyQuery(this.db(this.tableName), query).first();
     return { success:true, code:CODE_OK, msg:"检查成功", data:{ exists: !!row } };
   }
@@ -326,8 +396,8 @@ class Repository extends BaseComponent {
       logger.warn(`[Repository] 非法联表/字段：${joinTable}/${localField}/${foreignField}`);
       return { success: false, code: CODE_PARAM_INVALID, msg: "非法联表或字段", data: null };
     }
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    const err = this._guard({ query });
+    if (err) return err;
     const select = fields.length
       ? fields.filter(f => SORT_FIELD_REGEX.test(f) || f === '*')
       : [`${this.tableName}.*`];
@@ -361,4 +431,4 @@ class Repository extends BaseComponent {
   }
 }
 
-export default Repository;
+export default Repository;

package/package.json

@@ -1,8 +1,8 @@
 {
   "type": "module",
   "name": "chanjs",
-  "version": "2.7.11",
-  "description": "chanjs基于express5 纯js研发的轻量级mvc框架。",
+  "version": "2.7.13",
+  "description": "chanjs基于 Node.js + Express 5 的标准 HMVC 框架（NHMVC），纯 JavaScript（ESM）开发。",
   "main": "index.js",
   "module": "index.js",
   "keywords": [