monsqlize 1.0.1 → 1.0.5

package/lib/slow-query-log/mongodb-storage.js

@@ -0,0 +1,323 @@
+/**
+ * MongoDB慢查询日志存储实现
+ * 实现方案B（更新记录去重）
+ *
+ * @version 1.3.0
+ * @since 2025-12-22
+ */
+
+const { ISlowQueryLogStorage } = require('./base-storage');
+const { generateQueryHash } = require('./query-hash');
+
+class MongoDBSlowQueryLogStorage extends ISlowQueryLogStorage {
+  /**
+   * 创建MongoDB存储实例
+   * @param {Object} config - 存储配置
+   * @param {string} [config.uri] - MongoDB连接URI（独立连接时）
+   * @param {string} [config.database='admin'] - 存储数据库
+   * @param {string} [config.collection='slow_query_logs'] - 存储集合
+   * @param {number} [config.ttl=604800] - TTL过期时间（秒）
+   * @param {string} [config.ttlField='lastSeen'] - TTL字段
+   * @param {Object} [client] - MongoDB客户端（复用连接时）
+   * @param {Object} [logger] - 日志记录器
+   */
+  constructor(config, client, logger) {
+    super();
+    this.config = config;
+    this.client = client;  // 可能是复用的业务连接
+    this.ownClient = null;  // 独立连接（如果创建）
+    this.collection = null;
+    this.logger = logger || console;
+    this.initialized = false;
+  }
+
+  /**
+   * 初始化存储（连接+创建索引）
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    if (this.initialized) {
+      return;
+    }
+
+    try {
+      // 如果没有传入client，创建独立连接
+      if (!this.client) {
+        if (!this.config.uri) {
+          throw new Error('MongoDB URI is required when client is not provided');
+        }
+
+        const { MongoClient } = require('mongodb');
+        this.ownClient = await MongoClient.connect(this.config.uri);
+        this.client = this.ownClient;
+
+        if (this.logger.info) {
+          this.logger.info(`[SlowQueryLog] Connected to MongoDB: ${this.config.uri}`);
+        }
+      }
+
+      // 获取数据库和集合
+      const dbName = this.config.database || 'admin';
+      const collName = this.config.collection || 'slow_query_logs';
+
+      this.db = this.client.db(dbName);
+      this.collection = this.db.collection(collName);
+
+      // 创建索引
+      await this.setupIndexes();
+
+      this.initialized = true;
+
+      if (this.logger.info) {
+        this.logger.info(
+          `[SlowQueryLog] Initialized MongoDB storage: ${dbName}.${collName}`
+        );
+      }
+    } catch (err) {
+      if (this.logger.error) {
+        this.logger.error('[SlowQueryLog] Failed to initialize MongoDB storage:', err);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * 创建索引
+   * @returns {Promise<void>}
+   */
+  async setupIndexes() {
+    try {
+      // 索引1：queryHash唯一索引（去重关键）
+      await this.collection.createIndex(
+        { queryHash: 1 },
+        { unique: true, name: 'idx_queryHash_unique' }
+      );
+
+      // 索引2：lastSeen TTL索引（自动过期）
+      const ttl = this.config.ttl || 7 * 24 * 3600;
+      const ttlField = this.config.ttlField || 'lastSeen';
+
+      await this.collection.createIndex(
+        { [ttlField]: 1 },
+        {
+          name: 'idx_lastSeen_ttl',
+          expireAfterSeconds: ttl
+        }
+      );
+
+      // 索引3：按集合查询（辅助索引）
+      await this.collection.createIndex(
+        { db: 1, collection: 1 },
+        { name: 'idx_db_collection' }
+      );
+
+      // 索引4：按执行次数查询（找高频慢查询）
+      await this.collection.createIndex(
+        { count: -1 },
+        { name: 'idx_count_desc' }
+      );
+
+      if (this.logger.debug) {
+        this.logger.debug('[SlowQueryLog] MongoDB indexes created successfully');
+      }
+    } catch (err) {
+      // 索引创建失败不应该阻塞功能
+      if (this.logger.warn) {
+        this.logger.warn('[SlowQueryLog] Failed to create some indexes:', err.message);
+      }
+    }
+  }
+
+  /**
+   * 保存单条慢查询日志（upsert）
+   * @param {Object} log - 慢查询日志对象
+   * @returns {Promise<void>}
+   */
+  async save(log) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+
+    const queryHash = generateQueryHash(log);
+    await this.upsert(queryHash, log);
+  }
+
+  /**
+   * 批量保存慢查询日志（bulkWrite + upsert）
+   * @param {Object[]} logs - 慢查询日志数组
+   * @returns {Promise<void>}
+   */
+  async saveBatch(logs) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+
+    if (!logs || logs.length === 0) {
+      return;
+    }
+
+    try {
+      // 构建bulkWrite操作数组
+      const operations = logs.map(log => {
+        const queryHash = generateQueryHash(log);
+        const timestamp = log.timestamp || new Date();
+        const executionTimeMs = log.executionTimeMs || log.ms || 0;
+
+        return {
+          updateOne: {
+            filter: { queryHash },
+            update: {
+              $set: {
+                lastSeen: timestamp,
+                lastExecution: {
+                  executionTimeMs,
+                  timestamp,
+                  metadata: log.metadata || {}
+                }
+              },
+              $inc: {
+                count: 1,
+                totalTimeMs: executionTimeMs
+              },
+              $min: { minTimeMs: executionTimeMs },
+              $max: { maxTimeMs: executionTimeMs },
+              $setOnInsert: {
+                queryHash,
+                db: log.db,
+                collection: log.collection || log.coll,
+                operation: log.operation || log.op,
+                queryShape: log.queryShape || {},
+                type: log.type || 'mongodb',
+                firstSeen: timestamp
+              }
+            },
+            upsert: true
+          }
+        };
+      });
+
+      // 批量写入（ordered=false 允许部分失败）
+      const result = await this.collection.bulkWrite(operations, { ordered: false });
+
+      if (this.logger.debug) {
+        this.logger.debug(
+          `[SlowQueryLog] Batch saved: ${result.upsertedCount} inserted, ` +
+          `${result.modifiedCount} updated`
+        );
+      }
+    } catch (err) {
+      if (this.logger.error) {
+        this.logger.error('[SlowQueryLog] Failed to save batch:', err);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * 单条upsert操作
+   * @param {string} queryHash - 查询Hash
+   * @param {Object} log - 慢查询日志对象
+   * @returns {Promise<void>}
+   */
+  async upsert(queryHash, log) {
+    const timestamp = log.timestamp || new Date();
+    const executionTimeMs = log.executionTimeMs || log.ms || 0;
+
+    await this.collection.updateOne(
+      { queryHash },
+      {
+        $set: {
+          lastSeen: timestamp,
+          lastExecution: {
+            executionTimeMs,
+            timestamp,
+            metadata: log.metadata || {}
+          }
+        },
+        $inc: {
+          count: 1,
+          totalTimeMs: executionTimeMs
+        },
+        $min: { minTimeMs: executionTimeMs },
+        $max: { maxTimeMs: executionTimeMs },
+        $setOnInsert: {
+          queryHash,
+          db: log.db,
+          collection: log.collection || log.coll,
+          operation: log.operation || log.op,
+          queryShape: log.queryShape || {},
+          type: log.type || 'mongodb',
+          firstSeen: timestamp
+        }
+      },
+      { upsert: true }
+    );
+  }
+
+  /**
+   * 查询慢查询日志
+   * @param {Object} filter - 查询条件
+   * @param {Object} options - 查询选项
+   * @returns {Promise<Object[]>}
+   */
+  async query(filter = {}, options = {}) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+
+    try {
+      const cursor = this.collection.find(filter);
+
+      if (options.sort) {
+        cursor.sort(options.sort);
+      }
+      if (options.limit) {
+        cursor.limit(options.limit);
+      }
+      if (options.skip) {
+        cursor.skip(options.skip);
+      }
+
+      const results = await cursor.toArray();
+
+      // 计算avgTimeMs（动态计算）
+      return results.map(doc => ({
+        ...doc,
+        avgTimeMs: doc.count > 0 ? Math.round(doc.totalTimeMs / doc.count) : 0
+      }));
+    } catch (err) {
+      if (this.logger.error) {
+        this.logger.error('[SlowQueryLog] Failed to query:', err);
+      }
+      return [];
+    }
+  }
+
+  /**
+   * 关闭连接
+   * @returns {Promise<void>}
+   */
+  async close() {
+    // 只关闭自己创建的连接，不关闭复用的连接
+    if (this.ownClient) {
+      try {
+        await this.ownClient.close();
+        if (this.logger.info) {
+          this.logger.info('[SlowQueryLog] MongoDB connection closed');
+        }
+      } catch (err) {
+        if (this.logger.error) {
+          this.logger.error('[SlowQueryLog] Failed to close MongoDB connection:', err);
+        }
+      }
+      this.ownClient = null;
+    }
+
+    this.client = null;
+    this.collection = null;
+    this.initialized = false;
+  }
+}
+
+module.exports = { MongoDBSlowQueryLogStorage };
+

package/lib/slow-query-log/query-hash.js

@@ -0,0 +1,38 @@
+/**
+ * 慢查询Hash生成工具
+ * 用于生成queryHash（去重标识）
+ *
+ * @version 1.3.0
+ * @since 2025-12-22
+ */
+
+const crypto = require('crypto');
+
+/**
+ * 生成慢查询的唯一Hash标识
+ * @param {Object} log - 慢查询日志对象
+ * @param {string} log.db - 数据库名
+ * @param {string} log.collection - 集合名
+ * @param {string} log.operation - 操作类型
+ * @param {Object} log.queryShape - 查询模式（已脱敏）
+ * @returns {string} 16位Hash字符串
+ */
+function generateQueryHash(log) {
+  // 构建唯一键（不包含executionTimeMs、timestamp等动态字段）
+  const key = JSON.stringify({
+    db: log.db || '',
+    collection: log.collection || log.coll || '',
+    operation: log.operation || log.op || '',
+    queryShape: log.queryShape || {}
+  });
+
+  // 生成SHA256 Hash，取前16位
+  return crypto
+    .createHash('sha256')
+    .update(key)
+    .digest('hex')
+    .substring(0, 16);
+}
+
+module.exports = { generateQueryHash };
+

package/lib/transaction/DistributedCacheLockManager.js

@@ -2,17 +2,26 @@
  * 分布式缓存锁管理器
  * 基于 Redis 实现跨实例的事务缓存锁，确保事务隔离性
  *
- * @example
- * const lockManager = new DistributedCacheLockManager({
- *   redis: redisInstance,
- *   lockKeyPrefix: 'monsqlize:cache:lock:'
- * });
+ * v1.4.0 新增：业务级分布式锁支持
+ * - withLock(): 自动管理锁生命周期
+ * - acquireLock(): 手动获取锁（阻塞重试）
+ * - tryAcquireLock(): 尝试获取锁（不阻塞）
  *
+ * @example
+ * // 事务缓存锁（原有功能）
  * await lockManager.addLock('user:1', session);
  * const isLocked = await lockManager.isLocked('user:1');
  * await lockManager.releaseLocks(session);
+ *
+ * // 业务锁（v1.4.0 新增）
+ * await lockManager.withLock('inventory:SKU123', async () => {
+ *   // 临界区代码
+ * });
  */
 
+const Lock = require('../lock/Lock');
+const { LockAcquireError } = require('../lock/errors');
+
 class DistributedCacheLockManager {
     /**
      * @param {Object} options
@@ -233,6 +242,232 @@ class DistributedCacheLockManager {
             this.logger.info('[DistributedCacheLockManager] Stopped');
         }
     }
+
+    // ==================== 业务锁 API (v1.4.0) ====================
+
+    /**
+     * 业务锁：自动管理锁生命周期（推荐）
+     * @param {string} key - 锁的唯一标识
+     * @param {Function} callback - 获取锁后执行的函数
+     * @param {Object} [options] - 锁选项
+     * @param {number} [options.ttl=10000] - 锁过期时间（毫秒）
+     * @param {number} [options.retryTimes=3] - 重试次数
+     * @param {number} [options.retryDelay=100] - 重试间隔（毫秒）
+     * @param {boolean} [options.fallbackToNoLock=false] - Redis不可用时降级为无锁执行
+     * @returns {Promise<*>} callback 的返回值
+     */
+    async withLock(key, callback, options = {}) {
+        try {
+            const lock = await this.acquireLock(key, options);
+            try {
+                return await callback();
+            } finally {
+                // 释放失败不应阻塞业务（锁会在 TTL 后自动过期）
+                await lock.release().catch(err => {
+                    if (this.logger) {
+                        this.logger.warn(`[Lock] Release failed: ${key}`, err);
+                    }
+                });
+            }
+        } catch (error) {
+            // Redis 连接问题检测
+            if (this._isRedisConnectionError(error)) {
+                if (options.fallbackToNoLock) {
+                    if (this.logger) {
+                        this.logger.warn(`[Lock] Redis unavailable, proceeding without lock: ${key}`);
+                    }
+                    return callback();
+                }
+                throw new LockAcquireError(`Redis unavailable: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+
+    /**
+     * 业务锁：手动获取锁（阻塞重试）
+     * @param {string} key - 锁的唯一标识
+     * @param {Object} [options] - 锁选项
+     * @returns {Promise<Lock>}
+     */
+    async acquireLock(key, options = {}) {
+        const ttl = options.ttl || 10000; // 默认 10 秒
+        const retryTimes = options.retryTimes ?? 3;
+        const retryDelay = options.retryDelay || 100;
+        const lockId = this._generateLockId();
+        const fullKey = this.lockKeyPrefix + key;
+
+        for (let attempt = 0; attempt <= retryTimes; attempt++) {
+            try {
+                // 使用 SET NX PX 原子操作（毫秒级 TTL）
+                const result = await this.redis.set(
+                    fullKey,
+                    lockId,
+                    'PX', ttl,  // PX = 毫秒
+                    'NX'
+                );
+
+                if (result === 'OK') {
+                    this.stats.locksAcquired++;
+                    if (this.logger) {
+                        this.logger.debug(`[Lock] Acquired: ${key}`);
+                    }
+                    return new Lock(key, lockId, this, ttl);
+                }
+
+                // 最后一次尝试失败
+                if (attempt === retryTimes) {
+                    break;
+                }
+
+                // 等待后重试
+                await this._sleep(retryDelay);
+            } catch (error) {
+                // 如果是最后一次尝试，抛出错误
+                if (attempt === retryTimes) {
+                    throw error;
+                }
+                // 否则等待后重试
+                await this._sleep(retryDelay);
+            }
+        }
+
+        this.stats.errors++;
+        throw new LockAcquireError(`Failed to acquire lock: ${key}`);
+    }
+
+    /**
+     * 业务锁：尝试获取锁（不阻塞）
+     * @param {string} key - 锁的唯一标识
+     * @param {Object} [options] - 锁选项（不包含 retryTimes）
+     * @returns {Promise<Lock|null>} Lock对象或null
+     */
+    async tryAcquireLock(key, options = {}) {
+        const ttl = options.ttl || 10000;
+        const lockId = this._generateLockId();
+        const fullKey = this.lockKeyPrefix + key;
+
+        try {
+            const result = await this.redis.set(
+                fullKey,
+                lockId,
+                'PX', ttl,
+                'NX'
+            );
+
+            if (result === 'OK') {
+                this.stats.locksAcquired++;
+                if (this.logger) {
+                    this.logger.debug(`[Lock] Acquired (try): ${key}`);
+                }
+                return new Lock(key, lockId, this, ttl);
+            }
+
+            return null;
+        } catch (error) {
+            if (this.logger) {
+                this.logger.error(`[Lock] Try acquire error: ${key}`, error.message);
+            }
+            return null;
+        }
+    }
+
+    /**
+     * 释放单个锁（由 Lock 对象调用）
+     * @param {string} key - 锁标识
+     * @param {string} lockId - 锁ID
+     * @returns {Promise<boolean>}
+     */
+    async releaseLock(key, lockId) {
+        const fullKey = this.lockKeyPrefix + key;
+
+        try {
+            // 使用 Lua 脚本确保原子性（只释放自己的锁）
+            const luaScript = `
+                if redis.call("get", KEYS[1]) == ARGV[1] then
+                    return redis.call("del", KEYS[1])
+                else
+                    return 0
+                end
+            `;
+
+            const result = await this.redis.eval(luaScript, 1, fullKey, lockId);
+
+            if (result === 1) {
+                this.stats.locksReleased++;
+                if (this.logger) {
+                    this.logger.debug(`[Lock] Released: ${key}`);
+                }
+                return true;
+            }
+
+            return false;
+        } catch (error) {
+            this.stats.errors++;
+            if (this.logger) {
+                this.logger.error(`[Lock] Release error: ${key}`, error.message);
+            }
+            return false;
+        }
+    }
+
+    /**
+     * 续期（延长锁的过期时间）
+     * @param {string} key - 锁标识
+     * @param {string} lockId - 锁ID
+     * @param {number} ttl - 新的过期时间（毫秒）
+     * @returns {Promise<boolean>}
+     */
+    async renewLock(key, lockId, ttl) {
+        const fullKey = this.lockKeyPrefix + key;
+
+        try {
+            // 使用 Lua 脚本确保只续期自己的锁
+            const luaScript = `
+                if redis.call("get", KEYS[1]) == ARGV[1] then
+                    return redis.call("pexpire", KEYS[1], ARGV[2])
+                else
+                    return 0
+                end
+            `;
+
+            const result = await this.redis.eval(luaScript, 1, fullKey, lockId, ttl);
+            return result === 1;
+        } catch (error) {
+            if (this.logger) {
+                this.logger.error(`[Lock] Renew error: ${key}`, error.message);
+            }
+            return false;
+        }
+    }
+
+    /**
+     * 生成唯一锁ID
+     * @private
+     */
+    _generateLockId() {
+        return `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    }
+
+    /**
+     * 延迟
+     * @private
+     */
+    _sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+
+    /**
+     * 检测是否是 Redis 连接错误
+     * @private
+     */
+    _isRedisConnectionError(error) {
+        const msg = error.message || '';
+        return msg.includes('ECONNREFUSED') ||
+               msg.includes('ETIMEDOUT') ||
+               msg.includes('ENOTFOUND') ||
+               msg.includes('Connection is closed');
+    }
 }
 
 module.exports = DistributedCacheLockManager;

package/lib/transaction/Transaction.js

@@ -216,7 +216,7 @@ class Transaction {
         if (this.lockManager && this.session) {
             this.lockManager.releaseLocks(this.session);
             this.lockedKeys.clear();
-            this.logger?.debug(`[Transaction] Released all cache locks`);
+            this.logger?.debug('[Transaction] Released all cache locks');
         }
     }