monsqlize 1.0.0 → 1.0.2

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');
         }
     }