monsqlize 1.1.1 → 1.1.4

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-01-27
+> **最后更新**: 2026-02-09
 
 ---
 
@@ -9,6 +9,9 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [v1.1.4](./changelogs/v1.1.4.md) | 2026-02-09 | 🎉 重大功能：通用函数缓存 - 52个测试 (100%通过) + 多层缓存 delPattern 修复 | [查看](./changelogs/v1.1.4.md) |
+| [v1.1.3](./changelogs/v1.1.3.md) | 2026-02-03 | 📚 文档完善：多连接池文档优化 + 健康检查详解 + 验证体系规范 | [查看](./changelogs/v1.1.3.md) |
+| [v1.1.2](#v112---日志优化) | 2026-01-27 | 🔧 优化：ObjectId 转换日志默认静默 + Saga 日志修复 | [查看](#v112---日志优化) |
 | [v1.1.1](#v111---objectid-跨版本兼容) | 2026-01-27 | 🔧 Bug修复：新增跨版本 ObjectId 兼容性（支持 mongoose bson@4.x/5.x）| [查看](#v111---objectid-跨版本兼容) |
 | [v1.1.0](./changelogs/v1.1.0.md) | 2026-01-21 | 🎉 重大更新：新增49个操作符，实现100% MongoDB操作符支持（122/122）| [查看](./changelogs/v1.1.0.md) |
 | [v1.0.9](./changelogs/v1.0.9.md) | 2026-01-19 | 🎉 重大功能：统一表达式系统 - 67个操作符 + 107个测试 (100%通过) | [查看](./changelogs/v1.0.9.md) |
@@ -32,8 +35,123 @@
 
 ---
 
+## 文档与验证改进
+
+### v1.1.3 - 文档完善与验证体系 📚
+
+**发布日期**: 2026-02-03  
+**版本类型**: 文档优化 + 验证体系完善  
+**重要性**: ⭐⭐⭐⭐
+
+#### 核心改进
+
+**多连接池文档优化**:
+- ✅ 修复代码实现（ConnectionPoolManager 导出、selectPool 返回值完整）
+- ✅ 验证 100% 通过（76 项功能验证）
+- ✅ 文档精简（2082 行 → 1970 行，-5%）
+- ✅ 目录格式统一、删除重复内容
+
+**健康检查机制详解**:
+- ✅ 新增文档 `docs/multi-pool-health-check.md`
+- ✅ 详细说明工作原理、问题发现、问题处理
+- ✅ 提供 3 种运维通知方式（日志、监控、事件）
+- ✅ 集成方案（Prometheus、企业微信/钉钉、邮件）
+- ✅ 完整的生产环境告警系统代码
+
+**验证体系规范**:
+- ✅ 文档规范说明（目录格式、内容规范、禁止内容）
+- ✅ 文档更新流程（4 步）
+- ✅ 引用关系规范（建立原则、禁止情况、判断流程）
+- ✅ 验证通过标准（6 项）
+
+#### 影响范围
+
+- **文档文件**: 3 个（multi-pool.md、multi-pool-health-check.md、README.md）
+- **代码文件**: 2 个（lib/index.js、ConnectionPoolManager.js）
+- **验证文件**: 5 个（清单、脚本、报告）
+- **规范文件**: 1 个（validation/README.md）
+
+#### 升级说明
+
+**无破坏性变更**，现有代码无需修改：
+```bash
+npm update monsqlize
+```
+
+📖 **详细变更**: [查看完整变更日志](./changelogs/v1.1.3.md)
+
+---
+
 ## 里程碑版本
 
+### v1.1.2 - 日志优化 🔧
+
+**发布日期**: 2026-01-27  
+**重要性**: ⭐⭐⭐
+
+**优化内容**:
+
+1. **ObjectId 转换日志默认静默**
+   - ✅ **默认完全静默**: 不输出任何 ObjectId 转换日志
+   - ✅ **用户反馈驱动**: 根据用户反馈，转换日志无实际作用
+   - ✅ **可选启用**: 支持按需启用摘要或详细日志
+   - ✅ **生产友好**: 减少日志量，避免日志污染
+
+2. **Saga 日志修复**
+   - ✅ **修复误导性日志**: 正确区分内存缓存和 Redis 缓存
+   - ✅ **准确识别**: 通过检测 `cache.keys` 和 `cache.publish` 方法识别 Redis
+   - ✅ **日志准确**: 内存缓存显示"使用内存缓存"，Redis 显示"使用 Redis 存储"
+
+**配置选项**:
+
+```javascript
+// 默认配置（完全静默）
+const msq = new MonSQLize({
+  type: 'mongodb',
+  config: { uri: 'mongodb://localhost:27017' }
+});
+// ✅ 无任何 ObjectId 转换日志
+
+// 启用摘要日志（调试用）
+const msq = new MonSQLize({
+  type: 'mongodb',
+  config: { uri: 'mongodb://localhost:27017' },
+  autoConvertObjectId: {
+    silent: false  // 关闭静默
+  }
+});
+// 输出：[DEBUG] Converted 15 cross-version ObjectIds
+
+// 启用详细日志（深度调试）
+const msq = new MonSQLize({
+  type: 'mongodb',
+  config: { uri: 'mongodb://localhost:27017' },
+  autoConvertObjectId: {
+    silent: false,
+    verbose: true
+  }
+});
+// 输出：每个 ObjectId 都有一条日志
+```
+
+**效果对比**:
+
+| 模式 | silent | verbose | 日志输出 | 适用场景 |
+|------|--------|---------|---------|---------|
+| **静默模式**（默认）✅ | `true` | - | 无 | 生产环境、日常开发 |
+| **摘要模式** | `false` | `false` | 1条摘要 | 需要了解转换情况时 |
+| **详细模式** | `false` | `true` | N条详情 | 深度调试、排查问题 |
+
+**修改的文件**:
+- `lib/utils/objectid-converter.js`: 添加 `silent` 配置，默认 `true`
+- `lib/saga/SagaOrchestrator.js`: 修复 Redis 识别逻辑
+
+**详细文档**: 
+- [ObjectId 日志配置](./docs/objectid-logging-optimization.md)
+- [FAQ - Q3: 如何关闭日志](./docs/objectid-cross-version-faq.md#q3)
+
+---
+
 ### v1.1.1 - ObjectId 跨版本兼容 🔧
 
 **发布日期**: 2026-01-27  

package/README.md

@@ -465,7 +465,92 @@ const user = await users.findOne({ email: 'test@example.com' });
 
 ## 🌟 核心特性
 
-### 0. 🎯 统一表达式系统 🆕 v1.1.0 - 让聚合查询像SQL一样简单
+### 0. 🎨 通用函数缓存 🆕 v1.1.4 - 为任意函数添加缓存
+
+**52个测试（100% 通过）**，为任意异步函数添加缓存能力，性能提升**50000x**！
+
+<table>
+<tr>
+<td width="50%">
+
+**🆕 装饰器模式**
+
+```javascript
+const { withCache } = require('monsqlize');
+
+// 业务函数
+async function getUserProfile(userId) {
+    const user = await msq.collection('users')
+        .findOne({ _id: userId });
+    const orders = await msq.collection('orders')
+        .find({ userId }).toArray();
+    return { user, orders };
+}
+
+// 添加缓存（零侵入）
+const cached = withCache(getUserProfile, {
+    ttl: 300000,  // 5分钟
+    cache: msq.getCache()
+});
+
+// 使用
+await cached('user123');  // 首次：查询数据库
+await cached('user123');  // 再次：从缓存读取 ⚡
+```
+
+</td>
+<td width="50%">
+
+**核心优势**
+
+- ✅ **零侵入** - 装饰器模式，不修改原函数
+- ✅ **自动序列化** - 支持复杂参数（对象、Date等）
+- ✅ **并发控制** - 防止缓存击穿
+- ✅ **双层缓存** - 本地 + Redis，最佳性能
+- ✅ **条件缓存** - 基于返回值决定是否缓存
+- ✅ **统计监控** - 命中率、调用次数等
+- ✅ **命名空间** - 多模块缓存隔离
+- ✅ **TypeScript** - 完整类型支持
+
+**性能提升**:
+- 🚀 复杂业务函数：50000x
+- 🚀 外部 API 调用：200000x
+- 🚀 复杂计算：100000x
+
+</td>
+</tr>
+</table>
+
+**FunctionCache 类管理**:
+
+```javascript
+const { FunctionCache } = require('monsqlize');
+
+const fnCache = new FunctionCache(msq, {
+    namespace: 'myApp',
+    defaultTTL: 60000
+});
+
+// 注册多个函数
+fnCache.register('getUserProfile', getUserProfileFn);
+fnCache.register('getOrderStats', getOrderStatsFn);
+
+// 执行
+await fnCache.execute('getUserProfile', 'user123');
+
+// 失效缓存
+await fnCache.invalidate('getUserProfile', 'user123');
+
+// 查看统计
+const stats = fnCache.getStats('getUserProfile');
+console.log('命中率:', stats.hitRate);
+```
+
+📖 [完整文档](./docs/function-cache.md) · [键生成机制](./docs/function-cache-key-generation.md)
+
+---
+
+### 1. 🎯 统一表达式系统 🆕 v1.1.0 - 让聚合查询像SQL一样简单
 
 **122个操作符（100% MongoDB支持！新增49个函数）**，让MongoDB聚合查询**像写SQL一样简单**！
 
@@ -578,7 +663,7 @@ await orders.aggregate([
 
 ---
 
-### 1. ⚡ 智能缓存系统 - 性能提升 10~100 倍
+### 2. ⚡ 智能缓存系统 - 性能提升 10~100 倍
 
 <table>
 <tr>
@@ -720,7 +805,7 @@ await msq.collection('users').insertOne({ name: 'Alice' });
 
 [完整文档](./docs/sync-backup.md)
 
-### 3. 📦 便利方法 - 减少 60~80% 代码
+### 4. 📦 便利方法 - 减少 60~80% 代码
 
 <table>
 <tr>

package/index.d.ts

@@ -20,6 +20,7 @@ declare module 'monsqlize' {
     import type * as Collection from './types/collection';
     import type * as Model from './types/model';
     import type * as MonSQLizeModule from './types/monsqlize';
+    import type * as FunctionCacheTypes from './types/function-cache';
 
     // ========================================
     // 基础类型
@@ -190,5 +191,15 @@ declare module 'monsqlize' {
     // ========================================
     export import MonSQLize = MonSQLizeModule.MonSQLize;
     export default MonSQLizeModule.MonSQLize;
+
+    // ========================================
+    // 函数缓存（v1.1.4+）
+    // ========================================
+    export import WithCacheOptions = FunctionCacheTypes.WithCacheOptions;
+    export import CacheStats = FunctionCacheTypes.CacheStats;
+    export import FunctionCacheOptions = FunctionCacheTypes.FunctionCacheOptions;
+    export import CachedFunction = FunctionCacheTypes.CachedFunction;
+    export import withCache = FunctionCacheTypes.withCache;
+    export import FunctionCache = FunctionCacheTypes.FunctionCache;
 }
 

package/lib/function-cache.js

@@ -0,0 +1,509 @@
+/**
+ * 通用函数缓存装饰器
+ *
+ * 🆕 v1.1.4: 新增函数缓存功能
+ * - 缓存任意异步函数的返回结果
+ * - 支持 TTL 过期
+ * - 支持自定义键生成
+ * - 支持命名空间隔离
+ * - 复用 monSQLize 缓存基础设施
+ *
+ * @module lib/function-cache
+ */
+
+const CacheFactory = require('./cache');
+
+// 并发去重映射（防止缓存击穿）
+const __inflightFunctions = new Map();
+
+// 缓存未命中的特殊标记（使用 Symbol 确保唯一性）
+const CACHE_MISS = Symbol('CACHE_MISS');
+
+/**
+ * 基础装饰器：为函数添加缓存能力
+ *
+ * @param {Function} fn - 要缓存的异步函数
+ * @param {Object} options - 缓存配置
+ * @param {number} [options.ttl=60000] - 缓存时间（毫秒）
+ * @param {Function} [options.keyBuilder] - 自定义键生成函数
+ * @param {Object} [options.cache] - 缓存实例（可选）
+ * @param {string} [options.namespace='fn'] - 命名空间
+ * @param {Function} [options.condition] - 条件缓存函数
+ * @param {boolean} [options.enableStats=true] - 启用统计
+ * @returns {Function} 包装后的函数
+ *
+ * @example
+ * // 基础用法
+ * const cachedFn = withCache(originalFn, { ttl: 60000 });
+ * const result = await cachedFn('arg1', 'arg2');
+ *
+ * // 自定义键生成
+ * const cachedFn = withCache(originalFn, {
+ *   ttl: 300000,
+ *   keyBuilder: (userId) => `user:${userId}`
+ * });
+ *
+ * // 条件缓存（只缓存非空结果）
+ * const cachedFn = withCache(originalFn, {
+ *   ttl: 60000,
+ *   condition: (result) => result && result.length > 0
+ * });
+ */
+function withCache(fn, options = {}) {
+    const {
+        ttl = 60000,
+        keyBuilder,
+        cache,
+        namespace = 'fn',
+        condition,
+        enableStats = true
+    } = options;
+
+    // 参数验证
+    if (typeof fn !== 'function') {
+        throw new Error('fn must be a function');
+    }
+    if (ttl !== undefined && (typeof ttl !== 'number' || ttl < 0)) {
+        throw new Error('ttl must be a non-negative number');
+    }
+    if (keyBuilder !== undefined && typeof keyBuilder !== 'function') {
+        throw new Error('keyBuilder must be a function');
+    }
+    if (condition !== undefined && typeof condition !== 'function') {
+        throw new Error('condition must be a function');
+    }
+
+    // 使用全局缓存或自定义缓存
+    const cacheInstance = cache || CacheFactory.createDefault();
+
+    // 验证缓存实例
+    if (!CacheFactory.isValidCache(cacheInstance)) {
+        throw new Error('Invalid cache instance: must implement CacheLike interface');
+    }
+
+    // 统计信息
+    const stats = {
+        hits: 0,
+        misses: 0,
+        errors: 0,
+        totalTime: 0,
+        calls: 0
+    };
+
+    // 返回包装后的函数
+    const wrappedFn = async function(...args) {
+        // 1. 生成缓存键
+        let cacheKey;
+        try {
+            cacheKey = keyBuilder
+                ? `${namespace}:${keyBuilder(...args)}`
+                : `${namespace}:${fn.name}:${CacheFactory.stableStringify(args)}`;
+        } catch (err) {
+            // 键生成失败，直接执行原函数
+            if (enableStats) stats.errors++;
+            return await fn.apply(this, args);
+        }
+
+        // 2. 尝试从缓存读取
+        const startTime = Date.now();
+        let cached = CACHE_MISS;
+        try {
+            const value = await cacheInstance.get(cacheKey);
+            // 只有当缓存中有这个键时才认为命中（即使值是 undefined）
+            // 我们需要区分"缓存未命中"和"缓存值是 undefined"
+            // 但是 cache.get() 无法区分，所以我们使用 exists() 来判断
+            const exists = await cacheInstance.exists(cacheKey);
+            if (exists) {
+                cached = value;
+            }
+        } catch (err) {
+            if (enableStats) stats.errors++;
+        }
+
+        if (cached !== CACHE_MISS) {
+            if (enableStats) {
+                stats.hits++;
+                stats.calls++;
+                stats.totalTime += Date.now() - startTime;
+            }
+            return cached;
+        }
+
+        // 3. 并发控制（防止缓存击穿）
+        if (__inflightFunctions.has(cacheKey)) {
+            try {
+                const result = await __inflightFunctions.get(cacheKey);
+                if (enableStats) {
+                    stats.hits++;
+                    stats.calls++;
+                }
+                return result;
+            } catch (err) {
+                // 并发请求失败，继续执行
+            }
+        }
+
+        // 4. 执行原函数
+        const promise = (async () => {
+            try {
+                const result = await fn.apply(this, args);
+
+                // 5. 条件缓存
+                let shouldCache = true;
+                if (condition) {
+                    try {
+                        shouldCache = condition(result);
+                    } catch (err) {
+                        // 条件函数失败，默认缓存
+                        if (enableStats) stats.errors++;
+                        shouldCache = true;
+                    }
+                }
+
+                if (shouldCache) {
+                    try {
+                        await cacheInstance.set(cacheKey, result, ttl);
+                    } catch (err) {
+                        if (enableStats) stats.errors++;
+                    }
+                }
+
+                return result;
+            } finally {
+                __inflightFunctions.delete(cacheKey);
+            }
+        })();
+
+        __inflightFunctions.set(cacheKey, promise);
+
+        try {
+            const result = await promise;
+            if (enableStats) {
+                stats.misses++;
+                stats.calls++;
+                stats.totalTime += Date.now() - startTime;
+            }
+            return result;
+        } catch (err) {
+            if (enableStats) {
+                stats.errors++;
+                stats.calls++;
+            }
+            throw err;
+        }
+    };
+
+    // 挂载统计方法
+    wrappedFn.getCacheStats = () => ({
+        ...stats,
+        hitRate: stats.hits / (stats.hits + stats.misses) || 0,
+        avgTime: stats.totalTime / stats.calls || 0
+    });
+
+    return wrappedFn;
+}
+
+/**
+ * 函数缓存管理类
+ *
+ * @class FunctionCache
+ *
+ * @example
+ * const fnCache = new FunctionCache(msq);
+ *
+ * // 注册函数
+ * fnCache.register('getUserProfile', getUserProfileFn, { ttl: 300000 });
+ *
+ * // 执行函数
+ * const profile = await fnCache.execute('getUserProfile', 'user123');
+ *
+ * // 失效缓存
+ * await fnCache.invalidate('getUserProfile', 'user123');
+ *
+ * // 查看统计
+ * const stats = fnCache.getStats('getUserProfile');
+ */
+class FunctionCache {
+    /**
+     * 构造函数
+     * @param {Object} msq - MonSQLize 实例（可选）
+     * @param {Object} options - 配置选项
+     * @param {string} [options.namespace='action'] - 命名空间
+     * @param {number} [options.defaultTTL=60000] - 默认 TTL（毫秒）
+     * @param {boolean} [options.enableStats=true] - 启用统计
+     */
+    constructor(msq, options = {}) {
+        // 参数验证
+        if (options && typeof options !== 'object') {
+            throw new Error('options must be an object');
+        }
+
+        this.cache = msq ? msq.getCache() : CacheFactory.createDefault();
+
+        // 验证缓存实例
+        if (!CacheFactory.isValidCache(this.cache)) {
+            throw new Error('Invalid cache instance from MonSQLize');
+        }
+
+        this.functions = new Map();
+        this.stats = new Map();
+        this.options = {
+            namespace: options.namespace || 'action',
+            defaultTTL: options.defaultTTL || 60000,
+            enableStats: options.enableStats !== false
+        };
+
+        // 参数验证
+        if (typeof this.options.namespace !== 'string') {
+            throw new Error('namespace must be a string');
+        }
+        if (typeof this.options.defaultTTL !== 'number' || this.options.defaultTTL < 0) {
+            throw new Error('defaultTTL must be a non-negative number');
+        }
+    }
+
+    /**
+     * 注册函数
+     * @param {string} name - 函数名称
+     * @param {Function} fn - 函数实现
+     * @param {Object} options - 缓存配置
+     * @param {number} [options.ttl] - 缓存过期时间（毫秒）
+     * @param {Array<string>} [options.collections] - 依赖的 MongoDB 集合名称（自动失效）
+     */
+    register(name, fn, options = {}) {
+        if (!name || typeof name !== 'string') {
+            throw new Error('Function name must be a non-empty string');
+        }
+        if (typeof fn !== 'function') {
+            throw new Error('fn must be a function');
+        }
+        if (options && typeof options !== 'object') {
+            throw new Error('options must be an object');
+        }
+
+        const cachedFn = withCache(fn, {
+            ...options,
+            cache: this.cache,
+            namespace: `${this.options.namespace}:${name}`,
+            ttl: options.ttl !== undefined ? options.ttl : this.options.defaultTTL
+        });
+
+        this.functions.set(name, cachedFn);
+
+        if (this.options.enableStats) {
+            this.stats.set(name, {
+                hits: 0,
+                misses: 0,
+                errors: 0,
+                calls: 0,
+                totalTime: 0
+            });
+        }
+
+        // 🆕 v1.1.4: 建立集合依赖关系（用于自动失效）
+        if (options.collections && Array.isArray(options.collections)) {
+            this._registerDependencies(name, options.collections);
+        }
+    }
+
+    /**
+     * 🆕 v1.1.4: 注册函数与集合的依赖关系
+     * @private
+     * @param {string} functionName - 函数名称
+     * @param {Array<string>} collections - 集合名称列表
+     */
+    _registerDependencies(functionName, collections) {
+        for (const collection of collections) {
+            const depsKey = `fn_deps:${collection}`;
+
+            // 从缓存中读取已有的依赖列表
+            let existingDeps = [];
+            try {
+                const cached = this.cache.get ? this.cache.get(depsKey) : null;
+                if (cached && Array.isArray(cached)) {
+                    existingDeps = cached;
+                }
+            } catch (err) {
+                // 读取失败，使用空数组
+            }
+
+            // 添加新的函数名（避免重复）
+            if (!existingDeps.includes(functionName)) {
+                existingDeps.push(functionName);
+
+                // 存储依赖关系（永久存储，无 TTL）
+                try {
+                    if (this.cache.set) {
+                        this.cache.set(depsKey, existingDeps, 0);
+                    }
+                } catch (err) {
+                    // 存储失败不影响注册
+                    if (this.msq && this.msq.logger) {
+                        this.msq.logger.warn('[FunctionCache] 注册依赖关系失败', {
+                            collection,
+                            function: functionName,
+                            error: err.message
+                        });
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * 执行函数
+     * @param {string} name - 函数名称
+     * @param {...any} args - 函数参数
+     * @returns {Promise<any>}
+     */
+    async execute(name, ...args) {
+        const fn = this.functions.get(name);
+        if (!fn) {
+            throw new Error(`Function '${name}' not registered`);
+        }
+
+        const startTime = Date.now();
+        try {
+            const result = await fn(...args);
+
+            if (this.options.enableStats) {
+                const stats = this.stats.get(name);
+                if (stats) {
+                    stats.calls++;
+                    stats.totalTime += Date.now() - startTime;
+                }
+            }
+
+            return result;
+        } catch (err) {
+            if (this.options.enableStats) {
+                const stats = this.stats.get(name);
+                if (stats) {
+                    stats.errors++;
+                    stats.calls++;
+                }
+            }
+            throw err;
+        }
+    }
+
+    /**
+     * 失效缓存
+     * @param {string} name - 函数名称
+     * @param {...any} args - 函数参数
+     */
+    async invalidate(name, ...args) {
+        if (!name || typeof name !== 'string') {
+            throw new Error('Function name must be a non-empty string');
+        }
+
+        const fn = this.functions.get(name);
+        if (!fn) {
+            throw new Error(`Function '${name}' not registered`);
+        }
+
+        // 获取原始函数（从缓存的函数中提取）
+        const originalFn = fn;
+
+        // 缓存键格式：${namespace}:${name}:${fnName}:${args}
+        // 但是因为我们在 register 时已经将 name 加入 namespace，
+        // withCache 会再拼接 fn.name，所以这里需要使用正确的完整键
+        // 实际键格式：${this.options.namespace}:${name}:${fn.name}:${args}
+
+        // 构建通配符模式来删除所有匹配的缓存
+        const pattern = `${this.options.namespace}:${name}:*${CacheFactory.stableStringify(args)}*`;
+        await this.cache.delPattern(pattern);
+    }
+
+    /**
+     * 批量失效缓存
+     * @param {string} pattern - 失效模式（支持通配符 *）
+     * @returns {Promise<number>} 删除的缓存条目数
+     */
+    async invalidatePattern(pattern) {
+        if (!pattern || typeof pattern !== 'string') {
+            throw new Error('Pattern must be a non-empty string');
+        }
+
+        const fullPattern = `${this.options.namespace}:${pattern}`;
+        return await this.cache.delPattern(fullPattern);
+    }
+
+    /**
+     * 获取统计信息
+     * @param {string} [name] - 函数名称（可选）
+     * @returns {Object|null}
+     */
+    getStats(name) {
+        if (name) {
+            const stats = this.stats.get(name);
+            if (!stats) return null;
+            return {
+                ...stats,
+                hitRate: stats.hits / (stats.hits + stats.misses) || 0,
+                avgTime: stats.totalTime / stats.calls || 0
+            };
+        }
+
+        const allStats = {};
+        for (const [fnName, stats] of this.stats.entries()) {
+            allStats[fnName] = {
+                ...stats,
+                hitRate: stats.hits / (stats.hits + stats.misses) || 0,
+                avgTime: stats.totalTime / stats.calls || 0
+            };
+        }
+        return allStats;
+    }
+
+    /**
+     * 列出所有已注册的函数
+     * @returns {string[]}
+     */
+    list() {
+        return Array.from(this.functions.keys());
+    }
+
+    /**
+     * 重置统计信息
+     * @param {string} [name] - 函数名称（可选）
+     */
+    resetStats(name) {
+        if (name) {
+            const stats = this.stats.get(name);
+            if (stats) {
+                Object.assign(stats, {
+                    hits: 0,
+                    misses: 0,
+                    errors: 0,
+                    calls: 0,
+                    totalTime: 0
+                });
+            }
+        } else {
+            for (const stats of this.stats.values()) {
+                Object.assign(stats, {
+                    hits: 0,
+                    misses: 0,
+                    errors: 0,
+                    calls: 0,
+                    totalTime: 0
+                });
+            }
+        }
+    }
+
+    /**
+     * 清空所有已注册的函数
+     */
+    clear() {
+        this.functions.clear();
+        this.stats.clear();
+    }
+}
+
+module.exports = {
+    withCache,
+    FunctionCache
+};
+

package/lib/index.js

@@ -918,6 +918,10 @@ module.exports = class {
 // ========== 导出 Model 类 ==========
 module.exports.Model = require('./model');
 
+// ========== 导出 ConnectionPoolManager ==========
+// 🆕 v1.0.8: 多连接池管理
+module.exports.ConnectionPoolManager = require('./infrastructure/ConnectionPoolManager');
+
 // ========== 导出表达式工厂函数 ==========
 // 🆕 v1.0.9: 统一表达式语法
 const createExpression = require('./expression');
@@ -925,3 +929,11 @@ const createExpression = require('./expression');
 // 导出表达式创建函数
 module.exports.expr = createExpression;             // v1.0.9: 统一表达式语法 ⭐
 module.exports.createExpression = createExpression; // 完整版别名
+
+// ========== 导出函数缓存 ==========
+// 🆕 v1.1.4: 通用函数缓存
+const { withCache, FunctionCache } = require('./function-cache');
+
+module.exports.withCache = withCache;
+module.exports.FunctionCache = FunctionCache;
+

package/lib/infrastructure/ConnectionPoolManager.js

@@ -203,17 +203,18 @@ class ConnectionPoolManager {
      * @param {Object} options - 选项
      * @param {string} [options.pool] - 手动指定连接池名称
      * @param {Object} [options.poolPreference] - 连接池偏好
-     * @returns {{name: string, client: MongoClient}}
+      * @returns {{name: string, client: MongoClient, db: Db, collection: Function}}
      * @throws {Error} 如果无可用连接池
      */
     selectPool(operation, options = {}) {
         // 手动指定连接池
         if (options.pool) {
-            const client = this._getPool(options.pool);
-            if (!client) {
+            const poolData = this._pools.get(options.pool);
+            if (!poolData) {
                 throw new Error(`Pool '${options.pool}' not found`);
             }
-            return { name: options.pool, client };  // 🔴 修复问题3：返回 {name, client}
+            const config = this._configs.get(options.pool);
+            return this._createPoolResult(options.pool, poolData.client, config);
         }
 
         // 获取健康的连接池列表
@@ -240,15 +241,45 @@ class ConnectionPoolManager {
             ...options
         });
 
-        const client = this._getPool(poolName);
-        if (!client) {
+        const poolData = this._pools.get(poolName);
+        if (!poolData) {
             throw new Error(`Selected pool '${poolName}' not available`);
         }
 
         // 记录统计
         this._stats.recordSelection(poolName, operation);
 
-        return { name: poolName, client };
+        const config = this._configs.get(poolName);
+        return this._createPoolResult(poolName, poolData.client, config);
+    }
+
+    /**
+     * 创建连接池结果对象（包含 db 和 collection 访问器）
+     *
+     * @private
+     * @param {string} name - 连接池名称
+     * @param {MongoClient} client - MongoDB 客户端
+     * @param {Object} config - 连接池配置
+     * @returns {{name: string, client: MongoClient, db: Db, collection: Function}}
+     */
+    _createPoolResult(name, client, config) {
+        // 从 URI 中提取数据库名称
+        let dbName;
+        try {
+            const url = new URL(config.uri);
+            dbName = url.pathname.slice(1) || 'test';
+        } catch (err) {
+            dbName = 'test';
+        }
+
+        const db = client.db(dbName);
+
+        return {
+            name,
+            client,
+            db,
+            collection: (collectionName) => db.collection(collectionName)
+        };
     }
 
     /**

package/lib/multi-level-cache.js

@@ -157,10 +157,33 @@ class MultiLevelCache {
   }
 
   async delPattern(pattern) {
-    const deleted = await this.local.delPattern(pattern);
+    let deleted = 0;
+
+    // 删除本地缓存
+    try {
+      deleted = await this.local.delPattern(pattern);
+    } catch(err) {
+      // 忽略本地删除错误
+    }
+
+    // 删除远端缓存（如果存在）
+    if (this.remote && typeof this.remote.delPattern === 'function') {
+      try {
+        await this._withTimeout(this.remote.delPattern(pattern));
+      } catch(err) {
+        // 远端删除失败，降级处理
+      }
+    }
+
     // 向集群广播（可选）
-    try { if (this.publish) this.publish({ type: 'invalidate', pattern, ts: Date.now() }); } catch(_) {}
-    // 默认不在远端做大规模扫描，交由 TTL 自然过期或使用远端的 tag 机制（未来可扩展）
+    try {
+      if (this.publish) {
+        this.publish({ type: 'invalidate', pattern, ts: Date.now() });
+      }
+    } catch(err) {
+      // 忽略广播错误
+    }
+
     return deleted;
   }
 

package/lib/utils/objectid-converter.js

@@ -123,9 +123,16 @@ function convertObjectIdStrings(obj, fieldPath = '', depth = 0, visited = new We
     logger = null,
     excludeFields = [],
     customFieldPatterns = [],
-    maxDepth = 10
+    maxDepth = 10,
+    verbose = false,  // 详细日志模式（默认关闭）
+    silent = true,    // 🆕 静默模式（默认开启，不输出任何日志）
+    _conversionStats = null  // 内部统计对象（递归传递）
   } = options;
 
+  // 初始化统计（仅在顶层调用）
+  const stats = _conversionStats || { count: 0, fields: [] };
+  const isTopLevel = depth === 0 && !_conversionStats;
+
   try {
     // 1. 深度保护（防止栈溢出）
     if (depth > maxDepth) {
@@ -157,7 +164,15 @@ function convertObjectIdStrings(obj, fieldPath = '', depth = 0, visited = new We
         const hexString = obj.toString();
         if (isValidObjectIdString(hexString)) {
           const converted = new ObjectId(hexString);
-          if (logger && logger.debug) {
+
+          // 更新统计
+          stats.count++;
+          if (stats.fields.length < 5) {  // 只记录前5个字段路径
+            stats.fields.push(fieldPath);
+          }
+
+          // 详细模式：每次转换都输出日志（仅在非静默模式下）
+          if (!silent && verbose && logger && logger.debug) {
             logger.debug('[ObjectId Converter] Cross-version ObjectId converted', {
               from: obj.constructor.name,
               to: 'ObjectId',
@@ -165,6 +180,7 @@ function convertObjectIdStrings(obj, fieldPath = '', depth = 0, visited = new We
               fieldPath
             });
           }
+
           return converted;
         }
       } catch (error) {
@@ -212,7 +228,10 @@ function convertObjectIdStrings(obj, fieldPath = '', depth = 0, visited = new We
       let hasConverted = false;
       const converted = obj.map((item, index) => {
         const itemPath = `${fieldPath}[${index}]`;
-        const newItem = convertObjectIdStrings(item, itemPath, depth + 1, visited, options);
+        const newItem = convertObjectIdStrings(item, itemPath, depth + 1, visited, {
+          ...options,
+          _conversionStats: stats  // 传递统计对象
+        });
         if (newItem !== item) {
           hasConverted = true;
         }
@@ -276,7 +295,10 @@ function convertObjectIdStrings(obj, fieldPath = '', depth = 0, visited = new We
           }
         } else {
           // 6.5 递归处理
-          const newValue = convertObjectIdStrings(value, currentPath, depth + 1, visited, options);
+          const newValue = convertObjectIdStrings(value, currentPath, depth + 1, visited, {
+            ...options,
+            _conversionStats: stats  // 传递统计对象
+          });
           if (newValue !== value) {
             hasConverted = true;
           }
@@ -302,6 +324,18 @@ function convertObjectIdStrings(obj, fieldPath = '', depth = 0, visited = new We
     }
     // 异常时返回原值，确保不中断流程
     return obj;
+  } finally {
+    // 顶层调用：输出转换摘要（仅在非静默模式且有转换时）
+    if (!silent && isTopLevel && stats.count > 0 && logger && logger.debug) {
+      const message = stats.count === 1
+        ? 'Converted 1 cross-version ObjectId'
+        : `Converted ${stats.count} cross-version ObjectIds`;
+
+      logger.debug(`[ObjectId Converter] ${message}`, {
+        count: stats.count,
+        sampleFields: stats.fields.slice(0, 3)  // 只显示前3个字段示例
+      });
+    }
   }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "monsqlize",
-  "version": "1.1.1",
-  "description": "A lightweight MongoDB ORM with multi-level caching, transaction support, distributed features, Saga distributed transactions, and unified expression system with 122 operators (100% MongoDB support)",
+  "version": "1.1.4",
+  "description": "A lightweight MongoDB ORM with multi-level caching, transaction support, distributed features, Saga distributed transactions, unified expression system with 122 operators, and universal function caching (100% MongoDB support)",
   "main": "lib/index.js",
   "module": "index.mjs",
   "type": "commonjs",