更新文档

Author: rockyshi1993

README.md

@@ -8,6 +8,7 @@
 - [快速开始](#quick-start)
 - [深度分页（聚合版，Mongo）](#deep-pagination-agg)
 - [统一 findPage：游标 + 跳页 + offset + totals](#findpage-unified)
+- [返回耗时（meta）](#返回耗时meta)
 - [缓存与失效](#cache)
   - [缓存配置](#缓存配置)
   - [缓存行为与细节](#缓存行为与细节)
@@ -16,6 +17,8 @@
   - [invalidate(op) 用法](#invalidate)
 - [跨库访问注意事项](#cross-db)
 - [说明](#notes)
+- [事件（Mongo）](#事件mongo)
+- [健康检查与事件（Mongo）](#健康检查与事件mongo)
 
 <a id='status'></a>
 ## 状态（速览）
@@ -566,6 +569,53 @@ const msq = await new MonSQLize({
 提示：也可在上层自行构建 MultiLevelCache 并作为 `cache` 直接注入（需 `require('monsqlize/lib/multi-level-cache')`）。
 
 
+## 返回耗时（meta）
+- 支持在所有读 API 上按次返回耗时与元信息（opt-in，不改默认返回类型）。
+- 使用方法：在 options 中传入 `meta: true` 或 `meta: { level: 'sub', includeCache: true }`。
+  - findOne/find/count/find：当 `meta` 为真时返回 `{ data, meta }`；不传则维持原返回（对象/数组/数字）。
+  - findPage：当 `meta` 为真时在返回对象上附加 `meta` 字段；`level:'sub'` 时返回每个 hop/offset 的子步骤耗时。
+
+示例：
+```js
+// 单条查询：返回耗时
+const { data, meta } = await coll.findOne({ query:{ name: 'Alice' }, cache: 2000, maxTimeMS: 1500, meta: true });
+console.log(meta.durationMs);
+
+// 分页：总耗时
+const page = await coll.findPage({ query:{ status:'paid' }, sort:{ createdAt:-1,_id:1 }, limit:20, page:37, meta:true });
+console.log(page.meta.durationMs);
+
+// 分页：子步骤耗时（跳页时可见每个 hop 的耗时）
+const page2 = await coll.findPage({ query:{ status:'paid' }, sort:{ createdAt:-1,_id:1 }, limit:20, page:128, jump:{ step:20 }, meta:{ level:'sub', includeCache:true } });
+console.table(page2.meta.steps);
+```
+
+> 说明：
+> - 默认不返回 meta，需显式开启；开销很小，仅一次时间戳与对象组装。
+> - includeCache 仅包含去敏维度（如 cacheTtl 等，具体依实现）。
+
+## 事件（Mongo）
+- 事件基于 Node.js EventEmitter，进程内有效：
+  - `connected`: `{ type, db, scope, iid? }`
+  - `closed`: `{ type, db, iid? }`
+  - `error`: `{ type, db, error, iid? }`
+  - `slow-query`: `{ op, ns, durationMs, startTs, endTs, maxTimeMS, ... }`（去敏）
+  - `query`（可选）：每次读操作完成后触发；需在构造 defaults 中开启 `metrics.emitQueryEvent=true`。
+- 实例还暴露：`on/off/once/emit`。
+
+用法示例：
+```js
+const msq = new MonSQLize({ type:'mongodb', databaseName:'example', config:{ uri:'mongodb://localhost:27017' }, defaults:{ metrics:{ emitQueryEvent:false } } });
+msq.on('connected', info => console.log('[connected]', info));
+msq.on('closed', info => console.log('[closed]', info));
+msq.on('error', info => console.error('[error]', info));
+msq.on('slow-query', meta => console.warn('[slow-query]', meta));
+// 可选：开启 query 事件
+// const msq = new MonSQLize({ ..., defaults:{ metrics:{ emitQueryEvent:true } } });
+msq.on('query', meta => console.log('[query]', meta));
+await msq.connect();
+```
+
 ## 健康检查与事件（Mongo）
 - 健康检查：`await msq.health()` 返回 `{ status: 'up'|'down', connected, defaults, cache?, driver }` 摘要视图。
 - 事件钩子：

example/mongodb.js

@@ -88,14 +88,15 @@ const MonSQLize = require('../lib/index.js');
         // });
         //
         // // 1) 基础查询：findOne
-        // const one = await coll.findOne({
-        //     query: { status: 'paid' },
-        //     projection: ['_id', 'status', 'createdAt'],
-        //     sort: { createdAt: -1 },          // -1 降序，1 升序
-        //     cache: 2000,                      // 启用 2s 缓存（TTL 毫秒）
-        //     maxTimeMS: 1500,
-        // });
-        // console.log('[findOne] =>', one);
+        const { data, meta } = await coll.findOne({
+            query: { status: 'paid' },
+            projection: ['_id', 'status', 'createdAt'],
+            sort: { createdAt: -1 },          // -1 降序，1 升序
+            cache: 2000,                      // 启用 2s 缓存（TTL 毫秒）
+            maxTimeMS: 1500,                  // 超时
+            meta: true                        // 返回详细耗时信息
+        });
+        console.log('[findOne] =>', data, meta);
 
         // // 2) 基础查询：find（列表）
         // const list = await coll.find({
@@ -210,6 +211,41 @@ const MonSQLize = require('../lib/index.js');
         // 警告：dropCollection 会删除数据，请谨慎使用
         // const dropped = await coll.dropCollection();
         // console.log('dropCollection =>', dropped);
+
+        // 9.1) 演示跳页功能 - 模拟跳转到特定页面
+        // console.log('\n--- 跳页演示 ---');
+        //
+        // // 获取总数（用于计算总页数）
+        // const totalCount = await coll.count({
+        //     query: { status: 'paid' },
+        //     cache: 2000
+        // });
+        // const pageSize = 2;
+        // const totalPages = Math.ceil(totalCount / pageSize);
+        //
+        // console.log(`总记录数: ${totalCount}, 每页: ${pageSize}, 总页数: ${totalPages}`);
+        //
+        // // 跳转到最后一页的逻辑（实际应用中可能需要更复杂的游标计算）
+        // if (totalPages > 2) {
+        //     console.log('\n--- 尝试获取最后一页 ---');
+        //     // 注意：真实的跳页可能需要维护页码与游标的映射关系
+        //     // 这里只是演示概念，实际应用中建议：
+        //     // 1. 缓存关键页面的游标
+        //     // 2. 或使用传统的 skip/limit 方式作为跳页的补充
+        //
+        //     const lastPageQuery = await coll.find({
+        //         query: { status: 'paid' },
+        //         sort: { createdAt: -1, _id: 1 },
+        //         limit: pageSize,
+        //         skip: (totalPages - 1) * pageSize, // 使用 skip 跳到最后一页
+        //         cache: 1000,
+        //     });
+        //
+        //     console.log(`最后一页找到 ${lastPageQuery.length} 条记录`);
+        //     lastPageQuery.forEach((item, index) => {
+        //         console.log(`  ${index + 1}. 订单金额: ${item.amount}, 创建时间: ${item.createdAt}`);
+        //     });
+        // }
     }
     catch (e) {
         // 统一错误处理：

lib/common/runner.js

@@ -2,19 +2,54 @@ const CacheFactory = require('../cache');
 const { withSlowQueryLog } = require('./log');
 
 /**
- * 统一执行器：包装缓存与慢日志
+ * 统一执行器：包装缓存与慢日志，并可选返回 meta（耗时等）与发出 query 事件
  * @param {import('../..').CacheLike|any} cache
  * @param {{iid:string, type:string, db:string, collection:string}} nsAll
  * @param {import('../..').LoggerLike} logger
  * @param {object} defaults
- * @param {{ keyBuilder?: (op:string, options:any)=>any, slowLogShaper?: (options:any)=>object, onSlowQueryEmit?: (meta:any)=>void }} hooks
+ * @param {{ keyBuilder?: (op:string, options:any)=>any, slowLogShaper?: (options:any)=>object, onSlowQueryEmit?: (meta:any)=>void, onQueryEmit?: (meta:any)=>void }} hooks
  */
 function createCachedRunner(cache, nsAll, logger, defaults, hooks = {}) {
     const cached = CacheFactory.createCachedReader(cache, nsAll);
-    return (op, options, exec) => {
+    return async (op, options = {}, exec) => {
         const optsForKey = typeof hooks.keyBuilder === 'function' ? hooks.keyBuilder(op, options || {}) : (options || {});
         const runExec = () => cached(op, optsForKey, exec);
-        return withSlowQueryLog(logger, defaults, op, { db: nsAll.db, coll: nsAll.collection, iid: nsAll.iid, type: nsAll.type }, options, runExec, hooks.slowLogShaper, hooks.onSlowQueryEmit);
+        const ns = { db: nsAll.db, coll: nsAll.collection, iid: nsAll.iid, type: nsAll.type };
+        const t0 = Date.now();
+        let res;
+        let err;
+        try {
+            res = await withSlowQueryLog(logger, defaults, op, ns, options, runExec, hooks.slowLogShaper, hooks.onSlowQueryEmit);
+        } catch (e) {
+            err = e;
+            throw e;
+        } finally {
+            const endTs = Date.now();
+            const durationMs = endTs - t0;
+            const wantMeta = !!options.meta;
+            const meta = {
+                op,
+                ns,
+                startTs: endTs - durationMs,
+                endTs,
+                durationMs,
+                maxTimeMS: options && options.maxTimeMS,
+            };
+            if (err) meta.error = { code: err.code, message: String(err && (err.message || err)) };
+            // emit query event if enabled
+            if (defaults && defaults.metrics && defaults.metrics.emitQueryEvent && typeof hooks.onQueryEmit === 'function') {
+                try { hooks.onQueryEmit(meta); } catch (_) {}
+            }
+            if (wantMeta) {
+                // 按方法统一返回：findPage 在对象上挂 meta，其它读 API 返回 { data, meta }
+                if (op === 'findPage' && res && typeof res === 'object') {
+                    res.meta = meta;
+                } else {
+                    res = { data: res, meta };
+                }
+            }
+        }
+        return res;
     };
 }
 

lib/mongodb/index.js

@@ -36,6 +36,7 @@ module.exports = class {
         // 事件：connected/closed/error/slow-query
         this._emitter = new EventEmitter();
         this.on = this._emitter.on.bind(this._emitter);
+        this.once = this._emitter.once.bind(this._emitter);
         this.off = (this._emitter.off ? this._emitter.off.bind(this._emitter) : this._emitter.removeListener.bind(this._emitter));
         this.emit = this._emitter.emit.bind(this._emitter);
     }
@@ -133,7 +134,8 @@ module.exports = class {
         }, this.logger, this.defaults, {
             keyBuilder: mongoKeyBuilder,
             slowLogShaper: mongoSlowLogShaper,
-            onSlowQueryEmit: (meta) => { try { this.emit && this.emit('slow-query', meta); } catch(_) {} }
+            onSlowQueryEmit: (meta) => { try { this.emit && this.emit('slow-query', meta); } catch(_) {} },
+            onQueryEmit: (meta) => { try { this.emit && this.emit('query', meta); } catch(_) {} }
         });
         return {
             /** 返回当前访问器的命名空间信息 */